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 * Threading in GDB:: Using Python threads in GDB.
194 * Exception Handling:: How Python exceptions are translated.
195 * Values From Inferior:: Python representation of values.
196 * Types In Python:: Python representation of types.
197 * Pretty Printing API:: Pretty-printing values.
198 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
199 * Writing a Pretty-Printer:: Writing a Pretty-Printer.
200 * Type Printing API:: Pretty-printing types.
201 * Frame Filter API:: Filtering Frames.
202 * Frame Decorator API:: Decorating Frames.
203 * Writing a Frame Filter:: Writing a Frame Filter.
204 * Unwinding Frames in Python:: Writing frame unwinder.
205 * Xmethods In Python:: Adding and replacing methods of C++ classes.
206 * Xmethod API:: Xmethod types.
207 * Writing an Xmethod:: Writing an xmethod.
208 * Inferiors In Python:: Python representation of inferiors (processes)
209 * Events In Python:: Listening for events from @value{GDBN}.
210 * Threads In Python:: Accessing inferior threads from Python.
211 * Recordings In Python:: Accessing recordings from Python.
212 * CLI Commands In Python:: Implementing new CLI commands in Python.
213 * GDB/MI Commands In Python:: Implementing new @sc{gdb/mi} commands in Python.
214 * GDB/MI Notifications In Python:: Implementing new @sc{gdb/mi} notifications in Python.
215 * Parameters In Python:: Adding new @value{GDBN} parameters.
216 * Functions In Python:: Writing new convenience functions.
217 * Progspaces In Python:: Program spaces.
218 * Objfiles In Python:: Object files.
219 * Frames In Python:: Accessing inferior stack frames from Python.
220 * Blocks In Python:: Accessing blocks from Python.
221 * Symbols In Python:: Python representation of symbols.
222 * Symbol Tables In Python:: Python representation of symbol tables.
223 * Line Tables In Python:: Python representation of line tables.
224 * Breakpoints In Python:: Manipulating breakpoints using Python.
225 * Finish Breakpoints in Python:: Setting Breakpoints on function return
227 * Lazy Strings In Python:: Python representation of lazy strings.
228 * Architectures In Python:: Python representation of architectures.
229 * Registers In Python:: Python representation of registers.
230 * Connections In Python:: Python representation of connections.
231 * TUI Windows In Python:: Implementing new TUI windows.
232 * Disassembly In Python:: Instruction Disassembly In Python
233 * Missing Debug Info In Python:: Handle missing debug info from Python.
237 @subsubsection Basic Python
239 @cindex python stdout
240 @cindex python pagination
241 At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
242 @code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
243 A Python program which outputs to one of these streams may have its
244 output interrupted by the user (@pxref{Screen Size}). In this
245 situation, a Python @code{KeyboardInterrupt} exception is thrown.
247 Some care must be taken when writing Python code to run in
248 @value{GDBN}. Two things worth noting in particular:
252 @value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}.
253 Python code must not override these, or even change the options using
254 @code{sigaction}. If your program changes the handling of these
255 signals, @value{GDBN} will most likely stop working correctly. Note
256 that it is unfortunately common for GUI toolkits to install a
257 @code{SIGCHLD} handler. When creating a new Python thread, you can
258 use @code{gdb.block_signals} or @code{gdb.Thread} to handle this
259 correctly; see @ref{Threading in GDB}.
262 @value{GDBN} takes care to mark its internal file descriptors as
263 close-on-exec. However, this cannot be done in a thread-safe way on
264 all platforms. Your Python programs should be aware of this and
265 should both create new file descriptors with the close-on-exec flag
266 set and arrange to close unneeded file descriptors before starting a
270 @cindex python functions
271 @cindex python module
273 @value{GDBN} introduces a new Python module, named @code{gdb}. All
274 methods and classes added by @value{GDBN} are placed in this module.
275 @value{GDBN} automatically @code{import}s the @code{gdb} module for
276 use in all scripts evaluated by the @code{python} command.
278 Some types of the @code{gdb} module come with a textual representation
279 (accessible through the @code{repr} or @code{str} functions). These are
280 offered for debugging purposes only, expect them to change over time.
282 @defvar gdb.PYTHONDIR
283 A string containing the python directory (@pxref{Python}).
286 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
287 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
288 If a GDB exception happens while @var{command} runs, it is
289 translated as described in @ref{Exception Handling,,Exception Handling}.
291 The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
292 command as having originated from the user invoking it interactively.
293 It must be a boolean value. If omitted, it defaults to @code{False}.
295 By default, any output produced by @var{command} is sent to
296 @value{GDBN}'s standard output (and to the log output if logging is
297 turned on). If the @var{to_string} parameter is
298 @code{True}, then output will be collected by @code{gdb.execute} and
299 returned as a string. The default is @code{False}, in which case the
300 return value is @code{None}. If @var{to_string} is @code{True}, the
301 @value{GDBN} virtual terminal will be temporarily set to unlimited width
302 and height, and its pagination will be disabled; @pxref{Screen Size}.
305 @defun gdb.breakpoints ()
306 Return a sequence holding all of @value{GDBN}'s breakpoints.
307 @xref{Breakpoints In Python}, for more information. In @value{GDBN}
308 version 7.11 and earlier, this function returned @code{None} if there
309 were no breakpoints. This peculiarity was subsequently fixed, and now
310 @code{gdb.breakpoints} returns an empty sequence in this case.
313 @defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]})
314 Return a Python list holding a collection of newly set
315 @code{gdb.Breakpoint} objects matching function names defined by the
316 @var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all
317 system functions (those not explicitly defined in the inferior) will
318 also be included in the match. The @var{throttle} keyword takes an
319 integer that defines the maximum number of pattern matches for
320 functions matched by the @var{regex} pattern. If the number of
321 matches exceeds the integer value of @var{throttle}, a
322 @code{RuntimeError} will be raised and no breakpoints will be created.
323 If @var{throttle} is not defined then there is no imposed limit on the
324 maximum number of matches and breakpoints to be created. The
325 @var{symtabs} keyword takes a Python iterable that yields a collection
326 of @code{gdb.Symtab} objects and will restrict the search to those
327 functions only contained within the @code{gdb.Symtab} objects.
330 @defun gdb.parameter (parameter)
331 Return the value of a @value{GDBN} @var{parameter} given by its name,
332 a string; the parameter name string may contain spaces if the parameter has a
333 multi-part name. For example, @samp{print object} is a valid
336 If the named parameter does not exist, this function throws a
337 @code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
338 parameter's value is converted to a Python value of the appropriate
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 @defun gdb.with_parameter (name, value)
349 Create a Python context manager (for use with the Python
350 @command{with} statement) that temporarily sets the gdb parameter
351 @var{name} to @var{value}. On exit from the context, the previous
352 value will be restored.
354 This uses @code{gdb.parameter} in its implementation, so it can throw
355 the same exceptions as that function.
357 For example, it's sometimes useful to evaluate some Python code with a
358 particular gdb language:
361 with gdb.with_parameter('language', 'pascal'):
362 ... language-specific operations
366 @defun gdb.history (number)
367 Return a value from @value{GDBN}'s value history (@pxref{Value
368 History}). The @var{number} argument indicates which history element to return.
369 If @var{number} is negative, then @value{GDBN} will take its absolute value
370 and count backward from the last element (i.e., the most recent element) to
371 find the value to return. If @var{number} is zero, then @value{GDBN} will
372 return the most recent element. If the element specified by @var{number}
373 doesn't exist in the value history, a @code{gdb.error} exception will be
376 If no exception is raised, the return value is always an instance of
377 @code{gdb.Value} (@pxref{Values From Inferior}).
380 @defun gdb.add_history (value)
381 Takes @var{value}, an instance of @code{gdb.Value} (@pxref{Values From
382 Inferior}), and appends the value this object represents to
383 @value{GDBN}'s value history (@pxref{Value History}), and return an
384 integer, its history number. If @var{value} is not a
385 @code{gdb.Value}, it is is converted using the @code{gdb.Value}
386 constructor. If @var{value} can't be converted to a @code{gdb.Value}
387 then a @code{TypeError} is raised.
389 When a command implemented in Python prints a single @code{gdb.Value}
390 as its result, then placing the value into the history will allow the
391 user convenient access to those values via CLI history facilities.
394 @defun gdb.history_count ()
395 Return an integer indicating the number of values in @value{GDBN}'s
396 value history (@pxref{Value History}).
399 @defun gdb.convenience_variable (name)
400 Return the value of the convenience variable (@pxref{Convenience
401 Vars}) named @var{name}. @var{name} must be a string. The name
402 should not include the @samp{$} that is used to mark a convenience
403 variable in an expression. If the convenience variable does not
404 exist, then @code{None} is returned.
407 @defun gdb.set_convenience_variable (name, value)
408 Set the value of the convenience variable (@pxref{Convenience Vars})
409 named @var{name}. @var{name} must be a string. The name should not
410 include the @samp{$} that is used to mark a convenience variable in an
411 expression. If @var{value} is @code{None}, then the convenience
412 variable is removed. Otherwise, if @var{value} is not a
413 @code{gdb.Value} (@pxref{Values From Inferior}), it is is converted
414 using the @code{gdb.Value} constructor.
417 @defun gdb.parse_and_eval (expression @r{[}, global_context@r{]})
418 Parse @var{expression}, which must be a string, as an expression in
419 the current language, evaluate it, and return the result as a
422 @var{global_context}, if provided, is a boolean indicating whether the
423 parsing should be done in the global context. The default is
424 @samp{False}, meaning that the current frame or current static context
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 @defun gdb.find_pc_line (pc)
435 Return the @code{gdb.Symtab_and_line} object corresponding to the
436 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid
437 value of @var{pc} is passed as an argument, then the @code{symtab} and
438 @code{line} attributes of the returned @code{gdb.Symtab_and_line} object
439 will be @code{None} and 0 respectively. This is identical to
440 @code{gdb.current_progspace().find_pc_line(pc)} and is included for
441 historical compatibility.
444 @defun gdb.write (string @r{[}, stream@r{]})
445 Print a string to @value{GDBN}'s paginated output stream. The
446 optional @var{stream} determines the stream to print to. The default
447 stream is @value{GDBN}'s standard output stream. Possible stream
454 @value{GDBN}'s standard output stream.
459 @value{GDBN}'s standard error stream.
464 @value{GDBN}'s log stream (@pxref{Logging Output}).
467 Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
468 call this function and will automatically direct the output to the
472 @defun gdb.flush (@r{[}, stream@r{]})
473 Flush the buffer of a @value{GDBN} paginated stream so that the
474 contents are displayed immediately. @value{GDBN} will flush the
475 contents of a stream automatically when it encounters a newline in the
476 buffer. The optional @var{stream} determines the stream to flush. The
477 default stream is @value{GDBN}'s standard output stream. Possible
484 @value{GDBN}'s standard output stream.
489 @value{GDBN}'s standard error stream.
494 @value{GDBN}'s log stream (@pxref{Logging Output}).
498 Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
499 call this function for the relevant stream.
502 @defun gdb.target_charset ()
503 Return the name of the current target character set (@pxref{Character
504 Sets}). This differs from @code{gdb.parameter('target-charset')} in
505 that @samp{auto} is never returned.
508 @defun gdb.target_wide_charset ()
509 Return the name of the current target wide character set
510 (@pxref{Character Sets}). This differs from
511 @code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
515 @defun gdb.host_charset ()
516 Return a string, the name of the current host character set
517 (@pxref{Character Sets}). This differs from
518 @code{gdb.parameter('host-charset')} in that @samp{auto} is never
522 @defun gdb.solib_name (address)
523 Return the name of the shared library holding the given @var{address}
524 as a string, or @code{None}. This is identical to
525 @code{gdb.current_progspace().solib_name(address)} and is included for
526 historical compatibility.
529 @defun gdb.decode_line (@r{[}expression@r{]})
530 Return locations of the line specified by @var{expression}, or of the
531 current line if no argument was given. This function returns a Python
532 tuple containing two elements. The first element contains a string
533 holding any unparsed section of @var{expression} (or @code{None} if
534 the expression has been fully parsed). The second element contains
535 either @code{None} or another tuple that contains all the locations
536 that match the expression represented as @code{gdb.Symtab_and_line}
537 objects (@pxref{Symbol Tables In Python}). If @var{expression} is
538 provided, it is decoded the way that @value{GDBN}'s inbuilt
539 @code{break} or @code{edit} commands do (@pxref{Location
543 @defun gdb.prompt_hook (current_prompt)
546 If @var{prompt_hook} is callable, @value{GDBN} will call the method
547 assigned to this operation before a prompt is displayed by
550 The parameter @code{current_prompt} contains the current @value{GDBN}
551 prompt. This method must return a Python string, or @code{None}. If
552 a string is returned, the @value{GDBN} prompt will be set to that
553 string. If @code{None} is returned, @value{GDBN} will continue to use
556 Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
557 such as those used by readline for command input, and annotation
558 related prompts are prohibited from being changed.
561 @anchor{gdb_architecture_names}
562 @defun gdb.architecture_names ()
563 Return a list containing all of the architecture names that the
564 current build of @value{GDBN} supports. Each architecture name is a
565 string. The names returned in this list are the same names as are
566 returned from @code{gdb.Architecture.name}
567 (@pxref{gdbpy_architecture_name,,Architecture.name}).
570 @anchor{gdbpy_connections}
571 @defun gdb.connections
572 Return a list of @code{gdb.TargetConnection} objects, one for each
573 currently active connection (@pxref{Connections In Python}). The
574 connection objects are in no particular order in the returned list.
577 @defun gdb.format_address (address @r{[}, progspace, architecture@r{]})
578 Return a string in the format @samp{@var{addr}
579 <@var{symbol}+@var{offset}>}, where @var{addr} is @var{address}
580 formatted in hexadecimal, @var{symbol} is the symbol whose address is
581 the nearest to @var{address} and below it in memory, and @var{offset}
582 is the offset from @var{symbol} to @var{address} in decimal.
584 If no suitable @var{symbol} was found, then the
585 <@var{symbol}+@var{offset}> part is not included in the returned
586 string, instead the returned string will just contain the
587 @var{address} formatted as hexadecimal. How far @value{GDBN} looks
588 back for a suitable symbol can be controlled with @kbd{set print
589 max-symbolic-offset} (@pxref{Print Settings}).
591 Additionally, the returned string can include file name and line
592 number information when @kbd{set print symbol-filename on}
593 (@pxref{Print Settings}), in this case the format of the returned
594 string is @samp{@var{addr} <@var{symbol}+@var{offset}> at
595 @var{filename}:@var{line-number}}.
598 The @var{progspace} is the gdb.Progspace in which @var{symbol} is
599 looked up, and @var{architecture} is used when formatting @var{addr},
600 e.g.@: in order to determine the size of an address in bytes.
602 If neither @var{progspace} or @var{architecture} are passed, then by
603 default @value{GDBN} will use the program space and architecture of
604 the currently selected inferior, thus, the following two calls are
608 gdb.format_address(address)
609 gdb.format_address(address,
610 gdb.selected_inferior().progspace,
611 gdb.selected_inferior().architecture())
614 It is not valid to only pass one of @var{progspace} or
615 @var{architecture}, either they must both be provided, or neither must
616 be provided (and the defaults will be used).
618 This method uses the same mechanism for formatting address, symbol,
619 and offset information as core @value{GDBN} does in commands such as
622 Here are some examples of the possible string formats:
626 0x00001042 <symbol+16>
627 0x00001042 <symbol+16 at file.c:123>
631 @defun gdb.current_language ()
632 Return the name of the current language as a string. Unlike
633 @code{gdb.parameter('language')}, this function will never return
634 @samp{auto}. If a @code{gdb.Frame} object is available (@pxref{Frames
635 In Python}), the @code{language} method might be preferable in some
636 cases, as that is not affected by the user's language setting.
639 @node Threading in GDB
640 @subsubsection Threading in GDB
642 @value{GDBN} is not thread-safe. If your Python program uses multiple
643 threads, you must be careful to only call @value{GDBN}-specific
644 functions in the @value{GDBN} thread. @value{GDBN} provides some
645 functions to help with this.
647 @defun gdb.block_signals ()
648 As mentioned earlier (@pxref{Basic Python}), certain signals must be
649 delivered to the @value{GDBN} main thread. The @code{block_signals}
650 function returns a context manager that will block these signals on
651 entry. This can be used when starting a new thread to ensure that the
652 signals are blocked there, like:
655 with gdb.block_signals():
660 @deftp {class} gdb.Thread
661 This is a subclass of Python's @code{threading.Thread} class. It
662 overrides the @code{start} method to call @code{block_signals}, making
663 this an easy-to-use drop-in replacement for creating threads that will
664 work well in @value{GDBN}.
667 @defun gdb.post_event (event)
668 Put @var{event}, a callable object taking no arguments, into
669 @value{GDBN}'s internal event queue. This callable will be invoked at
670 some later point, during @value{GDBN}'s event processing. Events
671 posted using @code{post_event} will be run in the order in which they
672 were posted; however, there is no way to know when they will be
673 processed relative to other events inside @value{GDBN}.
675 Unlike most Python APIs in @value{GDBN}, @code{post_event} is
676 thread-safe. For example:
679 (@value{GDBP}) python
683 > def __init__(self, message):
684 > self.message = message;
685 > def __call__(self):
686 > gdb.write(self.message)
688 >class MyThread1 (threading.Thread):
690 > gdb.post_event(Writer("Hello "))
692 >class MyThread2 (threading.Thread):
694 > gdb.post_event(Writer("World\n"))
699 (@value{GDBP}) Hello World
704 @node Exception Handling
705 @subsubsection Exception Handling
706 @cindex python exceptions
707 @cindex exceptions, python
709 When executing the @code{python} command, Python exceptions
710 uncaught within the Python code are translated to calls to
711 @value{GDBN} error-reporting mechanism. If the command that called
712 @code{python} does not handle the error, @value{GDBN} will
713 terminate it and print an error message containing the Python
714 exception name, the associated value, and the Python call stack
715 backtrace at the point where the exception was raised. Example:
718 (@value{GDBP}) python print foo
719 Traceback (most recent call last):
720 File "<string>", line 1, in <module>
721 NameError: name 'foo' is not defined
724 @value{GDBN} errors that happen in @value{GDBN} commands invoked by
725 Python code are converted to Python exceptions. The type of the
726 Python exception depends on the error.
730 This is the base class for most exceptions generated by @value{GDBN}.
731 It is derived from @code{RuntimeError}, for compatibility with earlier
732 versions of @value{GDBN}.
734 If an error occurring in @value{GDBN} does not fit into some more
735 specific category, then the generated exception will have this type.
737 @item gdb.MemoryError
738 This is a subclass of @code{gdb.error} which is thrown when an
739 operation tried to access invalid memory in the inferior.
741 @item KeyboardInterrupt
742 User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
743 prompt) is translated to a Python @code{KeyboardInterrupt} exception.
746 In all cases, your exception handler will see the @value{GDBN} error
747 message as its value and the Python call stack backtrace at the Python
748 statement closest to where the @value{GDBN} error occurred as the
752 When implementing @value{GDBN} commands in Python via
753 @code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
754 to be able to throw an exception that doesn't cause a traceback to be
755 printed. For example, the user may have invoked the command
756 incorrectly. @value{GDBN} provides a special exception class that can
757 be used for this purpose.
761 When thrown from a command or function, this exception will cause the
762 command or function to fail, but the Python stack will not be
763 displayed. @value{GDBN} does not throw this exception itself, but
764 rather recognizes it when thrown from user Python code. Example:
768 >class HelloWorld (gdb.Command):
769 > """Greet the whole world."""
770 > def __init__ (self):
771 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
772 > def invoke (self, args, from_tty):
773 > argv = gdb.string_to_argv (args)
774 > if len (argv) != 0:
775 > raise gdb.GdbError ("hello-world takes no arguments")
776 > print ("Hello, World!")
780 hello-world takes no arguments
784 @node Values From Inferior
785 @subsubsection Values From Inferior
786 @cindex values from inferior, with Python
787 @cindex python, working with values from inferior
789 @cindex @code{gdb.Value}
790 @value{GDBN} provides values it obtains from the inferior program in
791 an object of type @code{gdb.Value}. @value{GDBN} uses this object
792 for its internal bookkeeping of the inferior's values, and for
793 fetching values when necessary.
795 Inferior values that are simple scalars can be used directly in
796 Python expressions that are valid for the value's data type. Here's
797 an example for an integer or floating-point value @code{some_val}:
804 As result of this, @code{bar} will also be a @code{gdb.Value} object
805 whose values are of the same type as those of @code{some_val}. Valid
806 Python operations can also be performed on @code{gdb.Value} objects
807 representing a @code{struct} or @code{class} object. For such cases,
808 the overloaded operator (if present), is used to perform the operation.
809 For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects
810 representing instances of a @code{class} which overloads the @code{+}
811 operator, then one can use the @code{+} operator in their Python script
819 The result of the operation @code{val3} is also a @code{gdb.Value}
820 object corresponding to the value returned by the overloaded @code{+}
821 operator. In general, overloaded operators are invoked for the
822 following operations: @code{+} (binary addition), @code{-} (binary
823 subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<},
824 @code{>>}, @code{|}, @code{&}, @code{^}.
826 Inferior values that are structures or instances of some class can
827 be accessed using the Python @dfn{dictionary syntax}. For example, if
828 @code{some_val} is a @code{gdb.Value} instance holding a structure, you
829 can access its @code{foo} element with:
832 bar = some_val['foo']
835 @cindex getting structure elements using gdb.Field objects as subscripts
836 Again, @code{bar} will also be a @code{gdb.Value} object. Structure
837 elements can also be accessed by using @code{gdb.Field} objects as
838 subscripts (@pxref{Types In Python}, for more information on
839 @code{gdb.Field} objects). For example, if @code{foo_field} is a
840 @code{gdb.Field} object corresponding to element @code{foo} of the above
841 structure, then @code{bar} can also be accessed as follows:
844 bar = some_val[foo_field]
847 If a @code{gdb.Value} has array or pointer type, an integer index can
848 be used to access elements.
851 result = some_array[23]
854 A @code{gdb.Value} that represents a function can be executed via
855 inferior function call. Any arguments provided to the call must match
856 the function's prototype, and must be provided in the order specified
859 For example, @code{some_val} is a @code{gdb.Value} instance
860 representing a function that takes two integers as arguments. To
861 execute this function, call it like so:
864 result = some_val (10,20)
867 Any values returned from a function call will be stored as a
870 The following attributes are provided:
872 @defvar Value.address
873 If this object is addressable, this read-only attribute holds a
874 @code{gdb.Value} object representing the address. Otherwise,
875 this attribute holds @code{None}.
878 @cindex optimized out value in Python
879 @defvar Value.is_optimized_out
880 This read-only boolean attribute is true if the compiler optimized out
881 this value, thus it is not available for fetching from the inferior.
885 The type of this @code{gdb.Value}. The value of this attribute is a
886 @code{gdb.Type} object (@pxref{Types In Python}).
889 @defvar Value.dynamic_type
890 The dynamic type of this @code{gdb.Value}. This uses the object's
891 virtual table and the C@t{++} run-time type information
892 (@acronym{RTTI}) to determine the dynamic type of the value. If this
893 value is of class type, it will return the class in which the value is
894 embedded, if any. If this value is of pointer or reference to a class
895 type, it will compute the dynamic type of the referenced object, and
896 return a pointer or reference to that type, respectively. In all
897 other cases, it will return the value's static type.
899 Note that this feature will only work when debugging a C@t{++} program
900 that includes @acronym{RTTI} for the object in question. Otherwise,
901 it will just return the static type of the value as in @kbd{ptype foo}
902 (@pxref{Symbols, ptype}).
905 @defvar Value.is_lazy
906 The value of this read-only boolean attribute is @code{True} if this
907 @code{gdb.Value} has not yet been fetched from the inferior.
908 @value{GDBN} does not fetch values until necessary, for efficiency.
912 myval = gdb.parse_and_eval ('somevar')
915 The value of @code{somevar} is not fetched at this time. It will be
916 fetched when the value is needed, or when the @code{fetch_lazy}
921 The value of this attribute is a @code{bytes} object containing the
922 bytes that make up this @code{Value}'s complete value in little endian
923 order. If the complete contents of this value are not available then
924 accessing this attribute will raise an exception.
926 This attribute can also be assigned to. The new value should be a
927 buffer object (e.g.@: a @code{bytes} object), the length of the new
928 buffer must exactly match the length of this @code{Value}'s type. The
929 bytes values in the new buffer should be in little endian order.
931 As with @code{Value.assign} (@pxref{Value.assign}), if this value
932 cannot be assigned to, then an exception will be thrown.
935 The following methods are provided:
937 @defun Value.__init__ (val)
938 Many Python values can be converted directly to a @code{gdb.Value} via
939 this object initializer. Specifically:
943 A Python boolean is converted to the boolean type from the current
947 A Python integer is converted to the C @code{long} type for the
948 current architecture.
951 A Python long is converted to the C @code{long long} type for the
952 current architecture.
955 A Python float is converted to the C @code{double} type for the
956 current architecture.
959 A Python string is converted to a target string in the current target
960 language using the current target encoding.
961 If a character cannot be represented in the current target encoding,
962 then an exception is thrown.
964 @item @code{gdb.Value}
965 If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
967 @item @code{gdb.LazyString}
968 If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
969 Python}), then the lazy string's @code{value} method is called, and
974 @defun Value.__init__ (val, type)
975 This second form of the @code{gdb.Value} constructor returns a
976 @code{gdb.Value} of type @var{type} where the value contents are taken
977 from the Python buffer object specified by @var{val}. The number of
978 bytes in the Python buffer object must be greater than or equal to the
981 If @var{type} is @code{None} then this version of @code{__init__}
982 behaves as though @var{type} was not passed at all.
985 @anchor{Value.assign}
986 @defun Value.assign (rhs)
987 Assign @var{rhs} to this value, and return @code{None}. If this value
988 cannot be assigned to, or if the assignment is invalid for some reason
989 (for example a type-checking failure), an exception will be thrown.
992 @defun Value.cast (type)
993 Return a new instance of @code{gdb.Value} that is the result of
994 casting this instance to the type described by @var{type}, which must
995 be a @code{gdb.Type} object. If the cast cannot be performed for some
996 reason, this method throws an exception.
999 @defun Value.dereference ()
1000 For pointer data types, this method returns a new @code{gdb.Value} object
1001 whose contents is the object pointed to by the pointer. For example, if
1002 @code{foo} is a C pointer to an @code{int}, declared in your C program as
1009 then you can use the corresponding @code{gdb.Value} to access what
1010 @code{foo} points to like this:
1013 bar = foo.dereference ()
1016 The result @code{bar} will be a @code{gdb.Value} object holding the
1017 value pointed to by @code{foo}.
1019 A similar function @code{Value.referenced_value} exists which also
1020 returns @code{gdb.Value} objects corresponding to the values pointed to
1021 by pointer values (and additionally, values referenced by reference
1022 values). However, the behavior of @code{Value.dereference}
1023 differs from @code{Value.referenced_value} by the fact that the
1024 behavior of @code{Value.dereference} is identical to applying the C
1025 unary operator @code{*} on a given value. For example, consider a
1026 reference to a pointer @code{ptrref}, declared in your C@t{++} program
1030 typedef int *intptr;
1034 intptr &ptrref = ptr;
1037 Though @code{ptrref} is a reference value, one can apply the method
1038 @code{Value.dereference} to the @code{gdb.Value} object corresponding
1039 to it and obtain a @code{gdb.Value} which is identical to that
1040 corresponding to @code{val}. However, if you apply the method
1041 @code{Value.referenced_value}, the result would be a @code{gdb.Value}
1042 object identical to that corresponding to @code{ptr}.
1045 py_ptrref = gdb.parse_and_eval ("ptrref")
1046 py_val = py_ptrref.dereference ()
1047 py_ptr = py_ptrref.referenced_value ()
1050 The @code{gdb.Value} object @code{py_val} is identical to that
1051 corresponding to @code{val}, and @code{py_ptr} is identical to that
1052 corresponding to @code{ptr}. In general, @code{Value.dereference} can
1053 be applied whenever the C unary operator @code{*} can be applied
1054 to the corresponding C value. For those cases where applying both
1055 @code{Value.dereference} and @code{Value.referenced_value} is allowed,
1056 the results obtained need not be identical (as we have seen in the above
1057 example). The results are however identical when applied on
1058 @code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
1059 objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
1062 @defun Value.referenced_value ()
1063 For pointer or reference data types, this method returns a new
1064 @code{gdb.Value} object corresponding to the value referenced by the
1065 pointer/reference value. For pointer data types,
1066 @code{Value.dereference} and @code{Value.referenced_value} produce
1067 identical results. The difference between these methods is that
1068 @code{Value.dereference} cannot get the values referenced by reference
1069 values. For example, consider a reference to an @code{int}, declared
1070 in your C@t{++} program as
1078 then applying @code{Value.dereference} to the @code{gdb.Value} object
1079 corresponding to @code{ref} will result in an error, while applying
1080 @code{Value.referenced_value} will result in a @code{gdb.Value} object
1081 identical to that corresponding to @code{val}.
1084 py_ref = gdb.parse_and_eval ("ref")
1085 er_ref = py_ref.dereference () # Results in error
1086 py_val = py_ref.referenced_value () # Returns the referenced value
1089 The @code{gdb.Value} object @code{py_val} is identical to that
1090 corresponding to @code{val}.
1093 @defun Value.reference_value ()
1094 Return a @code{gdb.Value} object which is a reference to the value
1095 encapsulated by this instance.
1098 @defun Value.const_value ()
1099 Return a @code{gdb.Value} object which is a @code{const} version of the
1100 value encapsulated by this instance.
1103 @defun Value.dynamic_cast (type)
1104 Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
1105 operator were used. Consult a C@t{++} reference for details.
1108 @defun Value.reinterpret_cast (type)
1109 Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
1110 operator were used. Consult a C@t{++} reference for details.
1113 @defun Value.format_string (...)
1114 Convert a @code{gdb.Value} to a string, similarly to what the @code{print}
1115 command does. Invoked with no arguments, this is equivalent to calling
1116 the @code{str} function on the @code{gdb.Value}. The representation of
1117 the same value may change across different versions of @value{GDBN}, so
1118 you shouldn't, for instance, parse the strings returned by this method.
1120 All the arguments are keyword only. If an argument is not specified, the
1121 current global default setting is used.
1125 @code{True} if pretty-printers (@pxref{Pretty Printing}) should not be
1126 used to format the value. @code{False} if enabled pretty-printers
1127 matching the type represented by the @code{gdb.Value} should be used to
1131 @code{True} if arrays should be pretty printed to be more convenient to
1132 read, @code{False} if they shouldn't (see @code{set print array} in
1133 @ref{Print Settings}).
1135 @item pretty_structs
1136 @code{True} if structs should be pretty printed to be more convenient to
1137 read, @code{False} if they shouldn't (see @code{set print pretty} in
1138 @ref{Print Settings}).
1141 @code{True} if array indexes should be included in the string
1142 representation of arrays, @code{False} if they shouldn't (see @code{set
1143 print array-indexes} in @ref{Print Settings}).
1146 @code{True} if the string representation of a pointer should include the
1147 corresponding symbol name (if one exists), @code{False} if it shouldn't
1148 (see @code{set print symbol} in @ref{Print Settings}).
1151 @code{True} if unions which are contained in other structures or unions
1152 should be expanded, @code{False} if they shouldn't (see @code{set print
1153 union} in @ref{Print Settings}).
1156 @code{True} if the string representation of a pointer should include the
1157 address, @code{False} if it shouldn't (see @code{set print address} in
1158 @ref{Print Settings}).
1161 @code{True} if binary values should be displayed in groups of four bits,
1162 known as nibbles. @code{False} if it shouldn't (@pxref{Print Settings,
1163 set print nibbles}).
1166 @code{True} if C@t{++} references should be resolved to the value they
1167 refer to, @code{False} (the default) if they shouldn't. Note that, unlike
1168 for the @code{print} command, references are not automatically expanded
1169 when using the @code{format_string} method or the @code{str}
1170 function. There is no global @code{print} setting to change the default
1173 @item actual_objects
1174 @code{True} if the representation of a pointer to an object should
1175 identify the @emph{actual} (derived) type of the object rather than the
1176 @emph{declared} type, using the virtual function table. @code{False} if
1177 the @emph{declared} type should be used. (See @code{set print object} in
1178 @ref{Print Settings}).
1180 @item static_members
1181 @code{True} if static members should be included in the string
1182 representation of a C@t{++} object, @code{False} if they shouldn't (see
1183 @code{set print static-members} in @ref{Print Settings}).
1185 @item max_characters
1186 Number of string characters to print, @code{0} to follow
1187 @code{max_elements}, or @code{UINT_MAX} to print an unlimited number
1188 of characters (see @code{set print characters} in @ref{Print Settings}).
1191 Number of array elements to print, or @code{0} to print an unlimited
1192 number of elements (see @code{set print elements} in @ref{Print
1196 The maximum depth to print for nested structs and unions, or @code{-1}
1197 to print an unlimited number of elements (see @code{set print
1198 max-depth} in @ref{Print Settings}).
1200 @item repeat_threshold
1201 Set the threshold for suppressing display of repeated array elements, or
1202 @code{0} to represent all elements, even if repeated. (See @code{set
1203 print repeats} in @ref{Print Settings}).
1206 A string containing a single character representing the format to use for
1207 the returned string. For instance, @code{'x'} is equivalent to using the
1208 @value{GDBN} command @code{print} with the @code{/x} option and formats
1209 the value as a hexadecimal number.
1212 @code{True} if @value{GDBN} should apply styling to the returned
1213 string. When styling is applied, the returned string might contain
1214 ANSI terminal escape sequences. Escape sequences will only be
1215 included if styling is turned on, see @ref{Output Styling}.
1216 Additionally, @value{GDBN} only styles some value contents, so not
1217 every output string will contain escape sequences.
1219 When @code{False}, which is the default, no output styling is applied.
1222 @code{True} when just a summary should be printed. In this mode,
1223 scalar values are printed in their entirety, but aggregates such as
1224 structures or unions are omitted. This mode is used by @code{set
1225 print frame-arguments scalars} (@pxref{Print Settings}).
1229 @defun Value.to_array ()
1230 If this value is array-like (@pxref{Type.is_array_like}), then this
1231 method converts it to an array, which is returned. If this value is
1232 already an array, it is simply returned. Otherwise, an exception is
1236 @defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
1237 If this @code{gdb.Value} represents a string, then this method
1238 converts the contents to a Python string. Otherwise, this method will
1241 Values are interpreted as strings according to the rules of the
1242 current language. If the optional length argument is given, the
1243 string will be converted to that length, and will include any embedded
1244 zeroes that the string may contain. Otherwise, for languages
1245 where the string is zero-terminated, the entire string will be
1248 For example, in C-like languages, a value is a string if it is a pointer
1249 to or an array of characters or ints of type @code{wchar_t}, @code{char16_t},
1252 If the optional @var{encoding} argument is given, it must be a string
1253 naming the encoding of the string in the @code{gdb.Value}, such as
1254 @code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
1255 the same encodings as the corresponding argument to Python's
1256 @code{string.decode} method, and the Python codec machinery will be used
1257 to convert the string. If @var{encoding} is not given, or if
1258 @var{encoding} is the empty string, then either the @code{target-charset}
1259 (@pxref{Character Sets}) will be used, or a language-specific encoding
1260 will be used, if the current language is able to supply one.
1262 The optional @var{errors} argument is the same as the corresponding
1263 argument to Python's @code{string.decode} method.
1265 If the optional @var{length} argument is given, the string will be
1266 fetched and converted to the given length.
1269 @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
1270 If this @code{gdb.Value} represents a string, then this method
1271 converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
1272 In Python}). Otherwise, this method will throw an exception.
1274 If the optional @var{encoding} argument is given, it must be a string
1275 naming the encoding of the @code{gdb.LazyString}. Some examples are:
1276 @samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
1277 @var{encoding} argument is an encoding that @value{GDBN} does
1278 recognize, @value{GDBN} will raise an error.
1280 When a lazy string is printed, the @value{GDBN} encoding machinery is
1281 used to convert the string during printing. If the optional
1282 @var{encoding} argument is not provided, or is an empty string,
1283 @value{GDBN} will automatically select the encoding most suitable for
1284 the string type. For further information on encoding in @value{GDBN}
1285 please see @ref{Character Sets}.
1287 If the optional @var{length} argument is given, the string will be
1288 fetched and encoded to the length of characters specified. If
1289 the @var{length} argument is not provided, the string will be fetched
1290 and encoded until a null of appropriate width is found.
1293 @defun Value.fetch_lazy ()
1294 If the @code{gdb.Value} object is currently a lazy value
1295 (@code{gdb.Value.is_lazy} is @code{True}), then the value is
1296 fetched from the inferior. Any errors that occur in the process
1297 will produce a Python exception.
1299 If the @code{gdb.Value} object is not a lazy value, this method
1302 This method does not return a value.
1306 @node Types In Python
1307 @subsubsection Types In Python
1308 @cindex types in Python
1309 @cindex Python, working with types
1312 @value{GDBN} represents types from the inferior using the class
1315 The following type-related functions are available in the @code{gdb}
1318 @defun gdb.lookup_type (name @r{[}, block@r{]})
1319 This function looks up a type by its @var{name}, which must be a string.
1321 If @var{block} is given, then @var{name} is looked up in that scope.
1322 Otherwise, it is searched for globally.
1324 Ordinarily, this function will return an instance of @code{gdb.Type}.
1325 If the named type cannot be found, it will throw an exception.
1328 Integer types can be found without looking them up by name.
1329 @xref{Architectures In Python}, for the @code{integer_type} method.
1331 If the type is a structure or class type, or an enum type, the fields
1332 of that type can be accessed using the Python @dfn{dictionary syntax}.
1333 For example, if @code{some_type} is a @code{gdb.Type} instance holding
1334 a structure type, you can access its @code{foo} field with:
1337 bar = some_type['foo']
1340 @code{bar} will be a @code{gdb.Field} object; see below under the
1341 description of the @code{Type.fields} method for a description of the
1342 @code{gdb.Field} class.
1344 An instance of @code{Type} has the following attributes:
1346 @defvar Type.alignof
1347 The alignment of this type, in bytes. Type alignment comes from the
1348 debugging information; if it was not specified, then @value{GDBN} will
1349 use the relevant ABI to try to determine the alignment. In some
1350 cases, even this is not possible, and zero will be returned.
1354 The type code for this type. The type code will be one of the
1355 @code{TYPE_CODE_} constants defined below.
1358 @defvar Type.dynamic
1359 A boolean indicating whether this type is dynamic. In some
1360 situations, such as Rust @code{enum} types or Ada variant records, the
1361 concrete type of a value may vary depending on its contents. That is,
1362 the declared type of a variable, or the type returned by
1363 @code{gdb.lookup_type} may be dynamic; while the type of the
1364 variable's value will be a concrete instance of that dynamic type.
1366 For example, consider this code:
1372 Here, at least conceptually (whether your compiler actually does this
1373 is a separate issue), examining @w{@code{gdb.lookup_symbol("array", ...).type}}
1374 could yield a @code{gdb.Type} which reports a size of @code{None}.
1375 This is the dynamic type.
1377 However, examining @code{gdb.parse_and_eval("array").type} would yield
1378 a concrete type, whose length would be known.
1382 The name of this type. If this type has no name, then @code{None}
1387 The size of this type, in target @code{char} units. Usually, a
1388 target's @code{char} type will be an 8-bit byte. However, on some
1389 unusual platforms, this type may have a different size. A dynamic
1390 type may not have a fixed size; in this case, this attribute's value
1391 will be @code{None}.
1395 The tag name for this type. The tag name is the name after
1396 @code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
1397 languages have this concept. If this type has no tag name, then
1398 @code{None} is returned.
1401 @defvar Type.objfile
1402 The @code{gdb.Objfile} that this type was defined in, or @code{None} if
1403 there is no associated objfile.
1406 @defvar Type.is_scalar
1407 This property is @code{True} if the type is a scalar type, otherwise,
1408 this property is @code{False}. Examples of non-scalar types include
1409 structures, unions, and classes.
1412 @defvar Type.is_signed
1413 For scalar types (those for which @code{Type.is_scalar} is
1414 @code{True}), this property is @code{True} if the type is signed,
1415 otherwise this property is @code{False}.
1417 Attempting to read this property for a non-scalar type (a type for
1418 which @code{Type.is_scalar} is @code{False}), will raise a
1422 @defvar Type.is_array_like
1423 @anchor{Type.is_array_like}
1424 A boolean indicating whether this type is array-like.
1426 Some languages have array-like objects that are represented internally
1427 as structures. For example, this is true for a Rust slice type, or
1428 for an Ada unconstrained array. @value{GDBN} may know about these
1429 types. This determination is done based on the language from which
1430 the type originated.
1433 @defvar Type.is_string_like
1434 A boolean indicating whether this type is string-like. Like
1435 @code{Type.is_array_like}, this is determined based on the originating
1436 language of the type.
1439 The following methods are provided:
1441 @defun Type.fields ()
1443 Return the fields of this type. The behavior depends on the type code:
1448 For structure and union types, this method returns the fields.
1451 Enum types have one field per enum constant.
1454 Function and method types have one field per parameter. The base types of
1455 C@t{++} classes are also represented as fields.
1458 Array types have one field representing the array's range.
1461 If the type does not fit into one of these categories, a @code{TypeError}
1466 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
1469 This attribute is not available for @code{enum} or @code{static}
1470 (as in C@t{++}) fields. The value is the position, counting
1471 in bits, from the start of the containing type. Note that, in a
1472 dynamic type, the position of a field may not be constant. In this
1473 case, the value will be @code{None}. Also, a dynamic type may have
1474 fields that do not appear in a corresponding concrete type.
1477 This attribute is only available for @code{enum} fields, and its value
1478 is the enumeration member's integer representation.
1481 The name of the field, or @code{None} for anonymous fields.
1484 This is @code{True} if the field is artificial, usually meaning that
1485 it was provided by the compiler and not the user. This attribute is
1486 always provided, and is @code{False} if the field is not artificial.
1489 This is @code{True} if the field represents a base class of a C@t{++}
1490 structure. This attribute is always provided, and is @code{False}
1491 if the field is not a base class of the type that is the argument of
1492 @code{fields}, or if that type was not a C@t{++} class.
1495 If the field is packed, or is a bitfield, then this will have a
1496 non-zero value, which is the size of the field in bits. Otherwise,
1497 this will be zero; in this case the field's size is given by its type.
1500 The type of the field. This is usually an instance of @code{Type},
1501 but it can be @code{None} in some situations.
1504 The type which contains this field. This is an instance of
1509 @defun Type.array (n1 @r{[}, n2@r{]})
1510 Return a new @code{gdb.Type} object which represents an array of this
1511 type. If one argument is given, it is the inclusive upper bound of
1512 the array; in this case the lower bound is zero. If two arguments are
1513 given, the first argument is the lower bound of the array, and the
1514 second argument is the upper bound of the array. An array's length
1515 must not be negative, but the bounds can be.
1518 @defun Type.vector (n1 @r{[}, n2@r{]})
1519 Return a new @code{gdb.Type} object which represents a vector of this
1520 type. If one argument is given, it is the inclusive upper bound of
1521 the vector; in this case the lower bound is zero. If two arguments are
1522 given, the first argument is the lower bound of the vector, and the
1523 second argument is the upper bound of the vector. A vector's length
1524 must not be negative, but the bounds can be.
1526 The difference between an @code{array} and a @code{vector} is that
1527 arrays behave like in C: when used in expressions they decay to a pointer
1528 to the first element whereas vectors are treated as first class values.
1531 @defun Type.const ()
1532 Return a new @code{gdb.Type} object which represents a
1533 @code{const}-qualified variant of this type.
1536 @defun Type.volatile ()
1537 Return a new @code{gdb.Type} object which represents a
1538 @code{volatile}-qualified variant of this type.
1541 @defun Type.unqualified ()
1542 Return a new @code{gdb.Type} object which represents an unqualified
1543 variant of this type. That is, the result is neither @code{const} nor
1547 @defun Type.range ()
1548 Return a Python @code{Tuple} object that contains two elements: the
1549 low bound of the argument type and the high bound of that type. If
1550 the type does not have a range, @value{GDBN} will raise a
1551 @code{gdb.error} exception (@pxref{Exception Handling}).
1554 @defun Type.reference ()
1555 Return a new @code{gdb.Type} object which represents a reference to this
1559 @defun Type.pointer ()
1560 Return a new @code{gdb.Type} object which represents a pointer to this
1564 @defun Type.strip_typedefs ()
1565 Return a new @code{gdb.Type} that represents the real type,
1566 after removing all layers of typedefs.
1569 @defun Type.target ()
1570 Return a new @code{gdb.Type} object which represents the target type
1573 For a pointer type, the target type is the type of the pointed-to
1574 object. For an array type (meaning C-like arrays), the target type is
1575 the type of the elements of the array. For a function or method type,
1576 the target type is the type of the return value. For a complex type,
1577 the target type is the type of the elements. For a typedef, the
1578 target type is the aliased type.
1580 If the type does not have a target, this method will throw an
1584 @defun Type.template_argument (n @r{[}, block@r{]})
1585 If this @code{gdb.Type} is an instantiation of a template, this will
1586 return a new @code{gdb.Value} or @code{gdb.Type} which represents the
1587 value of the @var{n}th template argument (indexed starting at 0).
1589 If this @code{gdb.Type} is not a template type, or if the type has fewer
1590 than @var{n} template arguments, this will throw an exception.
1591 Ordinarily, only C@t{++} code will have template types.
1593 If @var{block} is given, then @var{name} is looked up in that scope.
1594 Otherwise, it is searched for globally.
1597 @defun Type.optimized_out ()
1598 Return @code{gdb.Value} instance of this type whose value is optimized
1599 out. This allows a frame decorator to indicate that the value of an
1600 argument or a local variable is not known.
1603 Each type has a code, which indicates what category this type falls
1604 into. The available type categories are represented by constants
1605 defined in the @code{gdb} module:
1608 @vindex TYPE_CODE_PTR
1609 @item gdb.TYPE_CODE_PTR
1610 The type is a pointer.
1612 @vindex TYPE_CODE_ARRAY
1613 @item gdb.TYPE_CODE_ARRAY
1614 The type is an array.
1616 @vindex TYPE_CODE_STRUCT
1617 @item gdb.TYPE_CODE_STRUCT
1618 The type is a structure.
1620 @vindex TYPE_CODE_UNION
1621 @item gdb.TYPE_CODE_UNION
1622 The type is a union.
1624 @vindex TYPE_CODE_ENUM
1625 @item gdb.TYPE_CODE_ENUM
1626 The type is an enum.
1628 @vindex TYPE_CODE_FLAGS
1629 @item gdb.TYPE_CODE_FLAGS
1630 A bit flags type, used for things such as status registers.
1632 @vindex TYPE_CODE_FUNC
1633 @item gdb.TYPE_CODE_FUNC
1634 The type is a function.
1636 @vindex TYPE_CODE_INT
1637 @item gdb.TYPE_CODE_INT
1638 The type is an integer type.
1640 @vindex TYPE_CODE_FLT
1641 @item gdb.TYPE_CODE_FLT
1642 A floating point type.
1644 @vindex TYPE_CODE_VOID
1645 @item gdb.TYPE_CODE_VOID
1646 The special type @code{void}.
1648 @vindex TYPE_CODE_SET
1649 @item gdb.TYPE_CODE_SET
1652 @vindex TYPE_CODE_RANGE
1653 @item gdb.TYPE_CODE_RANGE
1654 A range type, that is, an integer type with bounds.
1656 @vindex TYPE_CODE_STRING
1657 @item gdb.TYPE_CODE_STRING
1658 A string type. Note that this is only used for certain languages with
1659 language-defined string types; C strings are not represented this way.
1661 @vindex TYPE_CODE_BITSTRING
1662 @item gdb.TYPE_CODE_BITSTRING
1663 A string of bits. It is deprecated.
1665 @vindex TYPE_CODE_ERROR
1666 @item gdb.TYPE_CODE_ERROR
1667 An unknown or erroneous type.
1669 @vindex TYPE_CODE_METHOD
1670 @item gdb.TYPE_CODE_METHOD
1671 A method type, as found in C@t{++}.
1673 @vindex TYPE_CODE_METHODPTR
1674 @item gdb.TYPE_CODE_METHODPTR
1675 A pointer-to-member-function.
1677 @vindex TYPE_CODE_MEMBERPTR
1678 @item gdb.TYPE_CODE_MEMBERPTR
1679 A pointer-to-member.
1681 @vindex TYPE_CODE_REF
1682 @item gdb.TYPE_CODE_REF
1685 @vindex TYPE_CODE_RVALUE_REF
1686 @item gdb.TYPE_CODE_RVALUE_REF
1687 A C@t{++}11 rvalue reference type.
1689 @vindex TYPE_CODE_CHAR
1690 @item gdb.TYPE_CODE_CHAR
1693 @vindex TYPE_CODE_BOOL
1694 @item gdb.TYPE_CODE_BOOL
1697 @vindex TYPE_CODE_COMPLEX
1698 @item gdb.TYPE_CODE_COMPLEX
1699 A complex float type.
1701 @vindex TYPE_CODE_TYPEDEF
1702 @item gdb.TYPE_CODE_TYPEDEF
1703 A typedef to some other type.
1705 @vindex TYPE_CODE_NAMESPACE
1706 @item gdb.TYPE_CODE_NAMESPACE
1707 A C@t{++} namespace.
1709 @vindex TYPE_CODE_DECFLOAT
1710 @item gdb.TYPE_CODE_DECFLOAT
1711 A decimal floating point type.
1713 @vindex TYPE_CODE_INTERNAL_FUNCTION
1714 @item gdb.TYPE_CODE_INTERNAL_FUNCTION
1715 A function internal to @value{GDBN}. This is the type used to represent
1716 convenience functions.
1718 @vindex TYPE_CODE_XMETHOD
1719 @item gdb.TYPE_CODE_XMETHOD
1720 A method internal to @value{GDBN}. This is the type used to represent
1721 xmethods (@pxref{Writing an Xmethod}).
1723 @vindex TYPE_CODE_FIXED_POINT
1724 @item gdb.TYPE_CODE_FIXED_POINT
1725 A fixed-point number.
1727 @vindex TYPE_CODE_NAMESPACE
1728 @item gdb.TYPE_CODE_NAMESPACE
1732 Further support for types is provided in the @code{gdb.types}
1733 Python module (@pxref{gdb.types}).
1735 @node Pretty Printing API
1736 @subsubsection Pretty Printing API
1737 @cindex python pretty printing api
1739 A pretty-printer is just an object that holds a value and implements a
1740 specific interface, defined here. An example output is provided
1741 (@pxref{Pretty Printing}).
1743 Because @value{GDBN} did not document extensibility for
1744 pretty-printers, by default @value{GDBN} will assume that only the
1745 basic pretty-printer methods may be available. The basic methods are
1746 marked as such, below.
1748 To allow extensibility, @value{GDBN} provides the
1749 @code{gdb.ValuePrinter} base class. This class does not provide any
1750 attributes or behavior, but instead serves as a tag that can be
1751 recognized by @value{GDBN}. For such printers, @value{GDBN} reserves
1752 all attributes starting with a lower-case letter. That is, in the
1753 future, @value{GDBN} may add a new method or attribute to the
1754 pretty-printer protocol, and @code{gdb.ValuePrinter}-based printers
1755 are expected to handle this gracefully. A simple way to do this would
1756 be to use a leading underscore (or two, following the Python
1757 name-mangling scheme) to any attributes local to the implementation.
1759 @defun pretty_printer.children (self)
1760 @value{GDBN} will call this method on a pretty-printer to compute the
1761 children of the pretty-printer's value.
1763 This method must return an object conforming to the Python iterator
1764 protocol. Each item returned by the iterator must be a tuple holding
1765 two elements. The first element is the ``name'' of the child; the
1766 second element is the child's value. The value can be any Python
1767 object which is convertible to a @value{GDBN} value.
1769 This is a basic method, and is optional. If it does not exist,
1770 @value{GDBN} will act as though the value has no children.
1772 For efficiency, the @code{children} method should lazily compute its
1773 results. This will let @value{GDBN} read as few elements as
1774 necessary, for example when various print settings (@pxref{Print
1775 Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable
1776 Objects}) limit the number of elements to be displayed.
1778 Children may be hidden from display based on the value of @samp{set
1779 print max-depth} (@pxref{Print Settings}).
1782 @defun pretty_printer.display_hint (self)
1783 The CLI may call this method and use its result to change the
1784 formatting of a value. The result will also be supplied to an MI
1785 consumer as a @samp{displayhint} attribute of the variable being
1788 This is a basic method, and is optional. If it does exist, this
1789 method must return a string or the special value @code{None}.
1791 Some display hints are predefined by @value{GDBN}:
1795 Indicate that the object being printed is ``array-like''. The CLI
1796 uses this to respect parameters such as @code{set print elements} and
1797 @code{set print array}.
1800 Indicate that the object being printed is ``map-like'', and that the
1801 children of this value can be assumed to alternate between keys and
1805 Indicate that the object being printed is ``string-like''. If the
1806 printer's @code{to_string} method returns a Python string of some
1807 kind, then @value{GDBN} will call its internal language-specific
1808 string-printing function to format the string. For the CLI this means
1809 adding quotation marks, possibly escaping some characters, respecting
1810 @code{set print elements}, and the like.
1813 The special value @code{None} causes @value{GDBN} to apply the default
1817 @defun pretty_printer.to_string (self)
1818 @value{GDBN} will call this method to display the string
1819 representation of the value passed to the object's constructor.
1821 This is a basic method, and is optional.
1823 When printing from the CLI, if the @code{to_string} method exists,
1824 then @value{GDBN} will prepend its result to the values returned by
1825 @code{children}. Exactly how this formatting is done is dependent on
1826 the display hint, and may change as more hints are added. Also,
1827 depending on the print settings (@pxref{Print Settings}), the CLI may
1828 print just the result of @code{to_string} in a stack trace, omitting
1829 the result of @code{children}.
1831 If this method returns a string, it is printed verbatim.
1833 Otherwise, if this method returns an instance of @code{gdb.Value},
1834 then @value{GDBN} prints this value. This may result in a call to
1835 another pretty-printer.
1837 If instead the method returns a Python value which is convertible to a
1838 @code{gdb.Value}, then @value{GDBN} performs the conversion and prints
1839 the resulting value. Again, this may result in a call to another
1840 pretty-printer. Python scalars (integers, floats, and booleans) and
1841 strings are convertible to @code{gdb.Value}; other types are not.
1843 Finally, if this method returns @code{None} then no further operations
1844 are peformed in this method and nothing is printed.
1846 If the result is not one of these types, an exception is raised.
1849 @defun pretty_printer.num_children ()
1850 This is not a basic method, so @value{GDBN} will only ever call it for
1851 objects derived from @code{gdb.ValuePrinter}.
1853 If available, this method should return the number of children.
1854 @code{None} may be returned if the number can't readily be computed.
1857 @defun pretty_printer.child (n)
1858 This is not a basic method, so @value{GDBN} will only ever call it for
1859 objects derived from @code{gdb.ValuePrinter}.
1861 If available, this method should return the child value indicated by
1862 @var{n}. Indices start at zero.
1865 @value{GDBN} provides a function which can be used to look up the
1866 default pretty-printer for a @code{gdb.Value}:
1868 @defun gdb.default_visualizer (value)
1869 This function takes a @code{gdb.Value} object as an argument. If a
1870 pretty-printer for this value exists, then it is returned. If no such
1871 printer exists, then this returns @code{None}.
1874 Normally, a pretty-printer can respect the user's print settings
1875 (including temporarily applied settings, such as @samp{/x}) simply by
1876 calling @code{Value.format_string} (@pxref{Values From Inferior}).
1877 However, these settings can also be queried directly:
1879 @defun gdb.print_options ()
1880 Return a dictionary whose keys are the valid keywords that can be
1881 given to @code{Value.format_string}, and whose values are the user's
1882 settings. During a @code{print} or other operation, the values will
1883 reflect any flags that are temporarily in effect.
1886 (gdb) python print (gdb.print_options ()['max_elements'])
1891 @node Selecting Pretty-Printers
1892 @subsubsection Selecting Pretty-Printers
1893 @cindex selecting python pretty-printers
1895 @value{GDBN} provides several ways to register a pretty-printer:
1896 globally, per program space, and per objfile. When choosing how to
1897 register your pretty-printer, a good rule is to register it with the
1898 smallest scope possible: that is prefer a specific objfile first, then
1899 a program space, and only register a printer globally as a last
1902 @defvar gdb.pretty_printers
1903 The Python list @code{gdb.pretty_printers} contains an array of
1904 functions or callable objects that have been registered via addition
1905 as a pretty-printer. Printers in this list are called @code{global}
1906 printers, they're available when debugging all inferiors.
1909 Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
1910 Each @code{gdb.Objfile} also contains a @code{pretty_printers}
1913 Each function on these lists is passed a single @code{gdb.Value}
1914 argument and should return a pretty-printer object conforming to the
1915 interface definition above (@pxref{Pretty Printing API}). If a function
1916 cannot create a pretty-printer for the value, it should return
1919 @value{GDBN} first checks the @code{pretty_printers} attribute of each
1920 @code{gdb.Objfile} in the current program space and iteratively calls
1921 each enabled lookup routine in the list for that @code{gdb.Objfile}
1922 until it receives a pretty-printer object.
1923 If no pretty-printer is found in the objfile lists, @value{GDBN} then
1924 searches the pretty-printer list of the current program space,
1925 calling each enabled function until an object is returned.
1926 After these lists have been exhausted, it tries the global
1927 @code{gdb.pretty_printers} list, again calling each enabled function until an
1930 The order in which the objfiles are searched is not specified. For a
1931 given list, functions are always invoked from the head of the list,
1932 and iterated over sequentially until the end of the list, or a printer
1935 For various reasons a pretty-printer may not work.
1936 For example, the underlying data structure may have changed and
1937 the pretty-printer is out of date.
1939 The consequences of a broken pretty-printer are severe enough that
1940 @value{GDBN} provides support for enabling and disabling individual
1941 printers. For example, if @code{print frame-arguments} is on,
1942 a backtrace can become highly illegible if any argument is printed
1943 with a broken printer.
1945 Pretty-printers are enabled and disabled by attaching an @code{enabled}
1946 attribute to the registered function or callable object. If this attribute
1947 is present and its value is @code{False}, the printer is disabled, otherwise
1948 the printer is enabled.
1950 @node Writing a Pretty-Printer
1951 @subsubsection Writing a Pretty-Printer
1952 @cindex writing a pretty-printer
1954 A pretty-printer consists of two parts: a lookup function to detect
1955 if the type is supported, and the printer itself.
1957 Here is an example showing how a @code{std::string} printer might be
1958 written. @xref{Pretty Printing API}, for details on the API this class
1959 must provide. Note that this example uses the @code{gdb.ValuePrinter}
1960 base class, and is careful to use a leading underscore for its local
1964 class StdStringPrinter(gdb.ValuePrinter):
1965 "Print a std::string"
1967 def __init__(self, val):
1970 def to_string(self):
1971 return self.__val['_M_dataplus']['_M_p']
1973 def display_hint(self):
1977 And here is an example showing how a lookup function for the printer
1978 example above might be written.
1981 def str_lookup_function(val):
1982 lookup_tag = val.type.tag
1983 if lookup_tag is None:
1985 regex = re.compile("^std::basic_string<char,.*>$")
1986 if regex.match(lookup_tag):
1987 return StdStringPrinter(val)
1991 The example lookup function extracts the value's type, and attempts to
1992 match it to a type that it can pretty-print. If it is a type the
1993 printer can pretty-print, it will return a printer object. If not, it
1994 returns @code{None}.
1996 We recommend that you put your core pretty-printers into a Python
1997 package. If your pretty-printers are for use with a library, we
1998 further recommend embedding a version number into the package name.
1999 This practice will enable @value{GDBN} to load multiple versions of
2000 your pretty-printers at the same time, because they will have
2003 You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
2004 can be evaluated multiple times without changing its meaning. An
2005 ideal auto-load file will consist solely of @code{import}s of your
2006 printer modules, followed by a call to a register pretty-printers with
2007 the current objfile.
2009 Taken as a whole, this approach will scale nicely to multiple
2010 inferiors, each potentially using a different library version.
2011 Embedding a version number in the Python package name will ensure that
2012 @value{GDBN} is able to load both sets of printers simultaneously.
2013 Then, because the search for pretty-printers is done by objfile, and
2014 because your auto-loaded code took care to register your library's
2015 printers with a specific objfile, @value{GDBN} will find the correct
2016 printers for the specific version of the library used by each
2019 To continue the @code{std::string} example (@pxref{Pretty Printing API}),
2020 this code might appear in @code{gdb.libstdcxx.v6}:
2023 def register_printers(objfile):
2024 objfile.pretty_printers.append(str_lookup_function)
2028 And then the corresponding contents of the auto-load file would be:
2031 import gdb.libstdcxx.v6
2032 gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
2035 The previous example illustrates a basic pretty-printer.
2036 There are a few things that can be improved on.
2037 The printer doesn't have a name, making it hard to identify in a
2038 list of installed printers. The lookup function has a name, but
2039 lookup functions can have arbitrary, even identical, names.
2041 Second, the printer only handles one type, whereas a library typically has
2042 several types. One could install a lookup function for each desired type
2043 in the library, but one could also have a single lookup function recognize
2044 several types. The latter is the conventional way this is handled.
2045 If a pretty-printer can handle multiple data types, then its
2046 @dfn{subprinters} are the printers for the individual data types.
2048 The @code{gdb.printing} module provides a formal way of solving these
2049 problems (@pxref{gdb.printing}).
2050 Here is another example that handles multiple types.
2052 These are the types we are going to pretty-print:
2055 struct foo @{ int a, b; @};
2056 struct bar @{ struct foo x, y; @};
2059 Here are the printers:
2062 class fooPrinter(gdb.ValuePrinter):
2063 """Print a foo object."""
2065 def __init__(self, val):
2068 def to_string(self):
2069 return ("a=<" + str(self.__val["a"]) +
2070 "> b=<" + str(self.__val["b"]) + ">")
2072 class barPrinter(gdb.ValuePrinter):
2073 """Print a bar object."""
2075 def __init__(self, val):
2078 def to_string(self):
2079 return ("x=<" + str(self.__val["x"]) +
2080 "> y=<" + str(self.__val["y"]) + ">")
2083 This example doesn't need a lookup function, that is handled by the
2084 @code{gdb.printing} module. Instead a function is provided to build up
2085 the object that handles the lookup.
2090 def build_pretty_printer():
2091 pp = gdb.printing.RegexpCollectionPrettyPrinter(
2093 pp.add_printer('foo', '^foo$', fooPrinter)
2094 pp.add_printer('bar', '^bar$', barPrinter)
2098 And here is the autoload support:
2103 gdb.printing.register_pretty_printer(
2104 gdb.current_objfile(),
2105 my_library.build_pretty_printer())
2108 Finally, when this printer is loaded into @value{GDBN}, here is the
2109 corresponding output of @samp{info pretty-printer}:
2112 (gdb) info pretty-printer
2119 @node Type Printing API
2120 @subsubsection Type Printing API
2121 @cindex type printing API for Python
2123 @value{GDBN} provides a way for Python code to customize type display.
2124 This is mainly useful for substituting canonical typedef names for
2127 @cindex type printer
2128 A @dfn{type printer} is just a Python object conforming to a certain
2129 protocol. A simple base class implementing the protocol is provided;
2130 see @ref{gdb.types}. A type printer must supply at least:
2132 @defivar type_printer enabled
2133 A boolean which is True if the printer is enabled, and False
2134 otherwise. This is manipulated by the @code{enable type-printer}
2135 and @code{disable type-printer} commands.
2138 @defivar type_printer name
2139 The name of the type printer. This must be a string. This is used by
2140 the @code{enable type-printer} and @code{disable type-printer}
2144 @defmethod type_printer instantiate (self)
2145 This is called by @value{GDBN} at the start of type-printing. It is
2146 only called if the type printer is enabled. This method must return a
2147 new object that supplies a @code{recognize} method, as described below.
2151 When displaying a type, say via the @code{ptype} command, @value{GDBN}
2152 will compute a list of type recognizers. This is done by iterating
2153 first over the per-objfile type printers (@pxref{Objfiles In Python}),
2154 followed by the per-progspace type printers (@pxref{Progspaces In
2155 Python}), and finally the global type printers.
2157 @value{GDBN} will call the @code{instantiate} method of each enabled
2158 type printer. If this method returns @code{None}, then the result is
2159 ignored; otherwise, it is appended to the list of recognizers.
2161 Then, when @value{GDBN} is going to display a type name, it iterates
2162 over the list of recognizers. For each one, it calls the recognition
2163 function, stopping if the function returns a non-@code{None} value.
2164 The recognition function is defined as:
2166 @defmethod type_recognizer recognize (self, type)
2167 If @var{type} is not recognized, return @code{None}. Otherwise,
2168 return a string which is to be printed as the name of @var{type}.
2169 The @var{type} argument will be an instance of @code{gdb.Type}
2170 (@pxref{Types In Python}).
2173 @value{GDBN} uses this two-pass approach so that type printers can
2174 efficiently cache information without holding on to it too long. For
2175 example, it can be convenient to look up type information in a type
2176 printer and hold it for a recognizer's lifetime; if a single pass were
2177 done then type printers would have to make use of the event system in
2178 order to avoid holding information that could become stale as the
2181 @node Frame Filter API
2182 @subsubsection Filtering Frames
2183 @cindex frame filters api
2185 Frame filters are Python objects that manipulate the visibility of a
2186 frame or frames when a backtrace (@pxref{Backtrace}) is printed by
2189 Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
2190 commands (@pxref{GDB/MI}), those that return a collection of frames
2191 are affected. The commands that work with frame filters are:
2193 @code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
2194 @code{-stack-list-frames}
2195 (@pxref{-stack-list-frames,, The -stack-list-frames command}),
2196 @code{-stack-list-variables} (@pxref{-stack-list-variables,, The
2197 -stack-list-variables command}), @code{-stack-list-arguments}
2198 @pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
2199 @code{-stack-list-locals} (@pxref{-stack-list-locals,, The
2200 -stack-list-locals command}).
2202 A frame filter works by taking an iterator as an argument, applying
2203 actions to the contents of that iterator, and returning another
2204 iterator (or, possibly, the same iterator it was provided in the case
2205 where the filter does not perform any operations). Typically, frame
2206 filters utilize tools such as the Python's @code{itertools} module to
2207 work with and create new iterators from the source iterator.
2208 Regardless of how a filter chooses to apply actions, it must not alter
2209 the underlying @value{GDBN} frame or frames, or attempt to alter the
2210 call-stack within @value{GDBN}. This preserves data integrity within
2211 @value{GDBN}. Frame filters are executed on a priority basis and care
2212 should be taken that some frame filters may have been executed before,
2213 and that some frame filters will be executed after.
2215 An important consideration when designing frame filters, and well
2216 worth reflecting upon, is that frame filters should avoid unwinding
2217 the call stack if possible. Some stacks can run very deep, into the
2218 tens of thousands in some cases. To search every frame when a frame
2219 filter executes may be too expensive at that step. The frame filter
2220 cannot know how many frames it has to iterate over, and it may have to
2221 iterate through them all. This ends up duplicating effort as
2222 @value{GDBN} performs this iteration when it prints the frames. If
2223 the filter can defer unwinding frames until frame decorators are
2224 executed, after the last filter has executed, it should. @xref{Frame
2225 Decorator API}, for more information on decorators. Also, there are
2226 examples for both frame decorators and filters in later chapters.
2227 @xref{Writing a Frame Filter}, for more information.
2229 The Python dictionary @code{gdb.frame_filters} contains key/object
2230 pairings that comprise a frame filter. Frame filters in this
2231 dictionary are called @code{global} frame filters, and they are
2232 available when debugging all inferiors. These frame filters must
2233 register with the dictionary directly. In addition to the
2234 @code{global} dictionary, there are other dictionaries that are loaded
2235 with different inferiors via auto-loading (@pxref{Python
2236 Auto-loading}). The two other areas where frame filter dictionaries
2237 can be found are: @code{gdb.Progspace} which contains a
2238 @code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
2239 object which also contains a @code{frame_filters} dictionary
2242 When a command is executed from @value{GDBN} that is compatible with
2243 frame filters, @value{GDBN} combines the @code{global},
2244 @code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
2245 loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
2246 several frames, and thus several object files, might be in use.
2247 @value{GDBN} then prunes any frame filter whose @code{enabled}
2248 attribute is @code{False}. This pruned list is then sorted according
2249 to the @code{priority} attribute in each filter.
2251 Once the dictionaries are combined, pruned and sorted, @value{GDBN}
2252 creates an iterator which wraps each frame in the call stack in a
2253 @code{FrameDecorator} object, and calls each filter in order. The
2254 output from the previous filter will always be the input to the next
2257 Frame filters have a mandatory interface which each frame filter must
2258 implement, defined here:
2260 @defun FrameFilter.filter (iterator)
2261 @value{GDBN} will call this method on a frame filter when it has
2262 reached the order in the priority list for that filter.
2264 For example, if there are four frame filters:
2275 The order that the frame filters will be called is:
2278 Filter3 -> Filter2 -> Filter1 -> Filter4
2281 Note that the output from @code{Filter3} is passed to the input of
2282 @code{Filter2}, and so on.
2284 This @code{filter} method is passed a Python iterator. This iterator
2285 contains a sequence of frame decorators that wrap each
2286 @code{gdb.Frame}, or a frame decorator that wraps another frame
2287 decorator. The first filter that is executed in the sequence of frame
2288 filters will receive an iterator entirely comprised of default
2289 @code{FrameDecorator} objects. However, after each frame filter is
2290 executed, the previous frame filter may have wrapped some or all of
2291 the frame decorators with their own frame decorator. As frame
2292 decorators must also conform to a mandatory interface, these
2293 decorators can be assumed to act in a uniform manner (@pxref{Frame
2296 This method must return an object conforming to the Python iterator
2297 protocol. Each item in the iterator must be an object conforming to
2298 the frame decorator interface. If a frame filter does not wish to
2299 perform any operations on this iterator, it should return that
2302 This method is not optional. If it does not exist, @value{GDBN} will
2303 raise and print an error.
2306 @defvar FrameFilter.name
2307 The @code{name} attribute must be Python string which contains the
2308 name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
2309 Management}). This attribute may contain any combination of letters
2310 or numbers. Care should be taken to ensure that it is unique. This
2311 attribute is mandatory.
2314 @defvar FrameFilter.enabled
2315 The @code{enabled} attribute must be Python boolean. This attribute
2316 indicates to @value{GDBN} whether the frame filter is enabled, and
2317 should be considered when frame filters are executed. If
2318 @code{enabled} is @code{True}, then the frame filter will be executed
2319 when any of the backtrace commands detailed earlier in this chapter
2320 are executed. If @code{enabled} is @code{False}, then the frame
2321 filter will not be executed. This attribute is mandatory.
2324 @defvar FrameFilter.priority
2325 The @code{priority} attribute must be Python integer. This attribute
2326 controls the order of execution in relation to other frame filters.
2327 There are no imposed limits on the range of @code{priority} other than
2328 it must be a valid integer. The higher the @code{priority} attribute,
2329 the sooner the frame filter will be executed in relation to other
2330 frame filters. Although @code{priority} can be negative, it is
2331 recommended practice to assume zero is the lowest priority that a
2332 frame filter can be assigned. Frame filters that have the same
2333 priority are executed in unsorted order in that priority slot. This
2334 attribute is mandatory. 100 is a good default priority.
2337 @node Frame Decorator API
2338 @subsubsection Decorating Frames
2339 @cindex frame decorator api
2341 Frame decorators are sister objects to frame filters (@pxref{Frame
2342 Filter API}). Frame decorators are applied by a frame filter and can
2343 only be used in conjunction with frame filters.
2345 The purpose of a frame decorator is to customize the printed content
2346 of each @code{gdb.Frame} in commands where frame filters are executed.
2347 This concept is called decorating a frame. Frame decorators decorate
2348 a @code{gdb.Frame} with Python code contained within each API call.
2349 This separates the actual data contained in a @code{gdb.Frame} from
2350 the decorated data produced by a frame decorator. This abstraction is
2351 necessary to maintain integrity of the data contained in each
2354 Frame decorators have a mandatory interface, defined below.
2356 @value{GDBN} already contains a frame decorator called
2357 @code{FrameDecorator}. This contains substantial amounts of
2358 boilerplate code to decorate the content of a @code{gdb.Frame}. It is
2359 recommended that other frame decorators inherit and extend this
2360 object, and only to override the methods needed.
2362 @tindex gdb.FrameDecorator
2363 @code{FrameDecorator} is defined in the Python module
2364 @code{gdb.FrameDecorator}, so your code can import it like:
2366 from gdb.FrameDecorator import FrameDecorator
2369 @defun FrameDecorator.elided (self)
2371 The @code{elided} method groups frames together in a hierarchical
2372 system. An example would be an interpreter, where multiple low-level
2373 frames make up a single call in the interpreted language. In this
2374 example, the frame filter would elide the low-level frames and present
2375 a single high-level frame, representing the call in the interpreted
2376 language, to the user.
2378 The @code{elided} function must return an iterable and this iterable
2379 must contain the frames that are being elided wrapped in a suitable
2380 frame decorator. If no frames are being elided this function may
2381 return an empty iterable, or @code{None}. Elided frames are indented
2382 from normal frames in a @code{CLI} backtrace, or in the case of
2383 @sc{gdb/mi}, are placed in the @code{children} field of the eliding
2386 It is the frame filter's task to also filter out the elided frames from
2387 the source iterator. This will avoid printing the frame twice.
2390 @defun FrameDecorator.function (self)
2392 This method returns the name of the function in the frame that is to
2395 This method must return a Python string describing the function, or
2398 If this function returns @code{None}, @value{GDBN} will not print any
2399 data for this field.
2402 @defun FrameDecorator.address (self)
2404 This method returns the address of the frame that is to be printed.
2406 This method must return a Python numeric integer type of sufficient
2407 size to describe the address of the frame, or @code{None}.
2409 If this function returns a @code{None}, @value{GDBN} will not print
2410 any data for this field.
2413 @defun FrameDecorator.filename (self)
2415 This method returns the filename and path associated with this frame.
2417 This method must return a Python string containing the filename and
2418 the path to the object file backing the frame, or @code{None}.
2420 If this function returns a @code{None}, @value{GDBN} will not print
2421 any data for this field.
2424 @defun FrameDecorator.line (self):
2426 This method returns the line number associated with the current
2427 position within the function addressed by this frame.
2429 This method must return a Python integer type, or @code{None}.
2431 If this function returns a @code{None}, @value{GDBN} will not print
2432 any data for this field.
2435 @defun FrameDecorator.frame_args (self)
2438 This method must return an iterable, or @code{None}. Returning an
2439 empty iterable, or @code{None} means frame arguments will not be
2440 printed for this frame. This iterable must contain objects that
2441 implement two methods, described here.
2443 This object must implement a @code{symbol} method which takes a
2444 single @code{self} parameter and must return a @code{gdb.Symbol}
2445 (@pxref{Symbols In Python}), or a Python string. The object must also
2446 implement a @code{value} method which takes a single @code{self}
2447 parameter and must return a @code{gdb.Value} (@pxref{Values From
2448 Inferior}), a Python value, or @code{None}. If the @code{value}
2449 method returns @code{None}, and the @code{argument} method returns a
2450 @code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
2451 the @code{gdb.Symbol} automatically.
2456 class SymValueWrapper():
2458 def __init__(self, symbol, value):
2468 class SomeFrameDecorator()
2471 def frame_args(self):
2474 block = self.inferior_frame.block()
2478 # Iterate over all symbols in a block. Only add
2479 # symbols that are arguments.
2481 if not sym.is_argument:
2483 args.append(SymValueWrapper(sym,None))
2485 # Add example synthetic argument.
2486 args.append(SymValueWrapper(``foo'', 42))
2492 @defun FrameDecorator.frame_locals (self)
2494 This method must return an iterable or @code{None}. Returning an
2495 empty iterable, or @code{None} means frame local arguments will not be
2496 printed for this frame.
2498 The object interface, the description of the various strategies for
2499 reading frame locals, and the example are largely similar to those
2500 described in the @code{frame_args} function, (@pxref{frame_args,,The
2501 frame filter frame_args function}). Below is a modified example:
2504 class SomeFrameDecorator()
2507 def frame_locals(self):
2510 block = self.inferior_frame.block()
2514 # Iterate over all symbols in a block. Add all
2515 # symbols, except arguments.
2519 vars.append(SymValueWrapper(sym,None))
2521 # Add an example of a synthetic local variable.
2522 vars.append(SymValueWrapper(``bar'', 99))
2528 @defun FrameDecorator.inferior_frame (self):
2530 This method must return the underlying @code{gdb.Frame} that this
2531 frame decorator is decorating. @value{GDBN} requires the underlying
2532 frame for internal frame information to determine how to print certain
2533 values when printing a frame.
2536 @node Writing a Frame Filter
2537 @subsubsection Writing a Frame Filter
2538 @cindex writing a frame filter
2540 There are three basic elements that a frame filter must implement: it
2541 must correctly implement the documented interface (@pxref{Frame Filter
2542 API}), it must register itself with @value{GDBN}, and finally, it must
2543 decide if it is to work on the data provided by @value{GDBN}. In all
2544 cases, whether it works on the iterator or not, each frame filter must
2545 return an iterator. A bare-bones frame filter follows the pattern in
2546 the following example.
2551 class FrameFilter():
2554 # Frame filter attribute creation.
2556 # 'name' is the name of the filter that GDB will display.
2558 # 'priority' is the priority of the filter relative to other
2561 # 'enabled' is a boolean that indicates whether this filter is
2562 # enabled and should be executed.
2568 # Register this frame filter with the global frame_filters
2570 gdb.frame_filters[self.name] = self
2572 def filter(self, frame_iter):
2573 # Just return the iterator.
2577 The frame filter in the example above implements the three
2578 requirements for all frame filters. It implements the API, self
2579 registers, and makes a decision on the iterator (in this case, it just
2580 returns the iterator untouched).
2582 The first step is attribute creation and assignment, and as shown in
2583 the comments the filter assigns the following attributes: @code{name},
2584 @code{priority} and whether the filter should be enabled with the
2585 @code{enabled} attribute.
2587 The second step is registering the frame filter with the dictionary or
2588 dictionaries that the frame filter has interest in. As shown in the
2589 comments, this filter just registers itself with the global dictionary
2590 @code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
2591 is a dictionary that is initialized in the @code{gdb} module when
2592 @value{GDBN} starts. What dictionary a filter registers with is an
2593 important consideration. Generally, if a filter is specific to a set
2594 of code, it should be registered either in the @code{objfile} or
2595 @code{progspace} dictionaries as they are specific to the program
2596 currently loaded in @value{GDBN}. The global dictionary is always
2597 present in @value{GDBN} and is never unloaded. Any filters registered
2598 with the global dictionary will exist until @value{GDBN} exits. To
2599 avoid filters that may conflict, it is generally better to register
2600 frame filters against the dictionaries that more closely align with
2601 the usage of the filter currently in question. @xref{Python
2602 Auto-loading}, for further information on auto-loading Python scripts.
2604 @value{GDBN} takes a hands-off approach to frame filter registration,
2605 therefore it is the frame filter's responsibility to ensure
2606 registration has occurred, and that any exceptions are handled
2607 appropriately. In particular, you may wish to handle exceptions
2608 relating to Python dictionary key uniqueness. It is mandatory that
2609 the dictionary key is the same as frame filter's @code{name}
2610 attribute. When a user manages frame filters (@pxref{Frame Filter
2611 Management}), the names @value{GDBN} will display are those contained
2612 in the @code{name} attribute.
2614 The final step of this example is the implementation of the
2615 @code{filter} method. As shown in the example comments, we define the
2616 @code{filter} method and note that the method must take an iterator,
2617 and also must return an iterator. In this bare-bones example, the
2618 frame filter is not very useful as it just returns the iterator
2619 untouched. However this is a valid operation for frame filters that
2620 have the @code{enabled} attribute set, but decide not to operate on
2623 In the next example, the frame filter operates on all frames and
2624 utilizes a frame decorator to perform some work on the frames.
2625 @xref{Frame Decorator API}, for further information on the frame
2626 decorator interface.
2628 This example works on inlined frames. It highlights frames which are
2629 inlined by tagging them with an ``[inlined]'' tag. By applying a
2630 frame decorator to all frames with the Python @code{itertools imap}
2631 method, the example defers actions to the frame decorator. Frame
2632 decorators are only processed when @value{GDBN} prints the backtrace.
2634 This introduces a new decision making topic: whether to perform
2635 decision making operations at the filtering step, or at the printing
2636 step. In this example's approach, it does not perform any filtering
2637 decisions at the filtering step beyond mapping a frame decorator to
2638 each frame. This allows the actual decision making to be performed
2639 when each frame is printed. This is an important consideration, and
2640 well worth reflecting upon when designing a frame filter. An issue
2641 that frame filters should avoid is unwinding the stack if possible.
2642 Some stacks can run very deep, into the tens of thousands in some
2643 cases. To search every frame to determine if it is inlined ahead of
2644 time may be too expensive at the filtering step. The frame filter
2645 cannot know how many frames it has to iterate over, and it would have
2646 to iterate through them all. This ends up duplicating effort as
2647 @value{GDBN} performs this iteration when it prints the frames.
2649 In this example decision making can be deferred to the printing step.
2650 As each frame is printed, the frame decorator can examine each frame
2651 in turn when @value{GDBN} iterates. From a performance viewpoint,
2652 this is the most appropriate decision to make as it avoids duplicating
2653 the effort that the printing step would undertake anyway. Also, if
2654 there are many frame filters unwinding the stack during filtering, it
2655 can substantially delay the printing of the backtrace which will
2656 result in large memory usage, and a poor user experience.
2659 class InlineFilter():
2662 self.name = "InlinedFrameFilter"
2665 gdb.frame_filters[self.name] = self
2667 def filter(self, frame_iter):
2668 frame_iter = itertools.imap(InlinedFrameDecorator,
2673 This frame filter is somewhat similar to the earlier example, except
2674 that the @code{filter} method applies a frame decorator object called
2675 @code{InlinedFrameDecorator} to each element in the iterator. The
2676 @code{imap} Python method is light-weight. It does not proactively
2677 iterate over the iterator, but rather creates a new iterator which
2678 wraps the existing one.
2680 Below is the frame decorator for this example.
2683 class InlinedFrameDecorator(FrameDecorator):
2685 def __init__(self, fobj):
2686 super(InlinedFrameDecorator, self).__init__(fobj)
2689 frame = self.inferior_frame()
2690 name = str(frame.name())
2692 if frame.type() == gdb.INLINE_FRAME:
2693 name = name + " [inlined]"
2698 This frame decorator only defines and overrides the @code{function}
2699 method. It lets the supplied @code{FrameDecorator}, which is shipped
2700 with @value{GDBN}, perform the other work associated with printing
2703 The combination of these two objects create this output from a
2707 #0 0x004004e0 in bar () at inline.c:11
2708 #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
2709 #2 0x00400566 in main () at inline.c:31
2712 So in the case of this example, a frame decorator is applied to all
2713 frames, regardless of whether they may be inlined or not. As
2714 @value{GDBN} iterates over the iterator produced by the frame filters,
2715 @value{GDBN} executes each frame decorator which then makes a decision
2716 on what to print in the @code{function} callback. Using a strategy
2717 like this is a way to defer decisions on the frame content to printing
2720 @subheading Eliding Frames
2722 It might be that the above example is not desirable for representing
2723 inlined frames, and a hierarchical approach may be preferred. If we
2724 want to hierarchically represent frames, the @code{elided} frame
2725 decorator interface might be preferable.
2727 This example approaches the issue with the @code{elided} method. This
2728 example is quite long, but very simplistic. It is out-of-scope for
2729 this section to write a complete example that comprehensively covers
2730 all approaches of finding and printing inlined frames. However, this
2731 example illustrates the approach an author might use.
2733 This example comprises of three sections.
2736 class InlineFrameFilter():
2739 self.name = "InlinedFrameFilter"
2742 gdb.frame_filters[self.name] = self
2744 def filter(self, frame_iter):
2745 return ElidingInlineIterator(frame_iter)
2748 This frame filter is very similar to the other examples. The only
2749 difference is this frame filter is wrapping the iterator provided to
2750 it (@code{frame_iter}) with a custom iterator called
2751 @code{ElidingInlineIterator}. This again defers actions to when
2752 @value{GDBN} prints the backtrace, as the iterator is not traversed
2755 The iterator for this example is as follows. It is in this section of
2756 the example where decisions are made on the content of the backtrace.
2759 class ElidingInlineIterator:
2760 def __init__(self, ii):
2761 self.input_iterator = ii
2767 frame = next(self.input_iterator)
2769 if frame.inferior_frame().type() != gdb.INLINE_FRAME:
2773 eliding_frame = next(self.input_iterator)
2774 except StopIteration:
2776 return ElidingFrameDecorator(eliding_frame, [frame])
2779 This iterator implements the Python iterator protocol. When the
2780 @code{next} function is called (when @value{GDBN} prints each frame),
2781 the iterator checks if this frame decorator, @code{frame}, is wrapping
2782 an inlined frame. If it is not, it returns the existing frame decorator
2783 untouched. If it is wrapping an inlined frame, it assumes that the
2784 inlined frame was contained within the next oldest frame,
2785 @code{eliding_frame}, which it fetches. It then creates and returns a
2786 frame decorator, @code{ElidingFrameDecorator}, which contains both the
2787 elided frame, and the eliding frame.
2790 class ElidingInlineDecorator(FrameDecorator):
2792 def __init__(self, frame, elided_frames):
2793 super(ElidingInlineDecorator, self).__init__(frame)
2795 self.elided_frames = elided_frames
2798 return iter(self.elided_frames)
2801 This frame decorator overrides one function and returns the inlined
2802 frame in the @code{elided} method. As before it lets
2803 @code{FrameDecorator} do the rest of the work involved in printing
2804 this frame. This produces the following output.
2807 #0 0x004004e0 in bar () at inline.c:11
2808 #2 0x00400529 in main () at inline.c:25
2809 #1 0x00400529 in max (b=6, a=12) at inline.c:15
2812 In that output, @code{max} which has been inlined into @code{main} is
2813 printed hierarchically. Another approach would be to combine the
2814 @code{function} method, and the @code{elided} method to both print a
2815 marker in the inlined frame, and also show the hierarchical
2818 @node Unwinding Frames in Python
2819 @subsubsection Unwinding Frames in Python
2820 @cindex unwinding frames in Python
2822 In @value{GDBN} terminology ``unwinding'' is the process of finding
2823 the previous frame (that is, caller's) from the current one. An
2824 unwinder has three methods. The first one checks if it can handle
2825 given frame (``sniff'' it). For the frames it can sniff an unwinder
2826 provides two additional methods: it can return frame's ID, and it can
2827 fetch registers from the previous frame. A running @value{GDBN}
2828 mantains a list of the unwinders and calls each unwinder's sniffer in
2829 turn until it finds the one that recognizes the current frame. There
2830 is an API to register an unwinder.
2832 The unwinders that come with @value{GDBN} handle standard frames.
2833 However, mixed language applications (for example, an application
2834 running Java Virtual Machine) sometimes use frame layouts that cannot
2835 be handled by the @value{GDBN} unwinders. You can write Python code
2836 that can handle such custom frames.
2838 You implement a frame unwinder in Python as a class with which has two
2839 attributes, @code{name} and @code{enabled}, with obvious meanings, and
2840 a single method @code{__call__}, which examines a given frame and
2841 returns an object (an instance of @code{gdb.UnwindInfo class)}
2842 describing it. If an unwinder does not recognize a frame, it should
2843 return @code{None}. The code in @value{GDBN} that enables writing
2844 unwinders in Python uses this object to return frame's ID and previous
2845 frame registers when @value{GDBN} core asks for them.
2847 An unwinder should do as little work as possible. Some otherwise
2848 innocuous operations can cause problems (even crashes, as this code is
2849 not well-hardened yet). For example, making an inferior call from
2850 an unwinder is unadvisable, as an inferior call will reset
2851 @value{GDBN}'s stack unwinding process, potentially causing re-entrant
2854 @subheading Unwinder Input
2856 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
2857 provides a method to read frame's registers:
2859 @defun PendingFrame.read_register (register)
2860 This method returns the contents of @var{register} in the
2861 frame as a @code{gdb.Value} object. For a description of the
2862 acceptable values of @var{register} see
2863 @ref{gdbpy_frame_read_register,,Frame.read_register}. If @var{register}
2864 does not name a register for the current architecture, this method
2865 will throw an exception.
2867 Note that this method will always return a @code{gdb.Value} for a
2868 valid register name. This does not mean that the value will be valid.
2869 For example, you may request a register that an earlier unwinder could
2870 not unwind---the value will be unavailable. Instead, the
2871 @code{gdb.Value} returned from this method will be lazy; that is, its
2872 underlying bits will not be fetched until it is first used. So,
2873 attempting to use such a value will cause an exception at the point of
2876 The type of the returned @code{gdb.Value} depends on the register and
2877 the architecture. It is common for registers to have a scalar type,
2878 like @code{long long}; but many other types are possible, such as
2879 pointer, pointer-to-function, floating point or vector types.
2882 It also provides a factory method to create a @code{gdb.UnwindInfo}
2883 instance to be returned to @value{GDBN}:
2885 @anchor{gdb.PendingFrame.create_unwind_info}
2886 @defun PendingFrame.create_unwind_info (frame_id)
2887 Returns a new @code{gdb.UnwindInfo} instance identified by given
2888 @var{frame_id}. The @var{frame_id} is used internally by @value{GDBN}
2889 to identify the frames within the current thread's stack. The
2890 attributes of @var{frame_id} determine what type of frame is
2891 created within @value{GDBN}:
2895 The frame is identified by the given stack address and PC. The stack
2896 address must be chosen so that it is constant throughout the lifetime
2897 of the frame, so a typical choice is the value of the stack pointer at
2898 the start of the function---in the DWARF standard, this would be the
2899 ``Call Frame Address''.
2901 This is the most common case by far. The other cases are documented
2902 for completeness but are only useful in specialized situations.
2904 @item sp, pc, special
2905 The frame is identified by the stack address, the PC, and a
2906 ``special'' address. The special address is used on architectures
2907 that can have frames that do not change the stack, but which are still
2908 distinct, for example the IA-64, which has a second stack for
2909 registers. Both @var{sp} and @var{special} must be constant
2910 throughout the lifetime of the frame.
2913 The frame is identified by the stack address only. Any other stack
2914 frame with a matching @var{sp} will be considered to match this frame.
2915 Inside gdb, this is called a ``wild frame''. You will never need
2919 Each attribute value should either be an instance of @code{gdb.Value}
2922 A helper class is provided in the @code{gdb.unwinder} module that can
2923 be used to represent a frame-id
2924 (@pxref{gdb.unwinder.FrameId}).
2928 @defun PendingFrame.architecture ()
2929 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
2930 for this @code{gdb.PendingFrame}. This represents the architecture of
2931 the particular frame being unwound.
2934 @defun PendingFrame.level ()
2935 Return an integer, the stack frame level for this frame.
2936 @xref{Frames, ,Stack Frames}.
2939 @defun PendingFrame.name ()
2940 Returns the function name of this pending frame, or @code{None} if it
2944 @defun PendingFrame.is_valid ()
2945 Returns true if the @code{gdb.PendingFrame} object is valid, false if
2946 not. A pending frame object becomes invalid when the call to the
2947 unwinder, for which the pending frame was created, returns.
2949 All @code{gdb.PendingFrame} methods, except this one, will raise an
2950 exception if the pending frame object is invalid at the time the
2954 @defun PendingFrame.pc ()
2955 Returns the pending frame's resume address.
2958 @defun PendingFrame.block ()
2959 Return the pending frame's code block (@pxref{Blocks In Python}). If
2960 the frame does not have a block -- for example, if there is no
2961 debugging information for the code in question -- then this will raise
2962 a @code{RuntimeError} exception.
2965 @defun PendingFrame.function ()
2966 Return the symbol for the function corresponding to this pending frame.
2967 @xref{Symbols In Python}.
2970 @defun PendingFrame.find_sal ()
2971 Return the pending frame's symtab and line object (@pxref{Symbol
2975 @defun PendingFrame.language ()
2976 Return the language of this frame, as a string, or None.
2979 @subheading Unwinder Output: UnwindInfo
2981 Use @code{PendingFrame.create_unwind_info} method described above to
2982 create a @code{gdb.UnwindInfo} instance. Use the following method to
2983 specify caller registers that have been saved in this frame:
2985 @defun gdb.UnwindInfo.add_saved_register (register, value)
2986 @var{register} identifies the register, for a description of the acceptable
2987 values see @ref{gdbpy_frame_read_register,,Frame.read_register}.
2988 @var{value} is a register value (a @code{gdb.Value} object).
2991 @subheading The @code{gdb.unwinder} Module
2993 @value{GDBN} comes with a @code{gdb.unwinder} module which contains
2994 the following classes:
2996 @deftp {class} gdb.unwinder.Unwinder
2997 The @code{Unwinder} class is a base class from which user created
2998 unwinders can derive, though it is not required that unwinders derive
2999 from this class, so long as any user created unwinder has the required
3000 @code{name} and @code{enabled} attributes.
3002 @defun gdb.unwinder.Unwinder.__init__(name)
3003 The @var{name} is a string used to reference this unwinder within some
3004 @value{GDBN} commands (@pxref{Managing Registered Unwinders}).
3007 @defvar gdb.unwinder.name
3008 A read-only attribute which is a string, the name of this unwinder.
3011 @defvar gdb.unwinder.enabled
3012 A modifiable attribute containing a boolean; when @code{True}, the
3013 unwinder is enabled, and will be used by @value{GDBN}. When
3014 @code{False}, the unwinder has been disabled, and will not be used.
3018 @anchor{gdb.unwinder.FrameId}
3019 @deftp {class} gdb.unwinder.FrameId
3020 This is a class suitable for being used as the frame-id when calling
3021 @code{gdb.PendingFrame.create_unwind_info}. It is not required to use
3022 this class, any class with the required attribute
3023 (@pxref{gdb.PendingFrame.create_unwind_info}) will be accepted, but in
3024 most cases this class will be sufficient.
3026 @code{gdb.unwinder.FrameId} has the following method:
3028 @defun gdb.unwinder.FrameId.__init__(sp, pc, special = @code{None})
3029 The @var{sp} and @var{pc} arguments are required and should be either
3030 a @code{gdb.Value} object, or an integer.
3032 The @var{special} argument is optional; if specified, it should be a
3033 @code{gdb.Value} object, or an integer.
3036 @code{gdb.unwinder.FrameId} has the following read-only attributes:
3038 @defvar gdb.unwinder.sp
3039 The @var{sp} value passed to the constructor.
3042 @defvar gdb.unwinder.pc
3043 The @var{pc} value passed to the constructor.
3046 @defvar gdb.unwinder.special
3047 The @var{special} value passed to the constructor, or @code{None} if
3048 no such value was passed.
3052 @subheading Registering an Unwinder
3054 Object files and program spaces can have unwinders registered with
3055 them. In addition, you can register unwinders globally.
3057 The @code{gdb.unwinders} module provides the function to register an
3060 @defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
3061 @var{locus} specifies to which unwinder list to prepend the
3062 @var{unwinder}. It can be either an object file (@pxref{Objfiles In
3063 Python}), a program space (@pxref{Progspaces In Python}), or
3064 @code{None}, in which case the unwinder is registered globally. The
3065 newly added @var{unwinder} will be called before any other unwinder
3066 from the same locus. Two unwinders in the same locus cannot have the
3067 same name. An attempt to add an unwinder with an already existing
3068 name raises an exception unless @var{replace} is @code{True}, in which
3069 case the old unwinder is deleted and the new unwinder is registered in
3072 @value{GDBN} first calls the unwinders from all the object files in no
3073 particular order, then the unwinders from the current program space,
3074 then the globally registered unwinders, and finally the unwinders
3075 builtin to @value{GDBN}.
3078 @subheading Unwinder Skeleton Code
3080 Here is an example of how to structure a user created unwinder:
3083 from gdb.unwinder import Unwinder, FrameId
3085 class MyUnwinder(Unwinder):
3087 super().__init___("MyUnwinder_Name")
3089 def __call__(self, pending_frame):
3090 if not <we recognize frame>:
3093 # Create a FrameID. Usually the frame is identified by a
3094 # stack pointer and the function address.
3095 sp = ... compute a stack address ...
3096 pc = ... compute function address ...
3097 unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
3099 # Find the values of the registers in the caller's frame and
3100 # save them in the result:
3101 unwind_info.add_saved_register(<register-number>, <register-value>)
3104 # Return the result:
3107 gdb.unwinder.register_unwinder(<locus>, MyUnwinder(), <replace>)
3110 @anchor{Managing Registered Unwinders}
3111 @subheading Managing Registered Unwinders
3112 @value{GDBN} defines 3 commands to manage registered unwinders. These
3116 @item info unwinder @r{[} @var{locus} @r{[} @var{name-regexp} @r{]} @r{]}
3117 Lists all registered unwinders. Arguments @var{locus} and
3118 @var{name-regexp} are both optional and can be used to filter which
3119 unwinders are listed.
3121 The @var{locus} argument should be either @kbd{global},
3122 @kbd{progspace}, or the name of an object file. Only unwinders
3123 registered for the specified locus will be listed.
3125 The @var{name-regexp} is a regular expression used to match against
3126 unwinder names. When trying to match against unwinder names that
3127 include a string enclose @var{name-regexp} in quotes.
3128 @item disable unwinder @r{[} @var{locus} @r{[} @var{name-regexp} @r{]} @r{]}
3129 The @var{locus} and @var{name-regexp} are interpreted as in @kbd{info
3130 unwinder} above, but instead of listing the matching unwinders, all of
3131 the matching unwinders are disabled. The @code{enabled} field of each
3132 matching unwinder is set to @code{False}.
3133 @item enable unwinder @r{[} @var{locus} @r{[} @var{name-regexp} @r{]} @r{]}
3134 The @var{locus} and @var{name-regexp} are interpreted as in @kbd{info
3135 unwinder} above, but instead of listing the matching unwinders, all of
3136 the matching unwinders are enabled. The @code{enabled} field of each
3137 matching unwinder is set to @code{True}.
3140 @node Xmethods In Python
3141 @subsubsection Xmethods In Python
3142 @cindex xmethods in Python
3144 @dfn{Xmethods} are additional methods or replacements for existing
3145 methods of a C@t{++} class. This feature is useful for those cases
3146 where a method defined in C@t{++} source code could be inlined or
3147 optimized out by the compiler, making it unavailable to @value{GDBN}.
3148 For such cases, one can define an xmethod to serve as a replacement
3149 for the method defined in the C@t{++} source code. @value{GDBN} will
3150 then invoke the xmethod, instead of the C@t{++} method, to
3151 evaluate expressions. One can also use xmethods when debugging
3152 with core files. Moreover, when debugging live programs, invoking an
3153 xmethod need not involve running the inferior (which can potentially
3154 perturb its state). Hence, even if the C@t{++} method is available, it
3155 is better to use its replacement xmethod if one is defined.
3157 The xmethods feature in Python is available via the concepts of an
3158 @dfn{xmethod matcher} and an @dfn{xmethod worker}. To
3159 implement an xmethod, one has to implement a matcher and a
3160 corresponding worker for it (more than one worker can be
3161 implemented, each catering to a different overloaded instance of the
3162 method). Internally, @value{GDBN} invokes the @code{match} method of a
3163 matcher to match the class type and method name. On a match, the
3164 @code{match} method returns a list of matching @emph{worker} objects.
3165 Each worker object typically corresponds to an overloaded instance of
3166 the xmethod. They implement a @code{get_arg_types} method which
3167 returns a sequence of types corresponding to the arguments the xmethod
3168 requires. @value{GDBN} uses this sequence of types to perform
3169 overload resolution and picks a winning xmethod worker. A winner
3170 is also selected from among the methods @value{GDBN} finds in the
3171 C@t{++} source code. Next, the winning xmethod worker and the
3172 winning C@t{++} method are compared to select an overall winner. In
3173 case of a tie between a xmethod worker and a C@t{++} method, the
3174 xmethod worker is selected as the winner. That is, if a winning
3175 xmethod worker is found to be equivalent to the winning C@t{++}
3176 method, then the xmethod worker is treated as a replacement for
3177 the C@t{++} method. @value{GDBN} uses the overall winner to invoke the
3178 method. If the winning xmethod worker is the overall winner, then
3179 the corresponding xmethod is invoked via the @code{__call__} method
3180 of the worker object.
3182 If one wants to implement an xmethod as a replacement for an
3183 existing C@t{++} method, then they have to implement an equivalent
3184 xmethod which has exactly the same name and takes arguments of
3185 exactly the same type as the C@t{++} method. If the user wants to
3186 invoke the C@t{++} method even though a replacement xmethod is
3187 available for that method, then they can disable the xmethod.
3189 @xref{Xmethod API}, for API to implement xmethods in Python.
3190 @xref{Writing an Xmethod}, for implementing xmethods in Python.
3193 @subsubsection Xmethod API
3196 The @value{GDBN} Python API provides classes, interfaces and functions
3197 to implement, register and manipulate xmethods.
3198 @xref{Xmethods In Python}.
3200 An xmethod matcher should be an instance of a class derived from
3201 @code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an
3202 object with similar interface and attributes. An instance of
3203 @code{XMethodMatcher} has the following attributes:
3206 The name of the matcher.
3210 A boolean value indicating whether the matcher is enabled or disabled.
3214 A list of named methods managed by the matcher. Each object in the list
3215 is an instance of the class @code{XMethod} defined in the module
3216 @code{gdb.xmethod}, or any object with the following attributes:
3221 Name of the xmethod which should be unique for each xmethod
3222 managed by the matcher.
3225 A boolean value indicating whether the xmethod is enabled or
3230 The class @code{XMethod} is a convenience class with same
3231 attributes as above along with the following constructor:
3233 @defun XMethod.__init__ (self, name)
3234 Constructs an enabled xmethod with name @var{name}.
3239 The @code{XMethodMatcher} class has the following methods:
3241 @defun XMethodMatcher.__init__ (self, name)
3242 Constructs an enabled xmethod matcher with name @var{name}. The
3243 @code{methods} attribute is initialized to @code{None}.
3246 @defun XMethodMatcher.match (self, class_type, method_name)
3247 Derived classes should override this method. It should return a
3248 xmethod worker object (or a sequence of xmethod worker
3249 objects) matching the @var{class_type} and @var{method_name}.
3250 @var{class_type} is a @code{gdb.Type} object, and @var{method_name}
3251 is a string value. If the matcher manages named methods as listed in
3252 its @code{methods} attribute, then only those worker objects whose
3253 corresponding entries in the @code{methods} list are enabled should be
3257 An xmethod worker should be an instance of a class derived from
3258 @code{XMethodWorker} defined in the module @code{gdb.xmethod},
3259 or support the following interface:
3261 @defun XMethodWorker.get_arg_types (self)
3262 This method returns a sequence of @code{gdb.Type} objects corresponding
3263 to the arguments that the xmethod takes. It can return an empty
3264 sequence or @code{None} if the xmethod does not take any arguments.
3265 If the xmethod takes a single argument, then a single
3266 @code{gdb.Type} object corresponding to it can be returned.
3269 @defun XMethodWorker.get_result_type (self, *args)
3270 This method returns a @code{gdb.Type} object representing the type
3271 of the result of invoking this xmethod.
3272 The @var{args} argument is the same tuple of arguments that would be
3273 passed to the @code{__call__} method of this worker.
3276 @defun XMethodWorker.__call__ (self, *args)
3277 This is the method which does the @emph{work} of the xmethod. The
3278 @var{args} arguments is the tuple of arguments to the xmethod. Each
3279 element in this tuple is a gdb.Value object. The first element is
3280 always the @code{this} pointer value.
3283 For @value{GDBN} to lookup xmethods, the xmethod matchers
3284 should be registered using the following function defined in the module
3287 @defun register_xmethod_matcher (locus, matcher, replace=False)
3288 The @code{matcher} is registered with @code{locus}, replacing an
3289 existing matcher with the same name as @code{matcher} if
3290 @code{replace} is @code{True}. @code{locus} can be a
3291 @code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a
3292 @code{gdb.Progspace} object (@pxref{Progspaces In Python}), or
3293 @code{None}. If it is @code{None}, then @code{matcher} is registered
3297 @node Writing an Xmethod
3298 @subsubsection Writing an Xmethod
3299 @cindex writing xmethods in Python
3301 Implementing xmethods in Python will require implementing xmethod
3302 matchers and xmethod workers (@pxref{Xmethods In Python}). Consider
3303 the following C@t{++} class:
3309 MyClass (int a) : a_(a) @{ @}
3311 int geta (void) @{ return a_; @}
3312 int operator+ (int b);
3319 MyClass::operator+ (int b)
3326 Let us define two xmethods for the class @code{MyClass}, one
3327 replacing the method @code{geta}, and another adding an overloaded
3328 flavor of @code{operator+} which takes a @code{MyClass} argument (the
3329 C@t{++} code above already has an overloaded @code{operator+}
3330 which takes an @code{int} argument). The xmethod matcher can be
3334 class MyClass_geta(gdb.xmethod.XMethod):
3336 gdb.xmethod.XMethod.__init__(self, 'geta')
3338 def get_worker(self, method_name):
3339 if method_name == 'geta':
3340 return MyClassWorker_geta()
3343 class MyClass_sum(gdb.xmethod.XMethod):
3345 gdb.xmethod.XMethod.__init__(self, 'sum')
3347 def get_worker(self, method_name):
3348 if method_name == 'operator+':
3349 return MyClassWorker_plus()
3352 class MyClassMatcher(gdb.xmethod.XMethodMatcher):
3354 gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
3355 # List of methods 'managed' by this matcher
3356 self.methods = [MyClass_geta(), MyClass_sum()]
3358 def match(self, class_type, method_name):
3359 if class_type.tag != 'MyClass':
3362 for method in self.methods:
3364 worker = method.get_worker(method_name)
3366 workers.append(worker)
3372 Notice that the @code{match} method of @code{MyClassMatcher} returns
3373 a worker object of type @code{MyClassWorker_geta} for the @code{geta}
3374 method, and a worker object of type @code{MyClassWorker_plus} for the
3375 @code{operator+} method. This is done indirectly via helper classes
3376 derived from @code{gdb.xmethod.XMethod}. One does not need to use the
3377 @code{methods} attribute in a matcher as it is optional. However, if a
3378 matcher manages more than one xmethod, it is a good practice to list the
3379 xmethods in the @code{methods} attribute of the matcher. This will then
3380 facilitate enabling and disabling individual xmethods via the
3381 @code{enable/disable} commands. Notice also that a worker object is
3382 returned only if the corresponding entry in the @code{methods} attribute
3383 of the matcher is enabled.
3385 The implementation of the worker classes returned by the matcher setup
3386 above is as follows:
3389 class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
3390 def get_arg_types(self):
3393 def get_result_type(self, obj):
3394 return gdb.lookup_type('int')
3396 def __call__(self, obj):
3400 class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
3401 def get_arg_types(self):
3402 return gdb.lookup_type('MyClass')
3404 def get_result_type(self, obj):
3405 return gdb.lookup_type('int')
3407 def __call__(self, obj, other):
3408 return obj['a_'] + other['a_']
3411 For @value{GDBN} to actually lookup a xmethod, it has to be
3412 registered with it. The matcher defined above is registered with
3413 @value{GDBN} globally as follows:
3416 gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
3419 If an object @code{obj} of type @code{MyClass} is initialized in C@t{++}
3427 then, after loading the Python script defining the xmethod matchers
3428 and workers into @value{GDBN}, invoking the method @code{geta} or using
3429 the operator @code{+} on @code{obj} will invoke the xmethods
3440 Consider another example with a C++ template class:
3447 MyTemplate () : dsize_(10), data_ (new T [10]) @{ @}
3448 ~MyTemplate () @{ delete [] data_; @}
3450 int footprint (void)
3452 return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
3461 Let us implement an xmethod for the above class which serves as a
3462 replacement for the @code{footprint} method. The full code listing
3463 of the xmethod workers and xmethod matchers is as follows:
3466 class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
3467 def __init__(self, class_type):
3468 self.class_type = class_type
3470 def get_arg_types(self):
3473 def get_result_type(self):
3474 return gdb.lookup_type('int')
3476 def __call__(self, obj):
3477 return (self.class_type.sizeof +
3479 self.class_type.template_argument(0).sizeof)
3482 class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
3484 gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
3486 def match(self, class_type, method_name):
3487 if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
3489 method_name == 'footprint'):
3490 return MyTemplateWorker_footprint(class_type)
3493 Notice that, in this example, we have not used the @code{methods}
3494 attribute of the matcher as the matcher manages only one xmethod. The
3495 user can enable/disable this xmethod by enabling/disabling the matcher
3498 @node Inferiors In Python
3499 @subsubsection Inferiors In Python
3500 @cindex inferiors in Python
3502 @findex gdb.Inferior
3503 Programs which are being run under @value{GDBN} are called inferiors
3504 (@pxref{Inferiors Connections and Programs}). Python scripts can access
3505 information about and manipulate inferiors controlled by @value{GDBN}
3506 via objects of the @code{gdb.Inferior} class.
3508 The following inferior-related functions are available in the @code{gdb}
3511 @defun gdb.inferiors ()
3512 Return a tuple containing all inferior objects.
3515 @defun gdb.selected_inferior ()
3516 Return an object representing the current inferior.
3519 A @code{gdb.Inferior} object has the following attributes:
3521 @defvar Inferior.num
3522 ID of inferior, as assigned by @value{GDBN}. You can use this to make
3523 Python breakpoints inferior-specific, for example
3524 (@pxref{python_breakpoint_inferior,,The Breakpoint.inferior
3528 @anchor{gdbpy_inferior_connection}
3529 @defvar Inferior.connection
3530 The @code{gdb.TargetConnection} for this inferior (@pxref{Connections
3531 In Python}), or @code{None} if this inferior has no connection.
3534 @defvar Inferior.connection_num
3535 ID of inferior's connection as assigned by @value{GDBN}, or None if
3536 the inferior is not connected to a target. @xref{Inferiors Connections
3537 and Programs}. This is equivalent to
3538 @code{gdb.Inferior.connection.num} in the case where
3539 @code{gdb.Inferior.connection} is not @code{None}.
3542 @defvar Inferior.pid
3543 Process ID of the inferior, as assigned by the underlying operating
3547 @defvar Inferior.was_attached
3548 Boolean signaling whether the inferior was created using `attach', or
3549 started by @value{GDBN} itself.
3552 @defvar Inferior.main_name
3553 A string holding the name of this inferior's ``main'' function, if it
3554 can be determined. If the name of main is not known, this is
3558 @defvar Inferior.progspace
3559 The inferior's program space. @xref{Progspaces In Python}.
3562 @defvar Inferior.arguments
3563 The inferior's command line arguments, if known. This corresponds to
3564 the @code{set args} and @code{show args} commands. @xref{Arguments}.
3566 When accessed, the value is a string holding all the arguments. The
3567 contents are quoted as they would be when passed to the shell. If
3568 there are no arguments, the value is @code{None}.
3570 Either a string or a sequence of strings can be assigned to this
3571 attribute. When a string is assigned, it is assumed to have any
3572 necessary quoting for the shell; when a sequence is assigned, the
3573 quoting is applied by @value{GDBN}.
3576 A @code{gdb.Inferior} object has the following methods:
3578 @defun Inferior.is_valid ()
3579 Returns @code{True} if the @code{gdb.Inferior} object is valid,
3580 @code{False} if not. A @code{gdb.Inferior} object will become invalid
3581 if the inferior no longer exists within @value{GDBN}. All other
3582 @code{gdb.Inferior} methods will throw an exception if it is invalid
3583 at the time the method is called.
3586 @defun Inferior.threads ()
3587 This method returns a tuple holding all the threads which are valid
3588 when it is called. If there are no valid threads, the method will
3589 return an empty tuple.
3592 @defun Inferior.architecture ()
3593 Return the @code{gdb.Architecture} (@pxref{Architectures In Python})
3594 for this inferior. This represents the architecture of the inferior
3595 as a whole. Some platforms can have multiple architectures in a
3596 single address space, so this may not match the architecture of a
3597 particular frame (@pxref{Frames In Python}).
3600 @anchor{gdbpy_inferior_read_memory}
3601 @defun Inferior.read_memory (address, length)
3602 Read @var{length} addressable memory units from the inferior, starting
3603 at @var{address}. Returns a @code{memoryview} object, which behaves
3604 much like an array or a string. It can be modified and given to the
3605 @code{Inferior.write_memory} function.
3608 @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
3609 Write the contents of @var{buffer} to the inferior, starting at
3610 @var{address}. The @var{buffer} parameter must be a Python object
3611 which supports the buffer protocol, i.e., a string, an array or the
3612 object returned from @code{Inferior.read_memory}. If given, @var{length}
3613 determines the number of addressable memory units from @var{buffer} to be
3617 @defun Inferior.search_memory (address, length, pattern)
3618 Search a region of the inferior memory starting at @var{address} with
3619 the given @var{length} using the search pattern supplied in
3620 @var{pattern}. The @var{pattern} parameter must be a Python object
3621 which supports the buffer protocol, i.e., a string, an array or the
3622 object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
3623 containing the address where the pattern was found, or @code{None} if
3624 the pattern could not be found.
3627 @findex Inferior.thread_from_thread_handle
3628 @defun Inferior.thread_from_handle (handle)
3629 Return the thread object corresponding to @var{handle}, a thread
3630 library specific data structure such as @code{pthread_t} for pthreads
3631 library implementations.
3633 The function @code{Inferior.thread_from_thread_handle} provides
3634 the same functionality, but use of @code{Inferior.thread_from_thread_handle}
3639 The environment that will be passed to the inferior can be changed
3640 from Python by using the following methods. These methods only take
3641 effect when the inferior is started -- they will not affect an
3642 inferior that is already executing.
3644 @defun Inferior.clear_env ()
3645 Clear the current environment variables that will be passed to this
3649 @defun Inferior.set_env (name, value)
3650 Set the environment variable @var{name} to have the indicated value.
3651 Both parameters must be strings.
3654 @defun Inferior.unset_env (name)
3655 Unset the environment variable @var{name}. @var{name} must be a
3659 @node Events In Python
3660 @subsubsection Events In Python
3661 @cindex inferior events in Python
3663 @value{GDBN} provides a general event facility so that Python code can be
3664 notified of various state changes, particularly changes that occur in
3667 An @dfn{event} is just an object that describes some state change. The
3668 type of the object and its attributes will vary depending on the details
3669 of the change. All the existing events are described below.
3671 In order to be notified of an event, you must register an event handler
3672 with an @dfn{event registry}. An event registry is an object in the
3673 @code{gdb.events} module which dispatches particular events. A registry
3674 provides methods to register and unregister event handlers:
3676 @defun EventRegistry.connect (object)
3677 Add the given callable @var{object} to the registry. This object will be
3678 called when an event corresponding to this registry occurs.
3681 @defun EventRegistry.disconnect (object)
3682 Remove the given @var{object} from the registry. Once removed, the object
3683 will no longer receive notifications of events.
3689 def exit_handler (event):
3690 print ("event type: exit")
3691 if hasattr (event, 'exit_code'):
3692 print ("exit code: %d" % (event.exit_code))
3694 print ("exit code not available")
3696 gdb.events.exited.connect (exit_handler)
3699 In the above example we connect our handler @code{exit_handler} to the
3700 registry @code{events.exited}. Once connected, @code{exit_handler} gets
3701 called when the inferior exits. The argument @dfn{event} in this example is
3702 of type @code{gdb.ExitedEvent}. As you can see in the example the
3703 @code{ExitedEvent} object has an attribute which indicates the exit code of
3706 Some events can be thread specific when @value{GDBN} is running in
3707 non-stop mode. When represented in Python, these events all extend
3708 @code{gdb.ThreadEvent}. This event is a base class and is never
3709 emitted directly; instead, events which are emitted by this or other
3710 modules might extend this event. Examples of these events are
3711 @code{gdb.BreakpointEvent} and @code{gdb.ContinueEvent}.
3712 @code{gdb.ThreadEvent} holds the following attributes:
3714 @defvar ThreadEvent.inferior_thread
3715 In non-stop mode this attribute will be set to the specific thread which was
3716 involved in the emitted event. Otherwise, it will be set to @code{None}.
3719 The following is a listing of the event registries that are available and
3720 details of the events they emit:
3725 Emits @code{gdb.ContinueEvent}, which extends @code{gdb.ThreadEvent}.
3726 This event indicates that the inferior has been continued after a
3727 stop. For inherited attribute refer to @code{gdb.ThreadEvent} above.
3730 Emits @code{events.ExitedEvent}, which indicates that the inferior has
3731 exited. @code{events.ExitedEvent} has two attributes:
3733 @defvar ExitedEvent.exit_code
3734 An integer representing the exit code, if available, which the inferior
3735 has returned. (The exit code could be unavailable if, for example,
3736 @value{GDBN} detaches from the inferior.) If the exit code is unavailable,
3737 the attribute does not exist.
3740 @defvar ExitedEvent.inferior
3741 A reference to the inferior which triggered the @code{exited} event.
3745 Emits @code{gdb.StopEvent}, which extends @code{gdb.ThreadEvent}.
3747 Indicates that the inferior has stopped. All events emitted by this
3748 registry extend @code{gdb.StopEvent}. As a child of
3749 @code{gdb.ThreadEvent}, @code{gdb.StopEvent} will indicate the stopped
3750 thread when @value{GDBN} is running in non-stop mode. Refer to
3751 @code{gdb.ThreadEvent} above for more details.
3753 @code{gdb.StopEvent} has the following additional attributes:
3755 @defvar StopEvent.details
3756 A dictionary holding any details relevant to the stop. The exact keys
3757 and values depend on the type of stop, but are identical to the
3758 corresponding MI output (@pxref{GDB/MI Async Records}).
3760 A dictionary was used for this (rather than adding attributes directly
3761 to the event object) so that the MI keys could be used unchanged.
3764 Emits @code{gdb.SignalEvent}, which extends @code{gdb.StopEvent}.
3766 This event indicates that the inferior or one of its threads has
3767 received a signal. @code{gdb.SignalEvent} has the following
3770 @defvar SignalEvent.stop_signal
3771 A string representing the signal received by the inferior. A list of possible
3772 signal values can be obtained by running the command @code{info signals} in
3773 the @value{GDBN} command prompt.
3776 Also emits @code{gdb.BreakpointEvent}, which extends
3777 @code{gdb.StopEvent}.
3779 @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
3780 been hit, and has the following attributes:
3782 @defvar BreakpointEvent.breakpoints
3783 A sequence containing references to all the breakpoints (type
3784 @code{gdb.Breakpoint}) that were hit.
3785 @xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
3788 @defvar BreakpointEvent.breakpoint
3789 A reference to the first breakpoint that was hit. This attribute is
3790 maintained for backward compatibility and is now deprecated in favor
3791 of the @code{gdb.BreakpointEvent.breakpoints} attribute.
3794 @item events.new_objfile
3795 Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
3796 been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
3798 @defvar NewObjFileEvent.new_objfile
3799 A reference to the object file (@code{gdb.Objfile}) which has been loaded.
3800 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3803 @item events.free_objfile
3804 Emits @code{gdb.FreeObjFileEvent} which indicates that an object file
3805 is about to be removed from @value{GDBN}. One reason this can happen
3806 is when the inferior calls @code{dlclose}.
3807 @code{gdb.FreeObjFileEvent} has one attribute:
3809 @defvar FreeObjFileEvent.objfile
3810 A reference to the object file (@code{gdb.Objfile}) which will be unloaded.
3811 @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
3814 @item events.clear_objfiles
3815 Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object
3816 files for a program space has been reset.
3817 @code{gdb.ClearObjFilesEvent} has one attribute:
3819 @defvar ClearObjFilesEvent.progspace
3820 A reference to the program space (@code{gdb.Progspace}) whose objfile list has
3821 been cleared. @xref{Progspaces In Python}.
3824 @item events.inferior_call
3825 Emits events just before and after a function in the inferior is
3826 called by @value{GDBN}. Before an inferior call, this emits an event
3827 of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
3828 this emits an event of type @code{gdb.InferiorCallPostEvent}.
3831 @tindex gdb.InferiorCallPreEvent
3832 @item @code{gdb.InferiorCallPreEvent}
3833 Indicates that a function in the inferior is about to be called.
3835 @defvar InferiorCallPreEvent.ptid
3836 The thread in which the call will be run.
3839 @defvar InferiorCallPreEvent.address
3840 The location of the function to be called.
3843 @tindex gdb.InferiorCallPostEvent
3844 @item @code{gdb.InferiorCallPostEvent}
3845 Indicates that a function in the inferior has just been called.
3847 @defvar InferiorCallPostEvent.ptid
3848 The thread in which the call was run.
3851 @defvar InferiorCallPostEvent.address
3852 The location of the function that was called.
3856 @item events.memory_changed
3857 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
3858 inferior has been modified by the @value{GDBN} user, for instance via a
3859 command like @w{@code{set *addr = value}}. The event has the following
3862 @defvar MemoryChangedEvent.address
3863 The start address of the changed region.
3866 @defvar MemoryChangedEvent.length
3867 Length in bytes of the changed region.
3870 @item events.register_changed
3871 Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the
3872 inferior has been modified by the @value{GDBN} user.
3874 @defvar RegisterChangedEvent.frame
3875 A gdb.Frame object representing the frame in which the register was modified.
3877 @defvar RegisterChangedEvent.regnum
3878 Denotes which register was modified.
3881 @item events.breakpoint_created
3882 This is emitted when a new breakpoint has been created. The argument
3883 that is passed is the new @code{gdb.Breakpoint} object.
3885 @item events.breakpoint_modified
3886 This is emitted when a breakpoint has been modified in some way. The
3887 argument that is passed is the new @code{gdb.Breakpoint} object.
3889 @item events.breakpoint_deleted
3890 This is emitted when a breakpoint has been deleted. The argument that
3891 is passed is the @code{gdb.Breakpoint} object. When this event is
3892 emitted, the @code{gdb.Breakpoint} object will already be in its
3893 invalid state; that is, the @code{is_valid} method will return
3896 @item events.before_prompt
3897 This event carries no payload. It is emitted each time @value{GDBN}
3898 presents a prompt to the user.
3900 @item events.new_inferior
3901 This is emitted when a new inferior is created. Note that the
3902 inferior is not necessarily running; in fact, it may not even have an
3903 associated executable.
3905 The event is of type @code{gdb.NewInferiorEvent}. This has a single
3908 @defvar NewInferiorEvent.inferior
3909 The new inferior, a @code{gdb.Inferior} object.
3912 @item events.inferior_deleted
3913 This is emitted when an inferior has been deleted. Note that this is
3914 not the same as process exit; it is notified when the inferior itself
3915 is removed, say via @code{remove-inferiors}.
3917 The event is of type @code{gdb.InferiorDeletedEvent}. This has a single
3920 @defvar InferiorDeletedEvent.inferior
3921 The inferior that is being removed, a @code{gdb.Inferior} object.
3924 @item events.new_thread
3925 This is emitted when @value{GDBN} notices a new thread. The event is of
3926 type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}.
3927 This has a single attribute:
3929 @defvar NewThreadEvent.inferior_thread
3933 @item events.thread_exited
3934 This is emitted when @value{GDBN} notices a thread has exited. The event
3935 is of type @code{gdb.ThreadExitedEvent} which extends @code{gdb.ThreadEvent}.
3936 This has a single attribute:
3938 @defvar ThreadExitedEvent.inferior_thread
3942 @item events.gdb_exiting
3943 This is emitted when @value{GDBN} exits. This event is not emitted if
3944 @value{GDBN} exits as a result of an internal error, or after an
3945 unexpected signal. The event is of type @code{gdb.GdbExitingEvent},
3946 which has a single attribute:
3948 @defvar GdbExitingEvent.exit_code
3949 An integer, the value of the exit code @value{GDBN} will return.
3952 @item events.connection_removed
3953 This is emitted when @value{GDBN} removes a connection
3954 (@pxref{Connections In Python}). The event is of type
3955 @code{gdb.ConnectionEvent}. This has a single read-only attribute:
3957 @defvar ConnectionEvent.connection
3958 The @code{gdb.TargetConnection} that is being removed.
3961 @item events.executable_changed
3962 Emits @code{gdb.ExecutableChangedEvent} which indicates that the
3963 @code{gdb.Progspace.executable_filename} has changed.
3965 This event is emitted when either the value of
3966 @code{gdb.Progspace.executable_filename } has changed to name a
3967 different file, or the executable file named by
3968 @code{gdb.Progspace.executable_filename} has changed on disk, and
3969 @value{GDBN} has therefore reloaded it.
3971 @defvar ExecutableChangedEvent.progspace
3972 The @code{gdb.Progspace} in which the current executable has changed.
3973 The file name of the updated executable will be visible in
3974 @code{gdb.Progspace.executable_filename} (@pxref{Progspaces In Python}).
3976 @defvar ExecutableChangedEvent.reload
3977 This attribute will be @code{True} if the value of
3978 @code{gdb.Progspace.executable_filename} didn't change, but the file
3979 it names changed on disk instead, and @value{GDBN} reloaded it.
3981 When this attribute is @code{False}, the value in
3982 @code{gdb.Progspace.executable_filename} was changed to name a
3986 Remember that @value{GDBN} tracks the executable file and the symbol
3987 file separately, these are visible as
3988 @code{gdb.Progspace.executable_filename} and
3989 @code{gdb.Progspace.filename} respectively. When using the @kbd{file}
3990 command, @value{GDBN} updates both of these fields, but the executable
3991 file is updated first, so when this event is emitted, the executable
3992 filename will have changed, but the symbol filename might still hold
3995 @item events.new_progspace
3996 This is emitted when @value{GDBN} adds a new program space
3997 (@pxref{Progspaces In Python,,Program Spaces In Python}). The event
3998 is of type @code{gdb.NewProgspaceEvent}, and has a single read-only
4001 @defvar NewProgspaceEvent.progspace
4002 The @code{gdb.Progspace} that was added to @value{GDBN}.
4005 No @code{NewProgspaceEvent} is emitted for the very first program
4006 space, which is assigned to the first inferior. This first program
4007 space is created within @value{GDBN} before any Python scripts are
4010 @item events.free_progspace
4011 This is emitted when @value{GDBN} removes a program space
4012 (@pxref{Progspaces In Python,,Program Spaces In Python}), for example
4013 as a result of the @kbd{remove-inferiors} command
4014 (@pxref{remove_inferiors_cli,,@kbd{remove-inferiors}}). The event is
4015 of type @code{gdb.FreeProgspaceEvent}, and has a single read-only
4018 @defvar FreeProgspaceEvent.progspace
4019 The @code{gdb.Progspace} that is about to be removed from
4025 @node Threads In Python
4026 @subsubsection Threads In Python
4027 @cindex threads in python
4029 @findex gdb.InferiorThread
4030 Python scripts can access information about, and manipulate inferior threads
4031 controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
4033 The following thread-related functions are available in the @code{gdb}
4036 @defun gdb.selected_thread ()
4037 This function returns the thread object for the selected thread. If there
4038 is no selected thread, this will return @code{None}.
4041 To get the list of threads for an inferior, use the @code{Inferior.threads()}
4042 method. @xref{Inferiors In Python}.
4044 A @code{gdb.InferiorThread} object has the following attributes:
4046 @defvar InferiorThread.name
4047 The name of the thread. If the user specified a name using
4048 @code{thread name}, then this returns that name. Otherwise, if an
4049 OS-supplied name is available, then it is returned. Otherwise, this
4050 returns @code{None}.
4052 This attribute can be assigned to. The new value must be a string
4053 object, which sets the new name, or @code{None}, which removes any
4054 user-specified thread name.
4057 @defvar InferiorThread.num
4058 The per-inferior number of the thread, as assigned by GDB.
4061 @defvar InferiorThread.global_num
4062 The global ID of the thread, as assigned by GDB. You can use this to
4063 make Python breakpoints thread-specific, for example
4064 (@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}).
4067 @anchor{inferior_thread_ptid}
4068 @defvar InferiorThread.ptid
4069 ID of the thread, as assigned by the operating system. This attribute is a
4070 tuple containing three integers. The first is the Process ID (PID); the second
4071 is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
4072 Either the LWPID or TID may be 0, which indicates that the operating system
4073 does not use that identifier.
4076 @defvar InferiorThread.inferior
4077 The inferior this thread belongs to. This attribute is represented as
4078 a @code{gdb.Inferior} object. This attribute is not writable.
4081 @defvar InferiorThread.details
4082 A string containing target specific thread state information. The
4083 format of this string varies by target. If there is no additional
4084 state information for this thread, then this attribute contains
4087 For example, on a @sc{gnu}/Linux system, a thread that is in the
4088 process of exiting will return the string @samp{Exiting}. For remote
4089 targets the @code{details} string will be obtained with the
4090 @samp{qThreadExtraInfo} remote packet, if the target supports it
4091 (@pxref{qThreadExtraInfo,,@samp{qThreadExtraInfo}}).
4093 @value{GDBN} displays the @code{details} string as part of the
4094 @samp{Target Id} column, in the @code{info threads} output
4095 (@pxref{info_threads,,@samp{info threads}}).
4098 A @code{gdb.InferiorThread} object has the following methods:
4100 @defun InferiorThread.is_valid ()
4101 Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
4102 @code{False} if not. A @code{gdb.InferiorThread} object will become
4103 invalid if the thread exits, or the inferior that the thread belongs
4104 is deleted. All other @code{gdb.InferiorThread} methods will throw an
4105 exception if it is invalid at the time the method is called.
4108 @defun InferiorThread.switch ()
4109 This changes @value{GDBN}'s currently selected thread to the one represented
4113 @defun InferiorThread.is_stopped ()
4114 Return a Boolean indicating whether the thread is stopped.
4117 @defun InferiorThread.is_running ()
4118 Return a Boolean indicating whether the thread is running.
4121 @defun InferiorThread.is_exited ()
4122 Return a Boolean indicating whether the thread is exited.
4125 @defun InferiorThread.handle ()
4126 Return the thread object's handle, represented as a Python @code{bytes}
4127 object. A @code{gdb.Value} representation of the handle may be
4128 constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is
4129 the Python @code{bytes} representation of the handle and @var{type} is
4130 a @code{gdb.Type} for the handle type.
4133 @node Recordings In Python
4134 @subsubsection Recordings In Python
4135 @cindex recordings in python
4137 The following recordings-related functions
4138 (@pxref{Process Record and Replay}) are available in the @code{gdb}
4141 @defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
4142 Start a recording using the given @var{method} and @var{format}. If
4143 no @var{format} is given, the default format for the recording method
4144 is used. If no @var{method} is given, the default method will be used.
4145 Returns a @code{gdb.Record} object on success. Throw an exception on
4148 The following strings can be passed as @var{method}:
4154 @code{"btrace"}: Possible values for @var{format}: @code{"pt"},
4155 @code{"bts"} or leave out for default format.
4159 @defun gdb.current_recording ()
4160 Access a currently running recording. Return a @code{gdb.Record}
4161 object on success. Return @code{None} if no recording is currently
4165 @defun gdb.stop_recording ()
4166 Stop the current recording. Throw an exception if no recording is
4167 currently active. All record objects become invalid after this call.
4170 A @code{gdb.Record} object has the following attributes:
4172 @defvar Record.method
4173 A string with the current recording method, e.g.@: @code{full} or
4177 @defvar Record.format
4178 A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
4182 @defvar Record.begin
4183 A method specific instruction object representing the first instruction
4188 A method specific instruction object representing the current
4189 instruction, that is not actually part of the recording.
4192 @defvar Record.replay_position
4193 The instruction representing the current replay position. If there is
4194 no replay active, this will be @code{None}.
4197 @defvar Record.instruction_history
4198 A list with all recorded instructions.
4201 @defvar Record.function_call_history
4202 A list with all recorded function call segments.
4205 A @code{gdb.Record} object has the following methods:
4207 @defun Record.goto (instruction)
4208 Move the replay position to the given @var{instruction}.
4211 The common @code{gdb.Instruction} class that recording method specific
4212 instruction objects inherit from, has the following attributes:
4214 @defvar Instruction.pc
4215 An integer representing this instruction's address.
4218 @defvar Instruction.data
4219 A @code{memoryview} object holding the raw instruction data.
4222 @defvar Instruction.decoded
4223 A human readable string with the disassembled instruction.
4226 @defvar Instruction.size
4227 The size of the instruction in bytes.
4230 Additionally @code{gdb.RecordInstruction} has the following attributes:
4232 @defvar RecordInstruction.number
4233 An integer identifying this instruction. @code{number} corresponds to
4234 the numbers seen in @code{record instruction-history}
4235 (@pxref{Process Record and Replay}).
4238 @defvar RecordInstruction.sal
4239 A @code{gdb.Symtab_and_line} object representing the associated symtab
4240 and line of this instruction. May be @code{None} if no debug information is
4244 @defvar RecordInstruction.is_speculative
4245 A boolean indicating whether the instruction was executed speculatively.
4248 If an error occurred during recording or decoding a recording, this error is
4249 represented by a @code{gdb.RecordGap} object in the instruction list. It has
4250 the following attributes:
4252 @defvar RecordGap.number
4253 An integer identifying this gap. @code{number} corresponds to the numbers seen
4254 in @code{record instruction-history} (@pxref{Process Record and Replay}).
4257 @defvar RecordGap.error_code
4258 A numerical representation of the reason for the gap. The value is specific to
4259 the current recording method.
4262 @defvar RecordGap.error_string
4263 A human readable string with the reason for the gap.
4266 A @code{gdb.RecordFunctionSegment} object has the following attributes:
4268 @defvar RecordFunctionSegment.number
4269 An integer identifying this function segment. @code{number} corresponds to
4270 the numbers seen in @code{record function-call-history}
4271 (@pxref{Process Record and Replay}).
4274 @defvar RecordFunctionSegment.symbol
4275 A @code{gdb.Symbol} object representing the associated symbol. May be
4276 @code{None} if no debug information is available.
4279 @defvar RecordFunctionSegment.level
4280 An integer representing the function call's stack level. May be
4281 @code{None} if the function call is a gap.
4284 @defvar RecordFunctionSegment.instructions
4285 A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
4286 associated with this function call.
4289 @defvar RecordFunctionSegment.up
4290 A @code{gdb.RecordFunctionSegment} object representing the caller's
4291 function segment. If the call has not been recorded, this will be the
4292 function segment to which control returns. If neither the call nor the
4293 return have been recorded, this will be @code{None}.
4296 @defvar RecordFunctionSegment.prev
4297 A @code{gdb.RecordFunctionSegment} object representing the previous
4298 segment of this function call. May be @code{None}.
4301 @defvar RecordFunctionSegment.next
4302 A @code{gdb.RecordFunctionSegment} object representing the next segment of
4303 this function call. May be @code{None}.
4306 The following example demonstrates the usage of these objects and
4307 functions to create a function that will rewind a record to the last
4308 time a function in a different file was executed. This would typically
4309 be used to track the execution of user provided callback functions in a
4310 library which typically are not visible in a back trace.
4314 rec = gdb.current_recording ()
4318 insn = rec.instruction_history
4323 position = insn.index (rec.replay_position)
4327 filename = insn[position].sal.symtab.fullname ()
4331 for i in reversed (insn[:position]):
4333 current = i.sal.symtab.fullname ()
4337 if filename == current:
4344 Another possible application is to write a function that counts the
4345 number of code executions in a given line range. This line range can
4346 contain parts of functions or span across several functions and is not
4347 limited to be contiguous.
4350 def countrange (filename, linerange):
4353 def filter_only (file_name):
4354 for call in gdb.current_recording ().function_call_history:
4356 if file_name in call.symbol.symtab.fullname ():
4361 for c in filter_only (filename):
4362 for i in c.instructions:
4364 if i.sal.line in linerange:
4373 @node CLI Commands In Python
4374 @subsubsection CLI Commands In Python
4376 @cindex CLI commands in python
4377 @cindex commands in python, CLI
4378 @cindex python commands, CLI
4379 You can implement new @value{GDBN} CLI commands in Python. A CLI
4380 command is implemented using an instance of the @code{gdb.Command}
4381 class, most commonly using a subclass.
4383 @defun Command.__init__ (name, command_class @r{[}, completer_class @r{[}, prefix@r{]]})
4384 The object initializer for @code{Command} registers the new command
4385 with @value{GDBN}. This initializer is normally invoked from the
4386 subclass' own @code{__init__} method.
4388 @var{name} is the name of the command. If @var{name} consists of
4389 multiple words, then the initial words are looked for as prefix
4390 commands. In this case, if one of the prefix commands does not exist,
4391 an exception is raised.
4393 There is no support for multi-line commands.
4395 @var{command_class} should be one of the @samp{COMMAND_} constants
4396 defined below. This argument tells @value{GDBN} how to categorize the
4397 new command in the help system.
4399 @var{completer_class} is an optional argument. If given, it should be
4400 one of the @samp{COMPLETE_} constants defined below. This argument
4401 tells @value{GDBN} how to perform completion for this command. If not
4402 given, @value{GDBN} will attempt to complete using the object's
4403 @code{complete} method (see below); if no such method is found, an
4404 error will occur when completion is attempted.
4406 @var{prefix} is an optional argument. If @code{True}, then the new
4407 command is a prefix command; sub-commands of this command may be
4410 The help text for the new command is taken from the Python
4411 documentation string for the command's class, if there is one. If no
4412 documentation string is provided, the default value ``This command is
4413 not documented.'' is used.
4416 @cindex don't repeat Python command
4417 @defun Command.dont_repeat ()
4418 By default, a @value{GDBN} command is repeated when the user enters a
4419 blank line at the command prompt. A command can suppress this
4420 behavior by invoking the @code{dont_repeat} method at some point in
4421 its @code{invoke} method (normally this is done early in case of
4422 exception). This is similar to the user command @code{dont-repeat},
4423 see @ref{Define, dont-repeat}.
4426 @defun Command.invoke (argument, from_tty)
4427 This method is called by @value{GDBN} when this command is invoked.
4429 @var{argument} is a string. It is the argument to the command, after
4430 leading and trailing whitespace has been stripped.
4432 @var{from_tty} is a boolean argument. When true, this means that the
4433 command was entered by the user at the terminal; when false it means
4434 that the command came from elsewhere.
4436 If this method throws an exception, it is turned into a @value{GDBN}
4437 @code{error} call. Otherwise, the return value is ignored.
4439 @findex gdb.string_to_argv
4440 To break @var{argument} up into an argv-like string use
4441 @code{gdb.string_to_argv}. This function behaves identically to
4442 @value{GDBN}'s internal argument lexer @code{buildargv}.
4443 It is recommended to use this for consistency.
4444 Arguments are separated by spaces and may be quoted.
4448 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
4449 ['1', '2 "3', '4 "5', "6 '7"]
4454 @cindex completion of Python commands
4455 @defun Command.complete (text, word)
4456 This method is called by @value{GDBN} when the user attempts
4457 completion on this command. All forms of completion are handled by
4458 this method, that is, the @key{TAB} and @key{M-?} key bindings
4459 (@pxref{Completion}), and the @code{complete} command (@pxref{Help,
4462 The arguments @var{text} and @var{word} are both strings; @var{text}
4463 holds the complete command line up to the cursor's location, while
4464 @var{word} holds the last word of the command line; this is computed
4465 using a word-breaking heuristic.
4467 The @code{complete} method can return several values:
4470 If the return value is a sequence, the contents of the sequence are
4471 used as the completions. It is up to @code{complete} to ensure that the
4472 contents actually do complete the word. A zero-length sequence is
4473 allowed, it means that there were no completions available. Only
4474 string elements of the sequence are used; other elements in the
4475 sequence are ignored.
4478 If the return value is one of the @samp{COMPLETE_} constants defined
4479 below, then the corresponding @value{GDBN}-internal completion
4480 function is invoked, and its result is used.
4483 All other results are treated as though there were no available
4488 When a new command is registered, it must be declared as a member of
4489 some general class of commands. This is used to classify top-level
4490 commands in the on-line help system; note that prefix commands are not
4491 listed under their own category but rather that of their top-level
4492 command. The available classifications are represented by constants
4493 defined in the @code{gdb} module:
4496 @findex COMMAND_NONE
4497 @findex gdb.COMMAND_NONE
4498 @item gdb.COMMAND_NONE
4499 The command does not belong to any particular class. A command in
4500 this category will not be displayed in any of the help categories.
4502 @findex COMMAND_RUNNING
4503 @findex gdb.COMMAND_RUNNING
4504 @item gdb.COMMAND_RUNNING
4505 The command is related to running the inferior. For example,
4506 @code{start}, @code{step}, and @code{continue} are in this category.
4507 Type @kbd{help running} at the @value{GDBN} prompt to see a list of
4508 commands in this category.
4510 @findex COMMAND_DATA
4511 @findex gdb.COMMAND_DATA
4512 @item gdb.COMMAND_DATA
4513 The command is related to data or variables. For example,
4514 @code{call}, @code{find}, and @code{print} are in this category. Type
4515 @kbd{help data} at the @value{GDBN} prompt to see a list of commands
4518 @findex COMMAND_STACK
4519 @findex gdb.COMMAND_STACK
4520 @item gdb.COMMAND_STACK
4521 The command has to do with manipulation of the stack. For example,
4522 @code{backtrace}, @code{frame}, and @code{return} are in this
4523 category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
4524 list of commands in this category.
4526 @findex COMMAND_FILES
4527 @findex gdb.COMMAND_FILES
4528 @item gdb.COMMAND_FILES
4529 This class is used for file-related commands. For example,
4530 @code{file}, @code{list} and @code{section} are in this category.
4531 Type @kbd{help files} at the @value{GDBN} prompt to see a list of
4532 commands in this category.
4534 @findex COMMAND_SUPPORT
4535 @findex gdb.COMMAND_SUPPORT
4536 @item gdb.COMMAND_SUPPORT
4537 This should be used for ``support facilities'', generally meaning
4538 things that are useful to the user when interacting with @value{GDBN},
4539 but not related to the state of the inferior. For example,
4540 @code{help}, @code{make}, and @code{shell} are in this category. Type
4541 @kbd{help support} at the @value{GDBN} prompt to see a list of
4542 commands in this category.
4544 @findex COMMAND_STATUS
4545 @findex gdb.COMMAND_STATUS
4546 @item gdb.COMMAND_STATUS
4547 The command is an @samp{info}-related command, that is, related to the
4548 state of @value{GDBN} itself. For example, @code{info}, @code{macro},
4549 and @code{show} are in this category. Type @kbd{help status} at the
4550 @value{GDBN} prompt to see a list of commands in this category.
4552 @findex COMMAND_BREAKPOINTS
4553 @findex gdb.COMMAND_BREAKPOINTS
4554 @item gdb.COMMAND_BREAKPOINTS
4555 The command has to do with breakpoints. For example, @code{break},
4556 @code{clear}, and @code{delete} are in this category. Type @kbd{help
4557 breakpoints} at the @value{GDBN} prompt to see a list of commands in
4560 @findex COMMAND_TRACEPOINTS
4561 @findex gdb.COMMAND_TRACEPOINTS
4562 @item gdb.COMMAND_TRACEPOINTS
4563 The command has to do with tracepoints. For example, @code{trace},
4564 @code{actions}, and @code{tfind} are in this category. Type
4565 @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
4566 commands in this category.
4569 @findex gdb.COMMAND_TUI
4570 @item gdb.COMMAND_TUI
4571 The command has to do with the text user interface (@pxref{TUI}).
4572 Type @kbd{help tui} at the @value{GDBN} prompt to see a list of
4573 commands in this category.
4575 @findex COMMAND_USER
4576 @findex gdb.COMMAND_USER
4577 @item gdb.COMMAND_USER
4578 The command is a general purpose command for the user, and typically
4579 does not fit in one of the other categories.
4580 Type @kbd{help user-defined} at the @value{GDBN} prompt to see
4581 a list of commands in this category, as well as the list of gdb macros
4582 (@pxref{Sequences}).
4584 @findex COMMAND_OBSCURE
4585 @findex gdb.COMMAND_OBSCURE
4586 @item gdb.COMMAND_OBSCURE
4587 The command is only used in unusual circumstances, or is not of
4588 general interest to users. For example, @code{checkpoint},
4589 @code{fork}, and @code{stop} are in this category. Type @kbd{help
4590 obscure} at the @value{GDBN} prompt to see a list of commands in this
4593 @findex COMMAND_MAINTENANCE
4594 @findex gdb.COMMAND_MAINTENANCE
4595 @item gdb.COMMAND_MAINTENANCE
4596 The command is only useful to @value{GDBN} maintainers. The
4597 @code{maintenance} and @code{flushregs} commands are in this category.
4598 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
4599 commands in this category.
4602 A new command can use a predefined completion function, either by
4603 specifying it via an argument at initialization, or by returning it
4604 from the @code{complete} method. These predefined completion
4605 constants are all defined in the @code{gdb} module:
4608 @vindex COMPLETE_NONE
4609 @item gdb.COMPLETE_NONE
4610 This constant means that no completion should be done.
4612 @vindex COMPLETE_FILENAME
4613 @item gdb.COMPLETE_FILENAME
4614 This constant means that filename completion should be performed.
4616 @vindex COMPLETE_LOCATION
4617 @item gdb.COMPLETE_LOCATION
4618 This constant means that location completion should be done.
4619 @xref{Location Specifications}.
4621 @vindex COMPLETE_COMMAND
4622 @item gdb.COMPLETE_COMMAND
4623 This constant means that completion should examine @value{GDBN}
4626 @vindex COMPLETE_SYMBOL
4627 @item gdb.COMPLETE_SYMBOL
4628 This constant means that completion should be done using symbol names
4631 @vindex COMPLETE_EXPRESSION
4632 @item gdb.COMPLETE_EXPRESSION
4633 This constant means that completion should be done on expressions.
4634 Often this means completing on symbol names, but some language
4635 parsers also have support for completing on field names.
4638 The following code snippet shows how a trivial CLI command can be
4639 implemented in Python:
4642 class HelloWorld (gdb.Command):
4643 """Greet the whole world."""
4645 def __init__ (self):
4646 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
4648 def invoke (self, arg, from_tty):
4649 print ("Hello, World!")
4654 The last line instantiates the class, and is necessary to trigger the
4655 registration of the command with @value{GDBN}. Depending on how the
4656 Python code is read into @value{GDBN}, you may need to import the
4657 @code{gdb} module explicitly.
4659 @node GDB/MI Commands In Python
4660 @subsubsection @sc{gdb/mi} Commands In Python
4662 @cindex MI commands in python
4663 @cindex commands in python, GDB/MI
4664 @cindex python commands, GDB/MI
4665 It is possible to add @sc{gdb/mi} (@pxref{GDB/MI}) commands
4666 implemented in Python. A @sc{gdb/mi} command is implemented using an
4667 instance of the @code{gdb.MICommand} class, most commonly using a
4670 @defun MICommand.__init__ (name)
4671 The object initializer for @code{MICommand} registers the new command
4672 with @value{GDBN}. This initializer is normally invoked from the
4673 subclass' own @code{__init__} method.
4675 @var{name} is the name of the command. It must be a valid name of a
4676 @sc{gdb/mi} command, and in particular must start with a hyphen
4677 (@code{-}). Reusing the name of a built-in @sc{gdb/mi} is not
4678 allowed, and a @code{RuntimeError} will be raised. Using the name
4679 of an @sc{gdb/mi} command previously defined in Python is allowed, the
4680 previous command will be replaced with the new command.
4683 @defun MICommand.invoke (arguments)
4684 This method is called by @value{GDBN} when the new MI command is
4687 @var{arguments} is a list of strings. Note, that @code{--thread}
4688 and @code{--frame} arguments are handled by @value{GDBN} itself therefore
4689 they do not show up in @code{arguments}.
4691 If this method raises an exception, then it is turned into a
4692 @sc{gdb/mi} @code{^error} response. Only @code{gdb.GdbError}
4693 exceptions (or its sub-classes) should be used for reporting errors to
4694 users, any other exception type is treated as a failure of the
4695 @code{invoke} method, and the exception will be printed to the error
4696 stream according to the @kbd{set python print-stack} setting
4697 (@pxref{set_python_print_stack,,@kbd{set python print-stack}}).
4699 If this method returns @code{None}, then the @sc{gdb/mi} command will
4700 return a @code{^done} response with no additional values.
4702 Otherwise, the return value must be a dictionary, which is converted
4703 to a @sc{gdb/mi} @var{result-record} (@pxref{GDB/MI Output Syntax}).
4704 The keys of this dictionary must be strings, and are used as
4705 @var{variable} names in the @var{result-record}, these strings must
4706 comply with the naming rules detailed below. The values of this
4707 dictionary are recursively handled as follows:
4711 If the value is Python sequence or iterator, it is converted to
4712 @sc{gdb/mi} @var{list} with elements converted recursively.
4715 If the value is Python dictionary, it is converted to
4716 @sc{gdb/mi} @var{tuple}. Keys in that dictionary must be strings,
4717 which comply with the @var{variable} naming rules detailed below.
4718 Values are converted recursively.
4721 Otherwise, value is first converted to a Python string using
4722 @code{str ()} and then converted to @sc{gdb/mi} @var{const}.
4725 The strings used for @var{variable} names in the @sc{gdb/mi} output
4726 must follow the following rules; the string must be at least one
4727 character long, the first character must be in the set
4728 @code{[a-zA-Z]}, while every subsequent character must be in the set
4729 @code{[-_a-zA-Z0-9]}.
4732 An instance of @code{MICommand} has the following attributes:
4734 @defvar MICommand.name
4735 A string, the name of this @sc{gdb/mi} command, as was passed to the
4736 @code{__init__} method. This attribute is read-only.
4739 @defvar MICommand.installed
4740 A boolean value indicating if this command is installed ready for a
4741 user to call from the command line. Commands are automatically
4742 installed when they are instantiated, after which this attribute will
4745 If later, a new command is created with the same name, then the
4746 original command will become uninstalled, and this attribute will be
4749 This attribute is read-write, setting this attribute to @code{False}
4750 will uninstall the command, removing it from the set of available
4751 commands. Setting this attribute to @code{True} will install the
4752 command for use. If there is already a Python command with this name
4753 installed, the currently installed command will be uninstalled, and
4754 this command installed in its stead.
4757 The following code snippet shows how some trivial MI commands can be
4758 implemented in Python:
4761 class MIEcho(gdb.MICommand):
4762 """Echo arguments passed to the command."""
4764 def __init__(self, name, mode):
4766 super(MIEcho, self).__init__(name)
4768 def invoke(self, argv):
4769 if self._mode == 'dict':
4770 return @{ 'dict': @{ 'argv' : argv @} @}
4771 elif self._mode == 'list':
4772 return @{ 'list': argv @}
4774 return @{ 'string': ", ".join(argv) @}
4777 MIEcho("-echo-dict", "dict")
4778 MIEcho("-echo-list", "list")
4779 MIEcho("-echo-string", "string")
4782 The last three lines instantiate the class three times, creating three
4783 new @sc{gdb/mi} commands @code{-echo-dict}, @code{-echo-list}, and
4784 @code{-echo-string}. Each time a subclass of @code{gdb.MICommand} is
4785 instantiated, the new command is automatically registered with
4788 Depending on how the Python code is read into @value{GDBN}, you may
4789 need to import the @code{gdb} module explicitly.
4791 The following example shows a @value{GDBN} session in which the above
4792 commands have been added:
4796 -echo-dict abc def ghi
4797 ^done,dict=@{argv=["abc","def","ghi"]@}
4799 -echo-list abc def ghi
4800 ^done,list=["abc","def","ghi"]
4802 -echo-string abc def ghi
4803 ^done,string="abc, def, ghi"
4807 Conversely, it is possible to execute @sc{gdb/mi} commands from
4808 Python, with the results being a Python object and not a
4809 specially-formatted string. This is done with the
4810 @code{gdb.execute_mi} function.
4812 @defun gdb.execute_mi (command @r{[}, arg @r{]}@dots{})
4813 Invoke a @sc{gdb/mi} command. @var{command} is the name of the
4814 command, a string. The arguments, @var{arg}, are passed to the
4815 command. Each argument must also be a string.
4817 This function returns a Python dictionary whose contents reflect the
4818 corresponding @sc{GDB/MI} command's output. Refer to the
4819 documentation for these commands for details. Lists are represented
4820 as Python lists, and tuples are represented as Python dictionaries.
4822 If the command fails, it will raise a Python exception.
4825 Here is how this works using the commands from the example above:
4828 (@value{GDBP}) python print(gdb.execute_mi("-echo-dict", "abc", "def", "ghi"))
4829 @{'dict': @{'argv': ['abc', 'def', 'ghi']@}@}
4830 (@value{GDBP}) python print(gdb.execute_mi("-echo-list", "abc", "def", "ghi"))
4831 @{'list': ['abc', 'def', 'ghi']@}
4832 (@value{GDBP}) python print(gdb.execute_mi("-echo-string", "abc", "def", "ghi"))
4833 @{'string': 'abc, def, ghi'@}
4836 @node GDB/MI Notifications In Python
4837 @subsubsection @sc{gdb/mi} Notifications In Python
4839 @cindex MI notifications in python
4840 @cindex notifications in python, GDB/MI
4841 @cindex python notifications, GDB/MI
4843 It is possible to emit @sc{gdb/mi} notifications from
4844 Python. Use the @code{gdb.notify_mi} function to do that.
4846 @defun gdb.notify_mi (name @r{[}, data@r{]})
4847 Emit a @sc{gdb/mi} asynchronous notification. @var{name} is the name of the
4848 notification, consisting of alphanumeric characters and a hyphen (@code{-}).
4849 @var{data} is any additional data to be emitted with the notification, passed
4850 as a Python dictionary. This argument is optional. The dictionary is converted
4851 to a @sc{gdb/mi} @var{result} records (@pxref{GDB/MI Output Syntax}) the same way
4852 as result of Python MI command (@pxref{GDB/MI Commands In Python}).
4854 If @var{data} is @code{None} then no additional values are emitted.
4857 While using existing notification names (@pxref{GDB/MI Async Records}) with
4858 @code{gdb.notify_mi} is allowed, users are encouraged to prefix user-defined
4859 notification with a hyphen (@code{-}) to avoid possible conflict.
4860 @value{GDBN} will never introduce notification starting with hyphen.
4862 Here is how to emit @code{=-connection-removed} whenever a connection to remote
4863 GDB server is closed (@pxref{Connections In Python}):
4866 def notify_connection_removed(event):
4867 data = @{"id": event.connection.num, "type": event.connection.type@}
4868 gdb.notify_mi("-connection-removed", data)
4871 gdb.events.connection_removed.connect(notify_connection_removed)
4874 Then, each time a connection is closed, there will be a notification on MI channel:
4877 =-connection-removed,id="1",type="remote"
4880 @node Parameters In Python
4881 @subsubsection Parameters In Python
4883 @cindex parameters in python
4884 @cindex python parameters
4885 @tindex gdb.Parameter
4887 You can implement new @value{GDBN} parameters using Python. A new
4888 parameter is implemented as an instance of the @code{gdb.Parameter}
4891 Parameters are exposed to the user via the @code{set} and
4892 @code{show} commands. @xref{Help}.
4894 There are many parameters that already exist and can be set in
4895 @value{GDBN}. Two examples are: @code{set follow fork} and
4896 @code{set charset}. Setting these parameters influences certain
4897 behavior in @value{GDBN}. Similarly, you can define parameters that
4898 can be used to influence behavior in custom Python scripts and commands.
4900 @defun Parameter.__init__ (name, command_class, parameter_class @r{[}, enum_sequence@r{]})
4901 The object initializer for @code{Parameter} registers the new
4902 parameter with @value{GDBN}. This initializer is normally invoked
4903 from the subclass' own @code{__init__} method.
4905 @var{name} is the name of the new parameter. If @var{name} consists
4906 of multiple words, then the initial words are looked for as prefix
4907 parameters. An example of this can be illustrated with the
4908 @code{set print} set of parameters. If @var{name} is
4909 @code{print foo}, then @code{print} will be searched as the prefix
4910 parameter. In this case the parameter can subsequently be accessed in
4911 @value{GDBN} as @code{set print foo}.
4913 If @var{name} consists of multiple words, and no prefix parameter group
4914 can be found, an exception is raised.
4916 @var{command_class} should be one of the @samp{COMMAND_} constants
4917 (@pxref{CLI Commands In Python}). This argument tells @value{GDBN} how to
4918 categorize the new parameter in the help system.
4920 @var{parameter_class} should be one of the @samp{PARAM_} constants
4921 defined below. This argument tells @value{GDBN} the type of the new
4922 parameter; this information is used for input validation and
4925 If @var{parameter_class} is @code{PARAM_ENUM}, then
4926 @var{enum_sequence} must be a sequence of strings. These strings
4927 represent the possible values for the parameter.
4929 If @var{parameter_class} is not @code{PARAM_ENUM}, then the presence
4930 of a fourth argument will cause an exception to be thrown.
4932 The help text for the new parameter includes the Python documentation
4933 string from the parameter's class, if there is one. If there is no
4934 documentation string, a default value is used. The documentation
4935 string is included in the output of the parameters @code{help set} and
4936 @code{help show} commands, and should be written taking this into
4940 @defvar Parameter.set_doc
4941 If this attribute exists, and is a string, then its value is used as
4942 the first part of the help text for this parameter's @code{set}
4943 command. The second part of the help text is taken from the
4944 documentation string for the parameter's class, if there is one.
4946 The value of @code{set_doc} should give a brief summary specific to
4947 the set action, this text is only displayed when the user runs the
4948 @code{help set} command for this parameter. The class documentation
4949 should be used to give a fuller description of what the parameter
4950 does, this text is displayed for both the @code{help set} and
4951 @code{help show} commands.
4953 The @code{set_doc} value is examined when @code{Parameter.__init__} is
4954 invoked; subsequent changes have no effect.
4957 @defvar Parameter.show_doc
4958 If this attribute exists, and is a string, then its value is used as
4959 the first part of the help text for this parameter's @code{show}
4960 command. The second part of the help text is taken from the
4961 documentation string for the parameter's class, if there is one.
4963 The value of @code{show_doc} should give a brief summary specific to
4964 the show action, this text is only displayed when the user runs the
4965 @code{help show} command for this parameter. The class documentation
4966 should be used to give a fuller description of what the parameter
4967 does, this text is displayed for both the @code{help set} and
4968 @code{help show} commands.
4970 The @code{show_doc} value is examined when @code{Parameter.__init__}
4971 is invoked; subsequent changes have no effect.
4974 @defvar Parameter.value
4975 The @code{value} attribute holds the underlying value of the
4976 parameter. It can be read and assigned to just as any other
4977 attribute. @value{GDBN} does validation when assignments are made.
4980 There are two methods that may be implemented in any @code{Parameter}
4983 @defun Parameter.get_set_string (self)
4984 If this method exists, @value{GDBN} will call it when a
4985 @var{parameter}'s value has been changed via the @code{set} API (for
4986 example, @kbd{set foo off}). The @code{value} attribute has already
4987 been populated with the new value and may be used in output. This
4988 method must return a string. If the returned string is not empty,
4989 @value{GDBN} will present it to the user.
4991 If this method raises the @code{gdb.GdbError} exception
4992 (@pxref{Exception Handling}), then @value{GDBN} will print the
4993 exception's string and the @code{set} command will fail. Note,
4994 however, that the @code{value} attribute will not be reset in this
4995 case. So, if your parameter must validate values, it should store the
4996 old value internally and reset the exposed value, like so:
4999 class ExampleParam (gdb.Parameter):
5000 def __init__ (self, name):
5001 super (ExampleParam, self).__init__ (name,
5005 self.saved_value = True
5008 def get_set_string (self):
5009 if not self.validate():
5010 self.value = self.saved_value
5011 raise gdb.GdbError('Failed to validate')
5012 self.saved_value = self.value
5017 @defun Parameter.get_show_string (self, svalue)
5018 @value{GDBN} will call this method when a @var{parameter}'s
5019 @code{show} API has been invoked (for example, @kbd{show foo}). The
5020 argument @code{svalue} receives the string representation of the
5021 current value. This method must return a string.
5024 When a new parameter is defined, its type must be specified. The
5025 available types are represented by constants defined in the @code{gdb}
5029 @findex PARAM_BOOLEAN
5030 @findex gdb.PARAM_BOOLEAN
5031 @item gdb.PARAM_BOOLEAN
5032 The value is a plain boolean. The Python boolean values, @code{True}
5033 and @code{False} are the only valid values.
5035 @findex PARAM_AUTO_BOOLEAN
5036 @findex gdb.PARAM_AUTO_BOOLEAN
5037 @item gdb.PARAM_AUTO_BOOLEAN
5038 The value has three possible states: true, false, and @samp{auto}. In
5039 Python, true and false are represented using boolean constants, and
5040 @samp{auto} is represented using @code{None}.
5042 @findex PARAM_UINTEGER
5043 @findex gdb.PARAM_UINTEGER
5044 @item gdb.PARAM_UINTEGER
5045 The value is an unsigned integer. The value of @code{None} should be
5046 interpreted to mean ``unlimited'' (literal @code{'unlimited'} can also
5047 be used to set that value), and the value of 0 is reserved and should
5050 @findex PARAM_INTEGER
5051 @findex gdb.PARAM_INTEGER
5052 @item gdb.PARAM_INTEGER
5053 The value is a signed integer. The value of @code{None} should be
5054 interpreted to mean ``unlimited'' (literal @code{'unlimited'} can also
5055 be used to set that value), and the value of 0 is reserved and should
5058 @findex PARAM_STRING
5059 @findex gdb.PARAM_STRING
5060 @item gdb.PARAM_STRING
5061 The value is a string. When the user modifies the string, any escape
5062 sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
5063 translated into corresponding characters and encoded into the current
5066 @findex PARAM_STRING_NOESCAPE
5067 @findex gdb.PARAM_STRING_NOESCAPE
5068 @item gdb.PARAM_STRING_NOESCAPE
5069 The value is a string. When the user modifies the string, escapes are
5070 passed through untranslated.
5072 @findex PARAM_OPTIONAL_FILENAME
5073 @findex gdb.PARAM_OPTIONAL_FILENAME
5074 @item gdb.PARAM_OPTIONAL_FILENAME
5075 The value is a either a filename (a string), or @code{None}.
5077 @findex PARAM_FILENAME
5078 @findex gdb.PARAM_FILENAME
5079 @item gdb.PARAM_FILENAME
5080 The value is a filename. This is just like
5081 @code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
5083 @findex PARAM_ZINTEGER
5084 @findex gdb.PARAM_ZINTEGER
5085 @item gdb.PARAM_ZINTEGER
5086 The value is a signed integer. This is like @code{PARAM_INTEGER},
5087 except that 0 is allowed and the value of @code{None} is not supported.
5089 @findex PARAM_ZUINTEGER
5090 @findex gdb.PARAM_ZUINTEGER
5091 @item gdb.PARAM_ZUINTEGER
5092 The value is an unsigned integer. This is like @code{PARAM_UINTEGER},
5093 except that 0 is allowed and the value of @code{None} is not supported.
5095 @findex PARAM_ZUINTEGER_UNLIMITED
5096 @findex gdb.PARAM_ZUINTEGER_UNLIMITED
5097 @item gdb.PARAM_ZUINTEGER_UNLIMITED
5098 The value is a signed integer. This is like @code{PARAM_INTEGER}
5099 including that the value of @code{None} should be interpreted to mean
5100 ``unlimited'' (literal @code{'unlimited'} can also be used to set that
5101 value), except that 0 is allowed, and the value cannot be negative,
5102 except the special value -1 is returned for the setting of ``unlimited''.
5105 @findex gdb.PARAM_ENUM
5106 @item gdb.PARAM_ENUM
5107 The value is a string, which must be one of a collection string
5108 constants provided when the parameter is created.
5111 @node Functions In Python
5112 @subsubsection Writing new convenience functions
5114 @cindex writing convenience functions
5115 @cindex convenience functions in python
5116 @cindex python convenience functions
5117 @tindex gdb.Function
5119 You can implement new convenience functions (@pxref{Convenience Vars})
5120 in Python. A convenience function is an instance of a subclass of the
5121 class @code{gdb.Function}.
5123 @defun Function.__init__ (name)
5124 The initializer for @code{Function} registers the new function with
5125 @value{GDBN}. The argument @var{name} is the name of the function,
5126 a string. The function will be visible to the user as a convenience
5127 variable of type @code{internal function}, whose name is the same as
5128 the given @var{name}.
5130 The documentation for the new function is taken from the documentation
5131 string for the new class.
5134 @defun Function.invoke (*args)
5135 When a convenience function is evaluated, its arguments are converted
5136 to instances of @code{gdb.Value}, and then the function's
5137 @code{invoke} method is called. Note that @value{GDBN} does not
5138 predetermine the arity of convenience functions. Instead, all
5139 available arguments are passed to @code{invoke}, following the
5140 standard Python calling convention. In particular, a convenience
5141 function can have default values for parameters without ill effect.
5143 The return value of this method is used as its value in the enclosing
5144 expression. If an ordinary Python value is returned, it is converted
5145 to a @code{gdb.Value} following the usual rules.
5148 The following code snippet shows how a trivial convenience function can
5149 be implemented in Python:
5152 class Greet (gdb.Function):
5153 """Return string to greet someone.
5154 Takes a name as argument."""
5156 def __init__ (self):
5157 super (Greet, self).__init__ ("greet")
5159 def invoke (self, name):
5160 return "Hello, %s!" % name.string ()
5165 The last line instantiates the class, and is necessary to trigger the
5166 registration of the function with @value{GDBN}. Depending on how the
5167 Python code is read into @value{GDBN}, you may need to import the
5168 @code{gdb} module explicitly.
5170 Now you can use the function in an expression:
5173 (gdb) print $greet("Bob")
5177 @node Progspaces In Python
5178 @subsubsection Program Spaces In Python
5180 @cindex progspaces in python
5181 @tindex gdb.Progspace
5183 A program space, or @dfn{progspace}, represents a symbolic view
5184 of an address space.
5185 It consists of all of the objfiles of the program.
5186 @xref{Objfiles In Python}.
5187 @xref{Inferiors Connections and Programs, program spaces}, for more details
5188 about program spaces.
5190 The following progspace-related functions are available in the
5193 @defun gdb.current_progspace ()
5194 This function returns the program space of the currently selected inferior.
5195 @xref{Inferiors Connections and Programs}. This is identical to
5196 @code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is
5197 included for historical compatibility.
5200 @defun gdb.progspaces ()
5201 Return a sequence of all the progspaces currently known to @value{GDBN}.
5204 Each progspace is represented by an instance of the @code{gdb.Progspace}
5207 @defvar Progspace.filename
5208 The file name, as a string, of the main symbol file (from which debug
5209 symbols have been loaded) for the progspace, e.g.@: the argument to
5210 the @kbd{symbol-file} or @kbd{file} commands.
5212 If there is no main symbol table currently loaded, then this attribute
5213 will be @code{None}.
5216 @defvar Progspace.symbol_file
5217 The @code{gdb.Objfile} representing the main symbol file (from which
5218 debug symbols have been loaded) for the @code{gdb.Progspace}. This is
5219 the symbol file set by the @kbd{symbol-file} or @kbd{file} commands.
5221 This will be the @code{gdb.Objfile} representing
5222 @code{Progspace.filename} when @code{Progspace.filename} is not
5225 If there is no main symbol table currently loaded, then this attribute
5226 will be @code{None}.
5228 If the @code{Progspace} is invalid, i.e.@:, when
5229 @code{Progspace.is_valid()} returns @code{False}, then attempting to
5230 access this attribute will raise a @code{RuntimeError} exception.
5233 @defvar Progspace.executable_filename
5234 The file name, as a string, of the executable file in use by this
5235 program space. The executable file is the file that @value{GDBN} will
5236 invoke in order to start an inferior when using a native target. The
5237 file name within this attribute is updated by the @kbd{exec-file} and
5238 @kbd{file} commands.
5240 If no executable is currently set within this @code{Progspace} then
5241 this attribute contains @code{None}.
5243 If the @code{Progspace} is invalid, i.e.@:, when
5244 @code{Progspace.is_valid()} returns @code{False}, then attempting to
5245 access this attribute will raise a @code{RuntimeError} exception.
5248 @defvar Progspace.pretty_printers
5249 The @code{pretty_printers} attribute is a list of functions. It is
5250 used to look up pretty-printers. A @code{Value} is passed to each
5251 function in order; if the function returns @code{None}, then the
5252 search continues. Otherwise, the return value should be an object
5253 which is used to format the value. @xref{Pretty Printing API}, for more
5257 @defvar Progspace.type_printers
5258 The @code{type_printers} attribute is a list of type printer objects.
5259 @xref{Type Printing API}, for more information.
5262 @defvar Progspace.frame_filters
5263 The @code{frame_filters} attribute is a dictionary of frame filter
5264 objects. @xref{Frame Filter API}, for more information.
5267 @defvar Progspace.missing_debug_handlers
5268 The @code{missing_debug_handlers} attribute is a list of the missing
5269 debug handler objects for this program space. @xref{Missing Debug
5270 Info In Python}, for more information.
5273 A program space has the following methods:
5275 @defun Progspace.block_for_pc (pc)
5276 Return the innermost @code{gdb.Block} containing the given @var{pc}
5277 value. If the block cannot be found for the @var{pc} value specified,
5278 the function will return @code{None}.
5281 @defun Progspace.find_pc_line (pc)
5282 Return the @code{gdb.Symtab_and_line} object corresponding to the
5283 @var{pc} value. @xref{Symbol Tables In Python}. If an invalid value
5284 of @var{pc} is passed as an argument, then the @code{symtab} and
5285 @code{line} attributes of the returned @code{gdb.Symtab_and_line}
5286 object will be @code{None} and 0 respectively.
5289 @defun Progspace.is_valid ()
5290 Returns @code{True} if the @code{gdb.Progspace} object is valid,
5291 @code{False} if not. A @code{gdb.Progspace} object can become invalid
5292 if the program space file it refers to is not referenced by any
5293 inferior. All other @code{gdb.Progspace} methods will throw an
5294 exception if it is invalid at the time the method is called.
5297 @defun Progspace.objfiles ()
5298 Return a sequence of all the objfiles referenced by this program
5299 space. @xref{Objfiles In Python}.
5302 @defun Progspace.solib_name (address)
5303 Return the name of the shared library holding the given @var{address}
5304 as a string, or @code{None}.
5307 @defun Progspace.objfile_for_address (address)
5308 Return the @code{gdb.Objfile} holding the given address, or
5309 @code{None} if no objfile covers it.
5312 One may add arbitrary attributes to @code{gdb.Progspace} objects
5313 in the usual Python way.
5314 This is useful if, for example, one needs to do some extra record keeping
5315 associated with the program space.
5317 In this contrived example, we want to perform some processing when
5318 an objfile with a certain symbol is loaded, but we only want to do
5319 this once because it is expensive. To achieve this we record the results
5320 with the program space because we can't predict when the desired objfile
5325 def clear_objfiles_handler(event):
5326 event.progspace.expensive_computation = None
5327 def expensive(symbol):
5328 """A mock routine to perform an "expensive" computation on symbol."""
5329 print ("Computing the answer to the ultimate question ...")
5331 def new_objfile_handler(event):
5332 objfile = event.new_objfile
5333 progspace = objfile.progspace
5334 if not hasattr(progspace, 'expensive_computation') or \
5335 progspace.expensive_computation is None:
5336 # We use 'main' for the symbol to keep the example simple.
5337 # Note: There's no current way to constrain the lookup
5339 symbol = gdb.lookup_global_symbol('main')
5340 if symbol is not None:
5341 progspace.expensive_computation = expensive(symbol)
5342 gdb.events.clear_objfiles.connect(clear_objfiles_handler)
5343 gdb.events.new_objfile.connect(new_objfile_handler)
5345 (gdb) file /tmp/hello
5346 Reading symbols from /tmp/hello...
5347 Computing the answer to the ultimate question ...
5348 (gdb) python print gdb.current_progspace().expensive_computation
5351 Starting program: /tmp/hello
5353 [Inferior 1 (process 4242) exited normally]
5356 @node Objfiles In Python
5357 @subsubsection Objfiles In Python
5359 @cindex objfiles in python
5362 @value{GDBN} loads symbols for an inferior from various
5363 symbol-containing files (@pxref{Files}). These include the primary
5364 executable file, any shared libraries used by the inferior, and any
5365 separate debug info files (@pxref{Separate Debug Files}).
5366 @value{GDBN} calls these symbol-containing files @dfn{objfiles}.
5368 The following objfile-related functions are available in the
5371 @defun gdb.current_objfile ()
5372 When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
5373 sets the ``current objfile'' to the corresponding objfile. This
5374 function returns the current objfile. If there is no current objfile,
5375 this function returns @code{None}.
5378 @defun gdb.objfiles ()
5379 Return a sequence of objfiles referenced by the current program space.
5380 @xref{Objfiles In Python}, and @ref{Progspaces In Python}. This is identical
5381 to @code{gdb.selected_inferior().progspace.objfiles()} and is included for
5382 historical compatibility.
5385 @defun gdb.lookup_objfile (name @r{[}, by_build_id@r{]})
5386 Look up @var{name}, a file name or build ID, in the list of objfiles
5387 for the current program space (@pxref{Progspaces In Python}).
5388 If the objfile is not found throw the Python @code{ValueError} exception.
5390 If @var{name} is a relative file name, then it will match any
5391 source file name with the same trailing components. For example, if
5392 @var{name} is @samp{gcc/expr.c}, then it will match source file
5393 name of @file{/build/trunk/gcc/expr.c}, but not
5394 @file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
5396 If @var{by_build_id} is provided and is @code{True} then @var{name}
5397 is the build ID of the objfile. Otherwise, @var{name} is a file name.
5398 This is supported only on some operating systems, notably those which use
5399 the ELF format for binary files and the @sc{gnu} Binutils. For more details
5400 about this feature, see the description of the @option{--build-id}
5401 command-line option in @ref{Options, , Command Line Options, ld,
5405 Each objfile is represented by an instance of the @code{gdb.Objfile}
5408 @defvar Objfile.filename
5409 The file name of the objfile as a string, with symbolic links resolved.
5411 The value is @code{None} if the objfile is no longer valid.
5412 See the @code{gdb.Objfile.is_valid} method, described below.
5415 @defvar Objfile.username
5416 The file name of the objfile as specified by the user as a string.
5418 The value is @code{None} if the objfile is no longer valid.
5419 See the @code{gdb.Objfile.is_valid} method, described below.
5422 @defvar Objfile.is_file
5423 An objfile often comes from an ordinary file, but in some cases it may
5424 be constructed from the contents of memory. This attribute is
5425 @code{True} for file-backed objfiles, and @code{False} for other
5429 @defvar Objfile.owner
5430 For separate debug info objfiles this is the corresponding @code{gdb.Objfile}
5431 object that debug info is being provided for.
5432 Otherwise this is @code{None}.
5433 Separate debug info objfiles are added with the
5434 @code{gdb.Objfile.add_separate_debug_file} method, described below.
5437 @defvar Objfile.build_id
5438 The build ID of the objfile as a string.
5439 If the objfile does not have a build ID then the value is @code{None}.
5441 This is supported only on some operating systems, notably those which use
5442 the ELF format for binary files and the @sc{gnu} Binutils. For more details
5443 about this feature, see the description of the @option{--build-id}
5444 command-line option in @ref{Options, , Command Line Options, ld,
5448 @defvar Objfile.progspace
5449 The containing program space of the objfile as a @code{gdb.Progspace}
5450 object. @xref{Progspaces In Python}.
5453 @defvar Objfile.pretty_printers
5454 The @code{pretty_printers} attribute is a list of functions. It is
5455 used to look up pretty-printers. A @code{Value} is passed to each
5456 function in order; if the function returns @code{None}, then the
5457 search continues. Otherwise, the return value should be an object
5458 which is used to format the value. @xref{Pretty Printing API}, for more
5462 @defvar Objfile.type_printers
5463 The @code{type_printers} attribute is a list of type printer objects.
5464 @xref{Type Printing API}, for more information.
5467 @defvar Objfile.frame_filters
5468 The @code{frame_filters} attribute is a dictionary of frame filter
5469 objects. @xref{Frame Filter API}, for more information.
5472 One may add arbitrary attributes to @code{gdb.Objfile} objects
5473 in the usual Python way.
5474 This is useful if, for example, one needs to do some extra record keeping
5475 associated with the objfile.
5477 In this contrived example we record the time when @value{GDBN}
5483 def new_objfile_handler(event):
5484 # Set the time_loaded attribute of the new objfile.
5485 event.new_objfile.time_loaded = datetime.datetime.today()
5486 gdb.events.new_objfile.connect(new_objfile_handler)
5489 Reading symbols from ./hello...
5490 (gdb) python print gdb.objfiles()[0].time_loaded
5491 2014-10-09 11:41:36.770345
5494 A @code{gdb.Objfile} object has the following methods:
5496 @defun Objfile.is_valid ()
5497 Returns @code{True} if the @code{gdb.Objfile} object is valid,
5498 @code{False} if not. A @code{gdb.Objfile} object can become invalid
5499 if the object file it refers to is not loaded in @value{GDBN} any
5500 longer. All other @code{gdb.Objfile} methods will throw an exception
5501 if it is invalid at the time the method is called.
5504 @defun Objfile.add_separate_debug_file (file)
5505 Add @var{file} to the list of files that @value{GDBN} will search for
5506 debug information for the objfile.
5507 This is useful when the debug info has been removed from the program
5508 and stored in a separate file. @value{GDBN} has built-in support for
5509 finding separate debug info files (@pxref{Separate Debug Files}), but if
5510 the file doesn't live in one of the standard places that @value{GDBN}
5511 searches then this function can be used to add a debug info file
5512 from a different place.
5515 @defun Objfile.lookup_global_symbol (name @r{[}, domain@r{]})
5516 Search for a global symbol named @var{name} in this objfile. Optionally, the
5517 search scope can be restricted with the @var{domain} argument.
5518 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5519 module and described in @ref{Symbols In Python}. This function is similar to
5520 @code{gdb.lookup_global_symbol}, except that the search is limited to this
5523 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5527 @defun Objfile.lookup_static_symbol (name @r{[}, domain@r{]})
5528 Like @code{Objfile.lookup_global_symbol}, but searches for a global
5529 symbol with static linkage named @var{name} in this objfile.
5532 @node Frames In Python
5533 @subsubsection Accessing inferior stack frames from Python
5535 @cindex frames in python
5536 When the debugged program stops, @value{GDBN} is able to analyze its call
5537 stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
5538 represents a frame in the stack. A @code{gdb.Frame} object is only valid
5539 while its corresponding frame exists in the inferior's stack. If you try
5540 to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
5541 exception (@pxref{Exception Handling}).
5543 Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
5547 (@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
5551 The following frame-related functions are available in the @code{gdb} module:
5553 @defun gdb.selected_frame ()
5554 Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
5557 @defun gdb.newest_frame ()
5558 Return the newest frame object for the selected thread.
5561 @defun gdb.frame_stop_reason_string (reason)
5562 Return a string explaining the reason why @value{GDBN} stopped unwinding
5563 frames, as expressed by the given @var{reason} code (an integer, see the
5564 @code{unwind_stop_reason} method further down in this section).
5567 @defun gdb.invalidate_cached_frames
5568 @value{GDBN} internally keeps a cache of the frames that have been
5569 unwound. This function invalidates this cache.
5571 This function should not generally be called by ordinary Python code.
5572 It is documented for the sake of completeness.
5575 A @code{gdb.Frame} object has the following methods:
5577 @defun Frame.is_valid ()
5578 Returns true if the @code{gdb.Frame} object is valid, false if not.
5579 A frame object can become invalid if the frame it refers to doesn't
5580 exist anymore in the inferior. All @code{gdb.Frame} methods will throw
5581 an exception if it is invalid at the time the method is called.
5584 @defun Frame.name ()
5585 Returns the function name of the frame, or @code{None} if it can't be
5589 @defun Frame.architecture ()
5590 Returns the @code{gdb.Architecture} object corresponding to the frame's
5591 architecture. @xref{Architectures In Python}.
5594 @defun Frame.type ()
5595 Returns the type of the frame. The value can be one of:
5597 @item gdb.NORMAL_FRAME
5598 An ordinary stack frame.
5600 @item gdb.DUMMY_FRAME
5601 A fake stack frame that was created by @value{GDBN} when performing an
5602 inferior function call.
5604 @item gdb.INLINE_FRAME
5605 A frame representing an inlined function. The function was inlined
5606 into a @code{gdb.NORMAL_FRAME} that is older than this one.
5608 @item gdb.TAILCALL_FRAME
5609 A frame representing a tail call. @xref{Tail Call Frames}.
5611 @item gdb.SIGTRAMP_FRAME
5612 A signal trampoline frame. This is the frame created by the OS when
5613 it calls into a signal handler.
5615 @item gdb.ARCH_FRAME
5616 A fake stack frame representing a cross-architecture call.
5618 @item gdb.SENTINEL_FRAME
5619 This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
5624 @defun Frame.unwind_stop_reason ()
5625 Return an integer representing the reason why it's not possible to find
5626 more frames toward the outermost frame. Use
5627 @code{gdb.frame_stop_reason_string} to convert the value returned by this
5628 function to a string. The value can be one of:
5631 @item gdb.FRAME_UNWIND_NO_REASON
5632 No particular reason (older frames should be available).
5634 @item gdb.FRAME_UNWIND_NULL_ID
5635 The previous frame's analyzer returns an invalid result. This is no
5636 longer used by @value{GDBN}, and is kept only for backward
5639 @item gdb.FRAME_UNWIND_OUTERMOST
5640 This frame is the outermost.
5642 @item gdb.FRAME_UNWIND_UNAVAILABLE
5643 Cannot unwind further, because that would require knowing the
5644 values of registers or memory that have not been collected.
5646 @item gdb.FRAME_UNWIND_INNER_ID
5647 This frame ID looks like it ought to belong to a NEXT frame,
5648 but we got it for a PREV frame. Normally, this is a sign of
5649 unwinder failure. It could also indicate stack corruption.
5651 @item gdb.FRAME_UNWIND_SAME_ID
5652 This frame has the same ID as the previous one. That means
5653 that unwinding further would almost certainly give us another
5654 frame with exactly the same ID, so break the chain. Normally,
5655 this is a sign of unwinder failure. It could also indicate
5658 @item gdb.FRAME_UNWIND_NO_SAVED_PC
5659 The frame unwinder did not find any saved PC, but we needed
5660 one to unwind further.
5662 @item gdb.FRAME_UNWIND_MEMORY_ERROR
5663 The frame unwinder caused an error while trying to access memory.
5665 @item gdb.FRAME_UNWIND_FIRST_ERROR
5666 Any stop reason greater or equal to this value indicates some kind
5667 of error. This special value facilitates writing code that tests
5668 for errors in unwinding in a way that will work correctly even if
5669 the list of the other values is modified in future @value{GDBN}
5670 versions. Using it, you could write:
5672 reason = gdb.selected_frame().unwind_stop_reason ()
5673 reason_str = gdb.frame_stop_reason_string (reason)
5674 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
5675 print ("An error occurred: %s" % reason_str)
5682 Returns the frame's resume address.
5685 @defun Frame.block ()
5686 Return the frame's code block. @xref{Blocks In Python}. If the frame
5687 does not have a block -- for example, if there is no debugging
5688 information for the code in question -- then this will throw an
5692 @defun Frame.function ()
5693 Return the symbol for the function corresponding to this frame.
5694 @xref{Symbols In Python}.
5697 @defun Frame.older ()
5698 Return the frame that called this frame. If this is the oldest frame,
5702 @defun Frame.newer ()
5703 Return the frame called by this frame. If this is the newest frame,
5707 @defun Frame.find_sal ()
5708 Return the frame's symtab and line object.
5709 @xref{Symbol Tables In Python}.
5712 @anchor{gdbpy_frame_read_register}
5713 @defun Frame.read_register (register)
5714 Return the value of @var{register} in this frame. Returns a
5715 @code{Gdb.Value} object. Throws an exception if @var{register} does
5716 not exist. The @var{register} argument must be one of the following:
5719 A string that is the name of a valid register (e.g., @code{'sp'} or
5722 A @code{gdb.RegisterDescriptor} object (@pxref{Registers In Python}).
5724 A @value{GDBN} internal, platform specific number. Using these
5725 numbers is supported for historic reasons, but is not recommended as
5726 future changes to @value{GDBN} could change the mapping between
5727 numbers and the registers they represent, breaking any Python code
5728 that uses the platform-specific numbers. The numbers are usually
5729 found in the corresponding @file{@var{platform}-tdep.h} file in the
5730 @value{GDBN} source tree.
5732 Using a string to access registers will be slightly slower than the
5733 other two methods as @value{GDBN} must look up the mapping between
5734 name and internal register number. If performance is critical
5735 consider looking up and caching a @code{gdb.RegisterDescriptor}
5739 @defun Frame.read_var (variable @r{[}, block@r{]})
5740 Return the value of @var{variable} in this frame. If the optional
5741 argument @var{block} is provided, search for the variable from that
5742 block; otherwise start at the frame's current block (which is
5743 determined by the frame's current program counter). The @var{variable}
5744 argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
5745 @code{gdb.Block} object.
5748 @defun Frame.select ()
5749 Set this frame to be the selected frame. @xref{Stack, ,Examining the
5753 @defun Frame.static_link ()
5754 In some languages (e.g., Ada, but also a GNU C extension), a nested
5755 function can access the variables in the outer scope. This is done
5756 via a ``static link'', which is a reference from the nested frame to
5757 the appropriate outer frame.
5759 This method returns this frame's static link frame, if one exists. If
5760 there is no static link, this method returns @code{None}.
5763 @defun Frame.level ()
5764 Return an integer, the stack frame level for this frame. @xref{Frames, ,Stack Frames}.
5767 @defun Frame.language ()
5768 Return a string, the source language for this frame.
5771 @node Blocks In Python
5772 @subsubsection Accessing blocks from Python
5774 @cindex blocks in python
5777 In @value{GDBN}, symbols are stored in blocks. A block corresponds
5778 roughly to a scope in the source code. Blocks are organized
5779 hierarchically, and are represented individually in Python as a
5780 @code{gdb.Block}. Blocks rely on debugging information being
5783 A frame has a block. Please see @ref{Frames In Python}, for a more
5784 in-depth discussion of frames.
5786 The outermost block is known as the @dfn{global block}. The global
5787 block typically holds public global variables and functions.
5789 The block nested just inside the global block is the @dfn{static
5790 block}. The static block typically holds file-scoped variables and
5793 @value{GDBN} provides a method to get a block's superblock, but there
5794 is currently no way to examine the sub-blocks of a block, or to
5795 iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
5798 Here is a short example that should help explain blocks:
5801 /* This is in the global block. */
5804 /* This is in the static block. */
5805 static int file_scope;
5807 /* 'function' is in the global block, and 'argument' is
5808 in a block nested inside of 'function'. */
5809 int function (int argument)
5811 /* 'local' is in a block inside 'function'. It may or may
5812 not be in the same block as 'argument'. */
5816 /* 'inner' is in a block whose superblock is the one holding
5820 /* If this call is expanded by the compiler, you may see
5821 a nested block here whose function is 'inline_function'
5822 and whose superblock is the one holding 'inner'. */
5828 A @code{gdb.Block} is iterable. The iterator returns the symbols
5829 (@pxref{Symbols In Python}) local to the block. Python programs
5830 should not assume that a specific block object will always contain a
5831 given symbol, since changes in @value{GDBN} features and
5832 infrastructure may cause symbols move across blocks in a symbol
5833 table. You can also use Python's @dfn{dictionary syntax} to access
5834 variables in this block, e.g.:
5837 symbol = some_block['variable'] # symbol is of type gdb.Symbol
5840 The following block-related functions are available in the @code{gdb}
5843 @defun gdb.block_for_pc (pc)
5844 Return the innermost @code{gdb.Block} containing the given @var{pc}
5845 value. If the block cannot be found for the @var{pc} value specified,
5846 the function will return @code{None}. This is identical to
5847 @code{gdb.current_progspace().block_for_pc(pc)} and is included for
5848 historical compatibility.
5851 A @code{gdb.Block} object has the following methods:
5853 @defun Block.is_valid ()
5854 Returns @code{True} if the @code{gdb.Block} object is valid,
5855 @code{False} if not. A block object can become invalid if the block it
5856 refers to doesn't exist anymore in the inferior. All other
5857 @code{gdb.Block} methods will throw an exception if it is invalid at
5858 the time the method is called. The block's validity is also checked
5859 during iteration over symbols of the block.
5862 A @code{gdb.Block} object has the following attributes:
5865 The start address of the block. This attribute is not writable.
5869 One past the last address that appears in the block. This attribute
5873 @defvar Block.function
5874 The name of the block represented as a @code{gdb.Symbol}. If the
5875 block is not named, then this attribute holds @code{None}. This
5876 attribute is not writable.
5878 For ordinary function blocks, the superblock is the static block.
5879 However, you should note that it is possible for a function block to
5880 have a superblock that is not the static block -- for instance this
5881 happens for an inlined function.
5884 @defvar Block.superblock
5885 The block containing this block. If this parent block does not exist,
5886 this attribute holds @code{None}. This attribute is not writable.
5889 @defvar Block.global_block
5890 The global block associated with this block. This attribute is not
5894 @defvar Block.static_block
5895 The static block associated with this block. This attribute is not
5899 @defvar Block.is_global
5900 @code{True} if the @code{gdb.Block} object is a global block,
5901 @code{False} if not. This attribute is not
5905 @defvar Block.is_static
5906 @code{True} if the @code{gdb.Block} object is a static block,
5907 @code{False} if not. This attribute is not writable.
5910 @node Symbols In Python
5911 @subsubsection Python representation of Symbols
5913 @cindex symbols in python
5916 @value{GDBN} represents every variable, function and type as an
5917 entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
5918 Similarly, Python represents these symbols in @value{GDBN} with the
5919 @code{gdb.Symbol} object.
5921 The following symbol-related functions are available in the @code{gdb}
5924 @defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
5925 This function searches for a symbol by name. The search scope can be
5926 restricted to the parameters defined in the optional domain and block
5929 @var{name} is the name of the symbol. It must be a string. The
5930 optional @var{block} argument restricts the search to symbols visible
5931 in that @var{block}. The @var{block} argument must be a
5932 @code{gdb.Block} object. If omitted, the block for the current frame
5933 is used. The optional @var{domain} argument restricts
5934 the search to the domain type. The @var{domain} argument must be a
5935 domain constant defined in the @code{gdb} module and described later
5938 The result is a tuple of two elements.
5939 The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
5941 If the symbol is found, the second element is @code{True} if the symbol
5942 is a field of a method's object (e.g., @code{this} in C@t{++}),
5943 otherwise it is @code{False}.
5944 If the symbol is not found, the second element is @code{False}.
5947 @defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
5948 This function searches for a global symbol by name.
5949 The search scope can be restricted to by the domain argument.
5951 @var{name} is the name of the symbol. It must be a string.
5952 The optional @var{domain} argument restricts the search to the domain type.
5953 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5954 module and described later in this chapter.
5956 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5960 @defun gdb.lookup_static_symbol (name @r{[}, domain@r{]})
5961 This function searches for a global symbol with static linkage by name.
5962 The search scope can be restricted to by the domain argument.
5964 @var{name} is the name of the symbol. It must be a string.
5965 The optional @var{domain} argument restricts the search to the domain type.
5966 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5967 module and described later in this chapter.
5969 The result is a @code{gdb.Symbol} object or @code{None} if the symbol
5972 Note that this function will not find function-scoped static variables. To look
5973 up such variables, iterate over the variables of the function's
5974 @code{gdb.Block} and check that @code{block.addr_class} is
5975 @code{gdb.SYMBOL_LOC_STATIC}.
5977 There can be multiple global symbols with static linkage with the same
5978 name. This function will only return the first matching symbol that
5979 it finds. Which symbol is found depends on where @value{GDBN} is
5980 currently stopped, as @value{GDBN} will first search for matching
5981 symbols in the current object file, and then search all other object
5982 files. If the application is not yet running then @value{GDBN} will
5983 search all object files in the order they appear in the debug
5987 @defun gdb.lookup_static_symbols (name @r{[}, domain@r{]})
5988 Similar to @code{gdb.lookup_static_symbol}, this function searches for
5989 global symbols with static linkage by name, and optionally restricted
5990 by the domain argument. However, this function returns a list of all
5991 matching symbols found, not just the first one.
5993 @var{name} is the name of the symbol. It must be a string.
5994 The optional @var{domain} argument restricts the search to the domain type.
5995 The @var{domain} argument must be a domain constant defined in the @code{gdb}
5996 module and described later in this chapter.
5998 The result is a list of @code{gdb.Symbol} objects which could be empty
5999 if no matching symbols were found.
6001 Note that this function will not find function-scoped static variables. To look
6002 up such variables, iterate over the variables of the function's
6003 @code{gdb.Block} and check that @code{block.addr_class} is
6004 @code{gdb.SYMBOL_LOC_STATIC}.
6007 A @code{gdb.Symbol} object has the following attributes:
6010 The type of the symbol or @code{None} if no type is recorded.
6011 This attribute is represented as a @code{gdb.Type} object.
6012 @xref{Types In Python}. This attribute is not writable.
6015 @defvar Symbol.symtab
6016 The symbol table in which the symbol appears. This attribute is
6017 represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
6018 Python}. This attribute is not writable.
6022 The line number in the source code at which the symbol was defined.
6027 The name of the symbol as a string. This attribute is not writable.
6030 @defvar Symbol.linkage_name
6031 The name of the symbol, as used by the linker (i.e., may be mangled).
6032 This attribute is not writable.
6035 @defvar Symbol.print_name
6036 The name of the symbol in a form suitable for output. This is either
6037 @code{name} or @code{linkage_name}, depending on whether the user
6038 asked @value{GDBN} to display demangled or mangled names.
6041 @defvar Symbol.addr_class
6042 The address class of the symbol. This classifies how to find the value
6043 of a symbol. Each address class is a constant defined in the
6044 @code{gdb} module and described later in this chapter.
6047 @defvar Symbol.needs_frame
6048 This is @code{True} if evaluating this symbol's value requires a frame
6049 (@pxref{Frames In Python}) and @code{False} otherwise. Typically,
6050 local variables will require a frame, but other symbols will not.
6053 @defvar Symbol.is_argument
6054 @code{True} if the symbol is an argument of a function.
6057 @defvar Symbol.is_constant
6058 @code{True} if the symbol is a constant.
6061 @defvar Symbol.is_function
6062 @code{True} if the symbol is a function or a method.
6065 @defvar Symbol.is_variable
6066 @code{True} if the symbol is a variable, as opposed to something like
6067 a function or type. Note that this also returns @code{False} for
6071 A @code{gdb.Symbol} object has the following methods:
6073 @defun Symbol.is_valid ()
6074 Returns @code{True} if the @code{gdb.Symbol} object is valid,
6075 @code{False} if not. A @code{gdb.Symbol} object can become invalid if
6076 the symbol it refers to does not exist in @value{GDBN} any longer.
6077 All other @code{gdb.Symbol} methods will throw an exception if it is
6078 invalid at the time the method is called.
6081 @defun Symbol.value (@r{[}frame@r{]})
6082 Compute the value of the symbol, as a @code{gdb.Value}. For
6083 functions, this computes the address of the function, cast to the
6084 appropriate type. If the symbol requires a frame in order to compute
6085 its value, then @var{frame} must be given. If @var{frame} is not
6086 given, or if @var{frame} is invalid, then this method will throw an
6090 The available domain categories in @code{gdb.Symbol} are represented
6091 as constants in the @code{gdb} module:
6094 @vindex SYMBOL_UNDEF_DOMAIN
6095 @item gdb.SYMBOL_UNDEF_DOMAIN
6096 This is used when a domain has not been discovered or none of the
6097 following domains apply. This usually indicates an error either
6098 in the symbol information or in @value{GDBN}'s handling of symbols.
6100 @vindex SYMBOL_VAR_DOMAIN
6101 @item gdb.SYMBOL_VAR_DOMAIN
6102 This domain contains variables, function names, typedef names and enum
6105 @vindex SYMBOL_STRUCT_DOMAIN
6106 @item gdb.SYMBOL_STRUCT_DOMAIN
6107 This domain holds struct, union and enum type names.
6109 @vindex SYMBOL_LABEL_DOMAIN
6110 @item gdb.SYMBOL_LABEL_DOMAIN
6111 This domain contains names of labels (for gotos).
6113 @vindex SYMBOL_MODULE_DOMAIN
6114 @item gdb.SYMBOL_MODULE_DOMAIN
6115 This domain contains names of Fortran module types.
6117 @vindex SYMBOL_COMMON_BLOCK_DOMAIN
6118 @item gdb.SYMBOL_COMMON_BLOCK_DOMAIN
6119 This domain contains names of Fortran common blocks.
6122 The available address class categories in @code{gdb.Symbol} are represented
6123 as constants in the @code{gdb} module:
6126 @vindex SYMBOL_LOC_UNDEF
6127 @item gdb.SYMBOL_LOC_UNDEF
6128 If this is returned by address class, it indicates an error either in
6129 the symbol information or in @value{GDBN}'s handling of symbols.
6131 @vindex SYMBOL_LOC_CONST
6132 @item gdb.SYMBOL_LOC_CONST
6133 Value is constant int.
6135 @vindex SYMBOL_LOC_STATIC
6136 @item gdb.SYMBOL_LOC_STATIC
6137 Value is at a fixed address.
6139 @vindex SYMBOL_LOC_REGISTER
6140 @item gdb.SYMBOL_LOC_REGISTER
6141 Value is in a register.
6143 @vindex SYMBOL_LOC_ARG
6144 @item gdb.SYMBOL_LOC_ARG
6145 Value is an argument. This value is at the offset stored within the
6146 symbol inside the frame's argument list.
6148 @vindex SYMBOL_LOC_REF_ARG
6149 @item gdb.SYMBOL_LOC_REF_ARG
6150 Value address is stored in the frame's argument list. Just like
6151 @code{LOC_ARG} except that the value's address is stored at the
6152 offset, not the value itself.
6154 @vindex SYMBOL_LOC_REGPARM_ADDR
6155 @item gdb.SYMBOL_LOC_REGPARM_ADDR
6156 Value is a specified register. Just like @code{LOC_REGISTER} except
6157 the register holds the address of the argument instead of the argument
6160 @vindex SYMBOL_LOC_LOCAL
6161 @item gdb.SYMBOL_LOC_LOCAL
6162 Value is a local variable.
6164 @vindex SYMBOL_LOC_TYPEDEF
6165 @item gdb.SYMBOL_LOC_TYPEDEF
6166 Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
6169 @vindex SYMBOL_LOC_LABEL
6170 @item gdb.SYMBOL_LOC_LABEL
6173 @vindex SYMBOL_LOC_BLOCK
6174 @item gdb.SYMBOL_LOC_BLOCK
6177 @vindex SYMBOL_LOC_CONST_BYTES
6178 @item gdb.SYMBOL_LOC_CONST_BYTES
6179 Value is a byte-sequence.
6181 @vindex SYMBOL_LOC_UNRESOLVED
6182 @item gdb.SYMBOL_LOC_UNRESOLVED
6183 Value is at a fixed address, but the address of the variable has to be
6184 determined from the minimal symbol table whenever the variable is
6187 @vindex SYMBOL_LOC_OPTIMIZED_OUT
6188 @item gdb.SYMBOL_LOC_OPTIMIZED_OUT
6189 The value does not actually exist in the program.
6191 @vindex SYMBOL_LOC_COMPUTED
6192 @item gdb.SYMBOL_LOC_COMPUTED
6193 The value's address is a computed location.
6195 @vindex SYMBOL_LOC_COMMON_BLOCK
6196 @item gdb.SYMBOL_LOC_COMMON_BLOCK
6197 The value's address is a symbol. This is only used for Fortran common
6201 @node Symbol Tables In Python
6202 @subsubsection Symbol table representation in Python
6204 @cindex symbol tables in python
6206 @tindex gdb.Symtab_and_line
6208 Access to symbol table data maintained by @value{GDBN} on the inferior
6209 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
6210 @code{gdb.Symtab}. Symbol table and line data for a frame is returned
6211 from the @code{find_sal} method in @code{gdb.Frame} object.
6212 @xref{Frames In Python}.
6214 For more information on @value{GDBN}'s symbol table management, see
6215 @ref{Symbols, ,Examining the Symbol Table}, for more information.
6217 A @code{gdb.Symtab_and_line} object has the following attributes:
6219 @defvar Symtab_and_line.symtab
6220 The symbol table object (@code{gdb.Symtab}) for this frame.
6221 This attribute is not writable.
6224 @defvar Symtab_and_line.pc
6225 Indicates the start of the address range occupied by code for the
6226 current source line. This attribute is not writable.
6229 @defvar Symtab_and_line.last
6230 Indicates the end of the address range occupied by code for the current
6231 source line. This attribute is not writable.
6234 @defvar Symtab_and_line.line
6235 Indicates the current line number for this object. This
6236 attribute is not writable.
6239 A @code{gdb.Symtab_and_line} object has the following methods:
6241 @defun Symtab_and_line.is_valid ()
6242 Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
6243 @code{False} if not. A @code{gdb.Symtab_and_line} object can become
6244 invalid if the Symbol table and line object it refers to does not
6245 exist in @value{GDBN} any longer. All other
6246 @code{gdb.Symtab_and_line} methods will throw an exception if it is
6247 invalid at the time the method is called.
6250 A @code{gdb.Symtab} object has the following attributes:
6252 @defvar Symtab.filename
6253 The symbol table's source filename. This attribute is not writable.
6256 @defvar Symtab.objfile
6257 The symbol table's backing object file. @xref{Objfiles In Python}.
6258 This attribute is not writable.
6261 @defvar Symtab.producer
6262 The name and possibly version number of the program that
6263 compiled the code in the symbol table.
6264 The contents of this string is up to the compiler.
6265 If no producer information is available then @code{None} is returned.
6266 This attribute is not writable.
6269 A @code{gdb.Symtab} object has the following methods:
6271 @defun Symtab.is_valid ()
6272 Returns @code{True} if the @code{gdb.Symtab} object is valid,
6273 @code{False} if not. A @code{gdb.Symtab} object can become invalid if
6274 the symbol table it refers to does not exist in @value{GDBN} any
6275 longer. All other @code{gdb.Symtab} methods will throw an exception
6276 if it is invalid at the time the method is called.
6279 @defun Symtab.fullname ()
6280 Return the symbol table's source absolute file name.
6283 @defun Symtab.global_block ()
6284 Return the global block of the underlying symbol table.
6285 @xref{Blocks In Python}.
6288 @defun Symtab.static_block ()
6289 Return the static block of the underlying symbol table.
6290 @xref{Blocks In Python}.
6293 @defun Symtab.linetable ()
6294 Return the line table associated with the symbol table.
6295 @xref{Line Tables In Python}.
6298 @node Line Tables In Python
6299 @subsubsection Manipulating line tables using Python
6301 @cindex line tables in python
6302 @tindex gdb.LineTable
6304 Python code can request and inspect line table information from a
6305 symbol table that is loaded in @value{GDBN}. A line table is a
6306 mapping of source lines to their executable locations in memory. To
6307 acquire the line table information for a particular symbol table, use
6308 the @code{linetable} function (@pxref{Symbol Tables In Python}).
6310 A @code{gdb.LineTable} is iterable. The iterator returns
6311 @code{LineTableEntry} objects that correspond to the source line and
6312 address for each line table entry. @code{LineTableEntry} objects have
6313 the following attributes:
6315 @defvar LineTableEntry.line
6316 The source line number for this line table entry. This number
6317 corresponds to the actual line of source. This attribute is not
6321 @defvar LineTableEntry.pc
6322 The address that is associated with the line table entry where the
6323 executable code for that source line resides in memory. This
6324 attribute is not writable.
6327 As there can be multiple addresses for a single source line, you may
6328 receive multiple @code{LineTableEntry} objects with matching
6329 @code{line} attributes, but with different @code{pc} attributes. The
6330 iterator is sorted in ascending @code{pc} order. Here is a small
6331 example illustrating iterating over a line table.
6334 symtab = gdb.selected_frame().find_sal().symtab
6335 linetable = symtab.linetable()
6336 for line in linetable:
6337 print ("Line: "+str(line.line)+" Address: "+hex(line.pc))
6340 This will have the following output:
6343 Line: 33 Address: 0x4005c8L
6344 Line: 37 Address: 0x4005caL
6345 Line: 39 Address: 0x4005d2L
6346 Line: 40 Address: 0x4005f8L
6347 Line: 42 Address: 0x4005ffL
6348 Line: 44 Address: 0x400608L
6349 Line: 42 Address: 0x40060cL
6350 Line: 45 Address: 0x400615L
6353 In addition to being able to iterate over a @code{LineTable}, it also
6354 has the following direct access methods:
6356 @defun LineTable.line (line)
6357 Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
6358 entries in the line table for the given @var{line}, which specifies
6359 the source code line. If there are no entries for that source code
6360 @var{line}, the Python @code{None} is returned.
6363 @defun LineTable.has_line (line)
6364 Return a Python @code{Boolean} indicating whether there is an entry in
6365 the line table for this source line. Return @code{True} if an entry
6366 is found, or @code{False} if not.
6369 @defun LineTable.source_lines ()
6370 Return a Python @code{List} of the source line numbers in the symbol
6371 table. Only lines with executable code locations are returned. The
6372 contents of the @code{List} will just be the source line entries
6373 represented as Python @code{Long} values.
6376 @node Breakpoints In Python
6377 @subsubsection Manipulating breakpoints using Python
6379 @cindex breakpoints in python
6380 @tindex gdb.Breakpoint
6382 Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
6385 A breakpoint can be created using one of the two forms of the
6386 @code{gdb.Breakpoint} constructor. The first one accepts a string
6387 like one would pass to the @code{break}
6388 (@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch}
6389 (@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to
6390 create both breakpoints and watchpoints. The second accepts separate Python
6391 arguments similar to @ref{Explicit Locations}, and can only be used to create
6394 @defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]})
6395 Create a new breakpoint according to @var{spec}, which is a string naming the
6396 location of a breakpoint, or an expression that defines a watchpoint. The
6397 string should describe a location in a format recognized by the @code{break}
6398 command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a
6399 watchpoint, by the @code{watch} command
6400 (@pxref{Set Watchpoints, , Setting Watchpoints}).
6402 The optional @var{type} argument specifies the type of the breakpoint to create,
6405 The optional @var{wp_class} argument defines the class of watchpoint to create,
6406 if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it
6407 defaults to @code{gdb.WP_WRITE}.
6409 The optional @var{internal} argument allows the breakpoint to become invisible
6410 to the user. The breakpoint will neither be reported when created, nor will it
6411 be listed in the output from @code{info breakpoints} (but will be listed with
6412 the @code{maint info breakpoints} command).
6414 The optional @var{temporary} argument makes the breakpoint a temporary
6415 breakpoint. Temporary breakpoints are deleted after they have been hit. Any
6416 further access to the Python breakpoint after it has been hit will result in a
6417 runtime error (as that breakpoint has now been automatically deleted).
6419 The optional @var{qualified} argument is a boolean that allows interpreting
6420 the function passed in @code{spec} as a fully-qualified name. It is equivalent
6421 to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
6422 @ref{Explicit Locations}).
6426 @defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]})
6427 This second form of creating a new breakpoint specifies the explicit
6428 location (@pxref{Explicit Locations}) using keywords. The new breakpoint will
6429 be created in the specified source file @var{source}, at the specified
6430 @var{function}, @var{label} and @var{line}.
6432 @var{internal}, @var{temporary} and @var{qualified} have the same usage as
6433 explained previously.
6436 The available types are represented by constants defined in the @code{gdb}
6440 @vindex BP_BREAKPOINT
6441 @item gdb.BP_BREAKPOINT
6442 Normal code breakpoint.
6444 @vindex BP_HARDWARE_BREAKPOINT
6445 @item gdb.BP_HARDWARE_BREAKPOINT
6446 Hardware assisted code breakpoint.
6448 @vindex BP_WATCHPOINT
6449 @item gdb.BP_WATCHPOINT
6450 Watchpoint breakpoint.
6452 @vindex BP_HARDWARE_WATCHPOINT
6453 @item gdb.BP_HARDWARE_WATCHPOINT
6454 Hardware assisted watchpoint.
6456 @vindex BP_READ_WATCHPOINT
6457 @item gdb.BP_READ_WATCHPOINT
6458 Hardware assisted read watchpoint.
6460 @vindex BP_ACCESS_WATCHPOINT
6461 @item gdb.BP_ACCESS_WATCHPOINT
6462 Hardware assisted access watchpoint.
6464 @vindex BP_CATCHPOINT
6465 @item gdb.BP_CATCHPOINT
6466 Catchpoint. Currently, this type can't be used when creating
6467 @code{gdb.Breakpoint} objects, but will be present in
6468 @code{gdb.Breakpoint} objects reported from
6469 @code{gdb.BreakpointEvent}s (@pxref{Events In Python}).
6472 The available watchpoint types are represented by constants defined in the
6478 Read only watchpoint.
6482 Write only watchpoint.
6486 Read/Write watchpoint.
6489 @defun Breakpoint.stop (self)
6490 The @code{gdb.Breakpoint} class can be sub-classed and, in
6491 particular, you may choose to implement the @code{stop} method.
6492 If this method is defined in a sub-class of @code{gdb.Breakpoint},
6493 it will be called when the inferior reaches any location of a
6494 breakpoint which instantiates that sub-class. If the method returns
6495 @code{True}, the inferior will be stopped at the location of the
6496 breakpoint, otherwise the inferior will continue.
6498 If there are multiple breakpoints at the same location with a
6499 @code{stop} method, each one will be called regardless of the
6500 return status of the previous. This ensures that all @code{stop}
6501 methods have a chance to execute at that location. In this scenario
6502 if one of the methods returns @code{True} but the others return
6503 @code{False}, the inferior will still be stopped.
6505 You should not alter the execution state of the inferior (i.e.@:, step,
6506 next, etc.), alter the current frame context (i.e.@:, change the current
6507 active frame), or alter, add or delete any breakpoint. As a general
6508 rule, you should not alter any data within @value{GDBN} or the inferior
6511 Example @code{stop} implementation:
6514 class MyBreakpoint (gdb.Breakpoint):
6516 inf_val = gdb.parse_and_eval("foo")
6523 @defun Breakpoint.is_valid ()
6524 Return @code{True} if this @code{Breakpoint} object is valid,
6525 @code{False} otherwise. A @code{Breakpoint} object can become invalid
6526 if the user deletes the breakpoint. In this case, the object still
6527 exists, but the underlying breakpoint does not. In the cases of
6528 watchpoint scope, the watchpoint remains valid even if execution of the
6529 inferior leaves the scope of that watchpoint.
6532 @defun Breakpoint.delete ()
6533 Permanently deletes the @value{GDBN} breakpoint. This also
6534 invalidates the Python @code{Breakpoint} object. Any further access
6535 to this object's attributes or methods will raise an error.
6538 @defvar Breakpoint.enabled
6539 This attribute is @code{True} if the breakpoint is enabled, and
6540 @code{False} otherwise. This attribute is writable. You can use it to enable
6541 or disable the breakpoint.
6544 @defvar Breakpoint.silent
6545 This attribute is @code{True} if the breakpoint is silent, and
6546 @code{False} otherwise. This attribute is writable.
6548 Note that a breakpoint can also be silent if it has commands and the
6549 first command is @code{silent}. This is not reported by the
6550 @code{silent} attribute.
6553 @defvar Breakpoint.pending
6554 This attribute is @code{True} if the breakpoint is pending, and
6555 @code{False} otherwise. @xref{Set Breaks}. This attribute is
6559 @anchor{python_breakpoint_thread}
6560 @defvar Breakpoint.thread
6561 If the breakpoint is thread-specific (@pxref{Thread-Specific
6562 Breakpoints}), this attribute holds the thread's global id. If the
6563 breakpoint is not thread-specific, this attribute is @code{None}.
6564 This attribute is writable.
6566 Only one of @code{Breakpoint.thread} or @code{Breakpoint.inferior} can
6567 be set to a valid id at any time, that is, a breakpoint can be thread
6568 specific, or inferior specific, but not both.
6571 @anchor{python_breakpoint_inferior}
6572 @defvar Breakpoint.inferior
6573 If the breakpoint is inferior-specific (@pxref{Inferior-Specific
6574 Breakpoints}), this attribute holds the inferior's id. If the
6575 breakpoint is not inferior-specific, this attribute is @code{None}.
6577 This attribute can be written for breakpoints of type
6578 @code{gdb.BP_BREAKPOINT} and @code{gdb.BP_HARDWARE_BREAKPOINT}.
6581 @defvar Breakpoint.task
6582 If the breakpoint is Ada task-specific, this attribute holds the Ada task
6583 id. If the breakpoint is not task-specific (or the underlying
6584 language is not Ada), this attribute is @code{None}. This attribute
6588 @defvar Breakpoint.ignore_count
6589 This attribute holds the ignore count for the breakpoint, an integer.
6590 This attribute is writable.
6593 @defvar Breakpoint.number
6594 This attribute holds the breakpoint's number --- the identifier used by
6595 the user to manipulate the breakpoint. This attribute is not writable.
6598 @defvar Breakpoint.type
6599 This attribute holds the breakpoint's type --- the identifier used to
6600 determine the actual breakpoint type or use-case. This attribute is not
6604 @defvar Breakpoint.visible
6605 This attribute tells whether the breakpoint is visible to the user
6606 when set, or when the @samp{info breakpoints} command is run. This
6607 attribute is not writable.
6610 @defvar Breakpoint.temporary
6611 This attribute indicates whether the breakpoint was created as a
6612 temporary breakpoint. Temporary breakpoints are automatically deleted
6613 after that breakpoint has been hit. Access to this attribute, and all
6614 other attributes and functions other than the @code{is_valid}
6615 function, will result in an error after the breakpoint has been hit
6616 (as it has been automatically deleted). This attribute is not
6620 @defvar Breakpoint.hit_count
6621 This attribute holds the hit count for the breakpoint, an integer.
6622 This attribute is writable, but currently it can only be set to zero.
6625 @defvar Breakpoint.location
6626 This attribute holds the location of the breakpoint, as specified by
6627 the user. It is a string. If the breakpoint does not have a location
6628 (that is, it is a watchpoint) the attribute's value is @code{None}. This
6629 attribute is not writable.
6632 @defvar Breakpoint.locations
6633 Get the most current list of breakpoint locations that are inserted for this
6634 breakpoint, with elements of type @code{gdb.BreakpointLocation}
6635 (described below). This functionality matches that of the
6636 @code{info breakpoint} command (@pxref{Set Breaks}), in that it only retrieves
6637 the most current list of locations, thus the list itself when returned is
6638 not updated behind the scenes. This attribute is not writable.
6641 @defvar Breakpoint.expression
6642 This attribute holds a breakpoint expression, as specified by
6643 the user. It is a string. If the breakpoint does not have an
6644 expression (the breakpoint is not a watchpoint) the attribute's value
6645 is @code{None}. This attribute is not writable.
6648 @defvar Breakpoint.condition
6649 This attribute holds the condition of the breakpoint, as specified by
6650 the user. It is a string. If there is no condition, this attribute's
6651 value is @code{None}. This attribute is writable.
6654 @defvar Breakpoint.commands
6655 This attribute holds the commands attached to the breakpoint. If
6656 there are commands, this attribute's value is a string holding all the
6657 commands, separated by newlines. If there are no commands, this
6658 attribute is @code{None}. This attribute is writable.
6661 @subheading Breakpoint Locations
6663 A breakpoint location is one of the actual places where a breakpoint has been
6664 set, represented in the Python API by the @code{gdb.BreakpointLocation}
6665 type. This type is never instantiated by the user directly, but is retrieved
6666 from @code{Breakpoint.locations} which returns a list of breakpoint
6667 locations where it is currently set. Breakpoint locations can become
6668 invalid if new symbol files are loaded or dynamically loaded libraries are
6669 closed. Accessing the attributes of an invalidated breakpoint location will
6670 throw a @code{RuntimeError} exception. Access the @code{Breakpoint.locations}
6671 attribute again to retrieve the new and valid breakpoints location list.
6673 @defvar BreakpointLocation.source
6674 This attribute returns the source file path and line number where this location
6675 was set. The type of the attribute is a tuple of @var{string} and
6676 @var{long}. If the breakpoint location doesn't have a source location,
6677 it returns None, which is the case for watchpoints and catchpoints.
6678 This will throw a @code{RuntimeError} exception if the location
6679 has been invalidated. This attribute is not writable.
6682 @defvar BreakpointLocation.address
6683 This attribute returns the address where this location was set.
6684 This attribute is of type long. This will throw a @code{RuntimeError}
6685 exception if the location has been invalidated. This attribute is
6689 @defvar BreakpointLocation.enabled
6690 This attribute holds the value for whether or not this location is enabled.
6691 This attribute is writable (boolean). This will throw a @code{RuntimeError}
6692 exception if the location has been invalidated.
6695 @defvar BreakpointLocation.owner
6696 This attribute holds a reference to the @code{gdb.Breakpoint} owner object,
6697 from which this @code{gdb.BreakpointLocation} was retrieved from.
6698 This will throw a @code{RuntimeError} exception if the location has been
6699 invalidated. This attribute is not writable.
6702 @defvar BreakpointLocation.function
6703 This attribute gets the name of the function where this location was set.
6704 If no function could be found this attribute returns @code{None}.
6705 This will throw a @code{RuntimeError} exception if the location has
6706 been invalidated. This attribute is not writable.
6709 @defvar BreakpointLocation.fullname
6710 This attribute gets the full name of where this location was set. If no
6711 full name could be found, this attribute returns @code{None}.
6712 This will throw a @code{RuntimeError} exception if the location has
6713 been invalidated. This attribute is not writable.
6716 @defvar BreakpointLocation.thread_groups
6717 This attribute gets the thread groups it was set in. It returns a @code{List}
6718 of the thread group ID's. This will throw a @code{RuntimeError}
6719 exception if the location has been invalidated. This attribute
6723 @node Finish Breakpoints in Python
6724 @subsubsection Finish Breakpoints
6726 @cindex python finish breakpoints
6727 @tindex gdb.FinishBreakpoint
6729 A finish breakpoint is a temporary breakpoint set at the return address of
6730 a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
6731 extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
6732 and deleted when the execution will run out of the breakpoint scope (i.e.@:
6733 @code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
6734 Finish breakpoints are thread specific and must be create with the right
6737 @defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
6738 Create a finish breakpoint at the return address of the @code{gdb.Frame}
6739 object @var{frame}. If @var{frame} is not provided, this defaults to the
6740 newest frame. The optional @var{internal} argument allows the breakpoint to
6741 become invisible to the user. @xref{Breakpoints In Python}, for further
6742 details about this argument.
6745 @defun FinishBreakpoint.out_of_scope (self)
6746 In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
6747 @code{return} command, @dots{}), a function may not properly terminate, and
6748 thus never hit the finish breakpoint. When @value{GDBN} notices such a
6749 situation, the @code{out_of_scope} callback will be triggered.
6751 You may want to sub-class @code{gdb.FinishBreakpoint} and override this
6755 class MyFinishBreakpoint (gdb.FinishBreakpoint)
6757 print ("normal finish")
6760 def out_of_scope ():
6761 print ("abnormal finish")
6765 @defvar FinishBreakpoint.return_value
6766 When @value{GDBN} is stopped at a finish breakpoint and the frame
6767 used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
6768 attribute will contain a @code{gdb.Value} object corresponding to the return
6769 value of the function. The value will be @code{None} if the function return
6770 type is @code{void} or if the return value was not computable. This attribute
6774 @node Lazy Strings In Python
6775 @subsubsection Python representation of lazy strings
6777 @cindex lazy strings in python
6778 @tindex gdb.LazyString
6780 A @dfn{lazy string} is a string whose contents is not retrieved or
6781 encoded until it is needed.
6783 A @code{gdb.LazyString} is represented in @value{GDBN} as an
6784 @code{address} that points to a region of memory, an @code{encoding}
6785 that will be used to encode that region of memory, and a @code{length}
6786 to delimit the region of memory that represents the string. The
6787 difference between a @code{gdb.LazyString} and a string wrapped within
6788 a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
6789 differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
6790 retrieved and encoded during printing, while a @code{gdb.Value}
6791 wrapping a string is immediately retrieved and encoded on creation.
6793 A @code{gdb.LazyString} object has the following functions:
6795 @defun LazyString.value ()
6796 Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
6797 will point to the string in memory, but will lose all the delayed
6798 retrieval, encoding and handling that @value{GDBN} applies to a
6799 @code{gdb.LazyString}.
6802 @defvar LazyString.address
6803 This attribute holds the address of the string. This attribute is not
6807 @defvar LazyString.length
6808 This attribute holds the length of the string in characters. If the
6809 length is -1, then the string will be fetched and encoded up to the
6810 first null of appropriate width. This attribute is not writable.
6813 @defvar LazyString.encoding
6814 This attribute holds the encoding that will be applied to the string
6815 when the string is printed by @value{GDBN}. If the encoding is not
6816 set, or contains an empty string, then @value{GDBN} will select the
6817 most appropriate encoding when the string is printed. This attribute
6821 @defvar LazyString.type
6822 This attribute holds the type that is represented by the lazy string's
6823 type. For a lazy string this is a pointer or array type. To
6824 resolve this to the lazy string's character type, use the type's
6825 @code{target} method. @xref{Types In Python}. This attribute is not
6829 @node Architectures In Python
6830 @subsubsection Python representation of architectures
6831 @cindex Python architectures
6833 @value{GDBN} uses architecture specific parameters and artifacts in a
6834 number of its various computations. An architecture is represented
6835 by an instance of the @code{gdb.Architecture} class.
6837 A @code{gdb.Architecture} class has the following methods:
6839 @anchor{gdbpy_architecture_name}
6840 @defun Architecture.name ()
6841 Return the name (string value) of the architecture.
6844 @defun Architecture.disassemble (start_pc @r{[}, end_pc @r{[}, count@r{]]})
6845 Return a list of disassembled instructions starting from the memory
6846 address @var{start_pc}. The optional arguments @var{end_pc} and
6847 @var{count} determine the number of instructions in the returned list.
6848 If both the optional arguments @var{end_pc} and @var{count} are
6849 specified, then a list of at most @var{count} disassembled instructions
6850 whose start address falls in the closed memory address interval from
6851 @var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
6852 specified, but @var{count} is specified, then @var{count} number of
6853 instructions starting from the address @var{start_pc} are returned. If
6854 @var{count} is not specified but @var{end_pc} is specified, then all
6855 instructions whose start address falls in the closed memory address
6856 interval from @var{start_pc} to @var{end_pc} are returned. If neither
6857 @var{end_pc} nor @var{count} are specified, then a single instruction at
6858 @var{start_pc} is returned. For all of these cases, each element of the
6859 returned list is a Python @code{dict} with the following string keys:
6864 The value corresponding to this key is a Python long integer capturing
6865 the memory address of the instruction.
6868 The value corresponding to this key is a string value which represents
6869 the instruction with assembly language mnemonics. The assembly
6870 language flavor used is the same as that specified by the current CLI
6871 variable @code{disassembly-flavor}. @xref{Machine Code}.
6874 The value corresponding to this key is the length (integer value) of the
6875 instruction in bytes.
6880 @defun Architecture.integer_type (size @r{[}, signed@r{]})
6881 This function looks up an integer type by its @var{size}, and
6882 optionally whether or not it is signed.
6884 @var{size} is the size, in bits, of the desired integer type. Only
6885 certain sizes are currently supported: 0, 8, 16, 24, 32, 64, and 128.
6887 If @var{signed} is not specified, it defaults to @code{True}. If
6888 @var{signed} is @code{False}, the returned type will be unsigned.
6890 If the indicated type cannot be found, this function will throw a
6891 @code{ValueError} exception.
6894 @anchor{gdbpy_architecture_registers}
6895 @defun Architecture.registers (@r{[} reggroup @r{]})
6896 Return a @code{gdb.RegisterDescriptorIterator} (@pxref{Registers In
6897 Python}) for all of the registers in @var{reggroup}, a string that is
6898 the name of a register group. If @var{reggroup} is omitted, or is the
6899 empty string, then the register group @samp{all} is assumed.
6902 @anchor{gdbpy_architecture_reggroups}
6903 @defun Architecture.register_groups ()
6904 Return a @code{gdb.RegisterGroupsIterator} (@pxref{Registers In
6905 Python}) for all of the register groups available for the
6906 @code{gdb.Architecture}.
6909 @node Registers In Python
6910 @subsubsection Registers In Python
6911 @cindex Registers In Python
6913 Python code can request from a @code{gdb.Architecture} information
6914 about the set of registers available
6915 (@pxref{gdbpy_architecture_registers,,@code{Architecture.registers}}).
6916 The register information is returned as a
6917 @code{gdb.RegisterDescriptorIterator}, which is an iterator that in
6918 turn returns @code{gdb.RegisterDescriptor} objects.
6920 A @code{gdb.RegisterDescriptor} does not provide the value of a
6921 register (@pxref{gdbpy_frame_read_register,,@code{Frame.read_register}}
6922 for reading a register's value), instead the @code{RegisterDescriptor}
6923 is a way to discover which registers are available for a particular
6926 A @code{gdb.RegisterDescriptor} has the following read-only properties:
6928 @defvar RegisterDescriptor.name
6929 The name of this register.
6932 It is also possible to lookup a register descriptor based on its name
6933 using the following @code{gdb.RegisterDescriptorIterator} function:
6935 @defun RegisterDescriptorIterator.find (name)
6936 Takes @var{name} as an argument, which must be a string, and returns a
6937 @code{gdb.RegisterDescriptor} for the register with that name, or
6938 @code{None} if there is no register with that name.
6941 Python code can also request from a @code{gdb.Architecture}
6942 information about the set of register groups available on a given
6944 (@pxref{gdbpy_architecture_reggroups,,@code{Architecture.register_groups}}).
6946 Every register can be a member of zero or more register groups. Some
6947 register groups are used internally within @value{GDBN} to control
6948 things like which registers must be saved when calling into the
6949 program being debugged (@pxref{Calling,,Calling Program Functions}).
6950 Other register groups exist to allow users to easily see related sets
6951 of registers in commands like @code{info registers}
6952 (@pxref{info_registers_reggroup,,@code{info registers
6955 The register groups information is returned as a
6956 @code{gdb.RegisterGroupsIterator}, which is an iterator that in turn
6957 returns @code{gdb.RegisterGroup} objects.
6959 A @code{gdb.RegisterGroup} object has the following read-only
6962 @defvar RegisterGroup.name
6963 A string that is the name of this register group.
6966 @node Connections In Python
6967 @subsubsection Connections In Python
6968 @cindex connections in python
6969 @value{GDBN} lets you run and debug multiple programs in a single
6970 session. Each program being debugged has a connection, the connection
6971 describes how @value{GDBN} controls the program being debugged.
6972 Examples of different connection types are @samp{native} and
6973 @samp{remote}. @xref{Inferiors Connections and Programs}.
6975 Connections in @value{GDBN} are represented as instances of
6976 @code{gdb.TargetConnection}, or as one of its sub-classes. To get a
6977 list of all connections use @code{gdb.connections}
6978 (@pxref{gdbpy_connections,,gdb.connections}).
6980 To get the connection for a single @code{gdb.Inferior} read its
6981 @code{gdb.Inferior.connection} attribute
6982 (@pxref{gdbpy_inferior_connection,,gdb.Inferior.connection}).
6984 Currently there is only a single sub-class of
6985 @code{gdb.TargetConnection}, @code{gdb.RemoteTargetConnection},
6986 however, additional sub-classes may be added in future releases of
6987 @value{GDBN}. As a result you should avoid writing code like:
6990 conn = gdb.selected_inferior().connection
6991 if type(conn) is gdb.RemoteTargetConnection:
6992 print("This is a remote target connection")
6996 as this may fail when more connection types are added. Instead, you
7000 conn = gdb.selected_inferior().connection
7001 if isinstance(conn, gdb.RemoteTargetConnection):
7002 print("This is a remote target connection")
7005 A @code{gdb.TargetConnection} has the following method:
7007 @defun TargetConnection.is_valid ()
7008 Return @code{True} if the @code{gdb.TargetConnection} object is valid,
7009 @code{False} if not. A @code{gdb.TargetConnection} will become
7010 invalid if the connection no longer exists within @value{GDBN}, this
7011 might happen when no inferiors are using the connection, but could be
7012 delayed until the user replaces the current target.
7014 Reading any of the @code{gdb.TargetConnection} properties will throw
7015 an exception if the connection is invalid.
7018 A @code{gdb.TargetConnection} has the following read-only properties:
7020 @defvar TargetConnection.num
7021 An integer assigned by @value{GDBN} to uniquely identify this
7022 connection. This is the same value as displayed in the @samp{Num}
7023 column of the @code{info connections} command output (@pxref{Inferiors
7024 Connections and Programs,,info connections}).
7027 @defvar TargetConnection.type
7028 A string that describes what type of connection this is. This string
7029 will be one of the valid names that can be passed to the @code{target}
7030 command (@pxref{Target Commands,,target command}).
7033 @defvar TargetConnection.description
7034 A string that gives a short description of this target type. This is
7035 the same string that is displayed in the @samp{Description} column of
7036 the @code{info connection} command output (@pxref{Inferiors
7037 Connections and Programs,,info connections}).
7040 @defvar TargetConnection.details
7041 An optional string that gives additional information about this
7042 connection. This attribute can be @code{None} if there are no
7043 additional details for this connection.
7045 An example of a connection type that might have additional details is
7046 the @samp{remote} connection, in this case the details string can
7047 contain the @samp{@var{hostname}:@var{port}} that was used to connect
7048 to the remote target.
7051 The @code{gdb.RemoteTargetConnection} class is a sub-class of
7052 @code{gdb.TargetConnection}, and is used to represent @samp{remote}
7053 and @samp{extended-remote} connections. In addition to the attributes
7054 and methods available from the @code{gdb.TargetConnection} base class,
7055 a @code{gdb.RemoteTargetConnection} has the following method:
7057 @kindex maint packet
7058 @defun RemoteTargetConnection.send_packet (packet)
7059 This method sends @var{packet} to the remote target and returns the
7060 response. The @var{packet} should either be a @code{bytes} object, or
7061 a @code{Unicode} string.
7063 If @var{packet} is a @code{Unicode} string, then the string is encoded
7064 to a @code{bytes} object using the @sc{ascii} codec. If the string
7065 can't be encoded then an @code{UnicodeError} is raised.
7067 If @var{packet} is not a @code{bytes} object, or a @code{Unicode}
7068 string, then a @code{TypeError} is raised. If @var{packet} is empty
7069 then a @code{ValueError} is raised.
7071 The response is returned as a @code{bytes} object. If it is known
7072 that the response can be represented as a string then this can be
7073 decoded from the buffer. For example, if it is known that the
7074 response is an @sc{ascii} string:
7077 remote_connection.send_packet("some_packet").decode("ascii")
7080 The prefix, suffix, and checksum (as required by the remote serial
7081 protocol) are automatically added to the outgoing packet, and removed
7082 from the incoming packet before the contents of the reply are
7085 This is equivalent to the @code{maintenance packet} command
7086 (@pxref{maint packet}).
7089 @node TUI Windows In Python
7090 @subsubsection Implementing new TUI windows
7091 @cindex Python TUI Windows
7093 New TUI (@pxref{TUI}) windows can be implemented in Python.
7095 @defun gdb.register_window_type (name, factory)
7096 Because TUI windows are created and destroyed depending on the layout
7097 the user chooses, new window types are implemented by registering a
7098 factory function with @value{GDBN}.
7100 @var{name} is the name of the new window. It's an error to try to
7101 replace one of the built-in windows, but other window types can be
7102 replaced. The @var{name} should match the regular expression
7103 @code{[a-zA-Z][-_.a-zA-Z0-9]*}, it is an error to try and create a
7104 window with an invalid name.
7106 @var{function} is a factory function that is called to create the TUI
7107 window. This is called with a single argument of type
7108 @code{gdb.TuiWindow}, described below. It should return an object
7109 that implements the TUI window protocol, also described below.
7112 As mentioned above, when a factory function is called, it is passed
7113 an object of type @code{gdb.TuiWindow}. This object has these
7114 methods and attributes:
7116 @defun TuiWindow.is_valid ()
7117 This method returns @code{True} when this window is valid. When the
7118 user changes the TUI layout, windows no longer visible in the new
7119 layout will be destroyed. At this point, the @code{gdb.TuiWindow}
7120 will no longer be valid, and methods (and attributes) other than
7121 @code{is_valid} will throw an exception.
7123 When the TUI is disabled using @code{tui disable} (@pxref{TUI
7124 Commands,,tui disable}) the window is hidden rather than destroyed,
7125 but @code{is_valid} will still return @code{False} and other methods
7126 (and attributes) will still throw an exception.
7129 @defvar TuiWindow.width
7130 This attribute holds the width of the window. It is not writable.
7133 @defvar TuiWindow.height
7134 This attribute holds the height of the window. It is not writable.
7137 @defvar TuiWindow.title
7138 This attribute holds the window's title, a string. This is normally
7139 displayed above the window. This attribute can be modified.
7142 @defun TuiWindow.erase ()
7143 Remove all the contents of the window.
7146 @defun TuiWindow.write (string @r{[}, full_window@r{]})
7147 Write @var{string} to the window. @var{string} can contain ANSI
7148 terminal escape styling sequences; @value{GDBN} will translate these
7149 as appropriate for the terminal.
7151 If the @var{full_window} parameter is @code{True}, then @var{string}
7152 contains the full contents of the window. This is similar to calling
7153 @code{erase} before @code{write}, but avoids the flickering.
7156 The factory function that you supply should return an object
7157 conforming to the TUI window protocol. These are the method that can
7158 be called on this object, which is referred to below as the ``window
7159 object''. The methods documented below are optional; if the object
7160 does not implement one of these methods, @value{GDBN} will not attempt
7161 to call it. Additional new methods may be added to the window
7162 protocol in the future. @value{GDBN} guarantees that they will begin
7163 with a lower-case letter, so you can start implementation methods with
7164 upper-case letters or underscore to avoid any future conflicts.
7166 @defun Window.close ()
7167 When the TUI window is closed, the @code{gdb.TuiWindow} object will be
7168 put into an invalid state. At this time, @value{GDBN} will call
7169 @code{close} method on the window object.
7171 After this method is called, @value{GDBN} will discard any references
7172 it holds on this window object, and will no longer call methods on
7176 @defun Window.render ()
7177 In some situations, a TUI window can change size. For example, this
7178 can happen if the user resizes the terminal, or changes the layout.
7179 When this happens, @value{GDBN} will call the @code{render} method on
7182 If your window is intended to update in response to changes in the
7183 inferior, you will probably also want to register event listeners and
7184 send output to the @code{gdb.TuiWindow}.
7187 @defun Window.hscroll (num)
7188 This is a request to scroll the window horizontally. @var{num} is the
7189 amount by which to scroll, with negative numbers meaning to scroll
7190 right. In the TUI model, it is the viewport that moves, not the
7191 contents. A positive argument should cause the viewport to move
7192 right, and so the content should appear to move to the left.
7195 @defun Window.vscroll (num)
7196 This is a request to scroll the window vertically. @var{num} is the
7197 amount by which to scroll, with negative numbers meaning to scroll
7198 backward. In the TUI model, it is the viewport that moves, not the
7199 contents. A positive argument should cause the viewport to move down,
7200 and so the content should appear to move up.
7203 @anchor{python-window-click}
7204 @defun Window.click (x, y, button)
7205 This is called on a mouse click in this window. @var{x} and @var{y} are
7206 the mouse coordinates inside the window (0-based, from the top left
7207 corner), and @var{button} specifies which mouse button was used, whose
7208 values can be 1 (left), 2 (middle), or 3 (right).
7210 When TUI mouse events are disabled by turning off the @code{tui mouse-events}
7211 setting (@pxref{tui-mouse-events,,set tui mouse-events}), then @code{click} will
7215 @node Disassembly In Python
7216 @subsubsection Instruction Disassembly In Python
7217 @cindex python instruction disassembly
7219 @value{GDBN}'s builtin disassembler can be extended, or even replaced,
7220 using the Python API. The disassembler related features are contained
7221 within the @code{gdb.disassembler} module:
7223 @anchor{DisassembleInfo Class}
7224 @deftp {class} gdb.disassembler.DisassembleInfo
7225 Disassembly is driven by instances of this class. Each time
7226 @value{GDBN} needs to disassemble an instruction, an instance of this
7227 class is created and passed to a registered disassembler. The
7228 disassembler is then responsible for disassembling an instruction and
7231 Instances of this type are usually created within @value{GDBN},
7232 however, it is possible to create a copy of an instance of this type,
7233 see the description of @code{__init__} for more details.
7235 This class has the following properties and methods:
7237 @defvar DisassembleInfo.address
7238 A read-only integer containing the address at which @value{GDBN}
7239 wishes to disassemble a single instruction.
7242 @defvar DisassembleInfo.architecture
7243 The @code{gdb.Architecture} (@pxref{Architectures In Python}) for
7244 which @value{GDBN} is currently disassembling, this property is
7248 @defvar DisassembleInfo.progspace
7249 The @code{gdb.Progspace} (@pxref{Progspaces In Python,,Program Spaces
7250 In Python}) for which @value{GDBN} is currently disassembling, this
7251 property is read-only.
7254 @defun DisassembleInfo.is_valid ()
7255 Returns @code{True} if the @code{DisassembleInfo} object is valid,
7256 @code{False} if not. A @code{DisassembleInfo} object will become
7257 invalid once the disassembly call for which the @code{DisassembleInfo}
7258 was created, has returned. Calling other @code{DisassembleInfo}
7259 methods, or accessing @code{DisassembleInfo} properties, will raise a
7260 @code{RuntimeError} exception if it is invalid.
7263 @defun DisassembleInfo.__init__ (info)
7264 This can be used to create a new @code{DisassembleInfo} object that is
7265 a copy of @var{info}. The copy will have the same @code{address},
7266 @code{architecture}, and @code{progspace} values as @var{info}, and
7267 will become invalid at the same time as @var{info}.
7269 This method exists so that sub-classes of @code{DisassembleInfo} can
7270 be created, these sub-classes must be initialized as copies of an
7271 existing @code{DisassembleInfo} object, but sub-classes might choose
7272 to override the @code{read_memory} method, and so control what
7273 @value{GDBN} sees when reading from memory
7274 (@pxref{builtin_disassemble}).
7277 @defun DisassembleInfo.read_memory (length, offset)
7278 This method allows the disassembler to read the bytes of the
7279 instruction to be disassembled. The method reads @var{length} bytes,
7280 starting at @var{offset} from
7281 @code{DisassembleInfo.address}.
7283 It is important that the disassembler read the instruction bytes using
7284 this method, rather than reading inferior memory directly, as in some
7285 cases @value{GDBN} disassembles from an internal buffer rather than
7286 directly from inferior memory, calling this method handles this
7289 Returns a buffer object, which behaves much like an array or a string,
7290 just as @code{Inferior.read_memory} does
7291 (@pxref{gdbpy_inferior_read_memory,,Inferior.read_memory}). The
7292 length of the returned buffer will always be exactly @var{length}.
7294 If @value{GDBN} is unable to read the required memory then a
7295 @code{gdb.MemoryError} exception is raised (@pxref{Exception
7298 This method can be overridden by a sub-class in order to control what
7299 @value{GDBN} sees when reading from memory
7300 (@pxref{builtin_disassemble}). When overriding this method it is
7301 important to understand how @code{builtin_disassemble} makes use of
7304 While disassembling a single instruction there could be multiple calls
7305 to this method, and the same bytes might be read multiple times. Any
7306 single call might only read a subset of the total instruction bytes.
7308 If an implementation of @code{read_memory} is unable to read the
7309 requested memory contents, for example, if there's a request to read
7310 from an invalid memory address, then a @code{gdb.MemoryError} should
7313 Raising a @code{MemoryError} inside @code{read_memory} does not
7314 automatically mean a @code{MemoryError} will be raised by
7315 @code{builtin_disassemble}. It is possible the @value{GDBN}'s builtin
7316 disassembler is probing to see how many bytes are available. When
7317 @code{read_memory} raises the @code{MemoryError} the builtin
7318 disassembler might be able to perform a complete disassembly with the
7319 bytes it has available, in this case @code{builtin_disassemble} will
7320 not itself raise a @code{MemoryError}.
7322 Any other exception type raised in @code{read_memory} will propagate
7323 back and be re-raised by @code{builtin_disassemble}.
7326 @defun DisassembleInfo.text_part (style, string)
7327 Create a new @code{DisassemblerTextPart} representing a piece of a
7328 disassembled instruction. @var{string} should be a non-empty string,
7329 and @var{style} should be an appropriate style constant
7330 (@pxref{Disassembler Style Constants}).
7332 Disassembler parts are used when creating a @code{DisassemblerResult}
7333 in order to represent the styling within an instruction
7334 (@pxref{DisassemblerResult Class}).
7337 @defun DisassembleInfo.address_part (address)
7338 Create a new @code{DisassemblerAddressPart}. @var{address} is the
7339 value of the absolute address this part represents. A
7340 @code{DisassemblerAddressPart} is displayed as an absolute address and
7341 an associated symbol, the address and symbol are styled appropriately.
7346 @anchor{Disassembler Class}
7347 @deftp {class} gdb.disassembler.Disassembler
7348 This is a base class from which all user implemented disassemblers
7351 @defun Disassembler.__init__ (name)
7352 The constructor takes @var{name}, a string, which should be a short
7353 name for this disassembler.
7356 @defun Disassembler.__call__ (info)
7357 The @code{__call__} method must be overridden by sub-classes to
7358 perform disassembly. Calling @code{__call__} on this base class will
7359 raise a @code{NotImplementedError} exception.
7361 The @var{info} argument is an instance of @code{DisassembleInfo}, and
7362 describes the instruction that @value{GDBN} wants disassembling.
7364 If this function returns @code{None}, this indicates to @value{GDBN}
7365 that this sub-class doesn't wish to disassemble the requested
7366 instruction. @value{GDBN} will then use its builtin disassembler to
7367 perform the disassembly.
7369 Alternatively, this function can return a @code{DisassemblerResult}
7370 that represents the disassembled instruction, this type is described
7371 in more detail below.
7373 The @code{__call__} method can raise a @code{gdb.MemoryError}
7374 exception (@pxref{Exception Handling}) to indicate to @value{GDBN}
7375 that there was a problem accessing the required memory, this will then
7376 be displayed by @value{GDBN} within the disassembler output.
7378 Ideally, the only three outcomes from invoking @code{__call__} would
7379 be a return of @code{None}, a successful disassembly returned in a
7380 @code{DisassemblerResult}, or a @code{MemoryError} indicating that
7381 there was a problem reading memory.
7383 However, as an implementation of @code{__call__} could fail due to
7384 other reasons, e.g.@: some external resource required to perform
7385 disassembly is temporarily unavailable, then, if @code{__call__}
7386 raises a @code{GdbError}, the exception will be converted to a string
7387 and printed at the end of the disassembly output, the disassembly
7388 request will then stop.
7390 Any other exception type raised by the @code{__call__} method is
7391 considered an error in the user code, the exception will be printed to
7392 the error stream according to the @kbd{set python print-stack} setting
7393 (@pxref{set_python_print_stack,,@kbd{set python print-stack}}).
7397 @anchor{DisassemblerResult Class}
7398 @deftp {class} gdb.disassembler.DisassemblerResult
7399 This class represents the result of disassembling a single
7400 instruction. An instance of this class will be returned from
7401 @code{builtin_disassemble} (@pxref{builtin_disassemble}), and an
7402 instance of this class should be returned from
7403 @w{@code{Disassembler.__call__}} (@pxref{Disassembler Class}) if an
7404 instruction was successfully disassembled.
7406 It is not possible to sub-class the @code{DisassemblerResult} class.
7408 The @code{DisassemblerResult} class has the following properties and
7411 @defun DisassemblerResult.__init__ (length, string, parts)
7412 Initialize an instance of this class, @var{length} is the length of
7413 the disassembled instruction in bytes, which must be greater than
7416 Only one of @var{string} or @var{parts} should be used to initialize a
7417 new @code{DisassemblerResult}; the other one should be passed the
7418 value @code{None}. Alternatively, the arguments can be passed by
7419 name, and the unused argument can be ignored.
7421 The @var{string} argument, if not @code{None}, is a non-empty string
7422 that represents the entire disassembled instruction. Building a result
7423 object using the @var{string} argument does not allow for any styling
7424 information to be included in the result. @value{GDBN} will style the
7425 result as a single @code{DisassemblerTextPart} with @code{STYLE_TEXT}
7426 style (@pxref{Disassembler Styling Parts}).
7428 The @var{parts} argument, if not @code{None}, is a non-empty sequence
7429 of @code{DisassemblerPart} objects. Each part represents a small part
7430 of the disassembled instruction along with associated styling
7431 information. A result object built using @var{parts} can be displayed
7432 by @value{GDBN} with full styling information
7433 (@pxref{style_disassembler_enabled,,@kbd{set style disassembler
7437 @defvar DisassemblerResult.length
7438 A read-only property containing the length of the disassembled
7439 instruction in bytes, this will always be greater than zero.
7442 @defvar DisassemblerResult.string
7443 A read-only property containing a non-empty string representing the
7444 disassembled instruction. The @var{string} is a representation of the
7445 disassembled instruction without any styling information. To see how
7446 the instruction will be styled use the @var{parts} property.
7448 If this instance was initialized using separate
7449 @code{DisassemblerPart} objects, the @var{string} property will still
7450 be valid. The @var{string} value is created by concatenating the
7451 @code{DisassemblerPart.string} values of each component part
7452 (@pxref{Disassembler Styling Parts}).
7455 @defvar DisassemblerResult.parts
7456 A read-only property containing a non-empty sequence of
7457 @code{DisassemblerPart} objects. Each @code{DisassemblerPart} object
7458 contains a small part of the instruction along with information about
7459 how that part should be styled. @value{GDBN} uses this information to
7460 create styled disassembler output
7461 (@pxref{style_disassembler_enabled,,@kbd{set style disassembler
7464 If this instance was initialized using a single string rather than
7465 with a sequence of @code{DisassemblerPart} objects, the @var{parts}
7466 property will still be valid. In this case the @var{parts} property
7467 will hold a sequence containing a single @code{DisassemblerTextPart}
7468 object, the string of which will represent the entire instruction, and
7469 the style of which will be @code{STYLE_TEXT}.
7473 @anchor{Disassembler Styling Parts}
7474 @deftp {class} gdb.disassembler.DisassemblerPart
7475 This is a parent class from which the different part sub-classes
7476 inherit. Only instances of the sub-classes detailed below will be
7477 returned by the Python API.
7479 It is not possible to directly create instances of either this parent
7480 class, or any of the sub-classes listed below. Instances of the
7481 sub-classes listed below are created by calling
7482 @code{builtin_disassemble} (@pxref{builtin_disassemble}) and are
7483 returned within the @code{DisassemblerResult} object, or can be
7484 created by calling the @code{text_part} and @code{address_part}
7485 methods on the @code{DisassembleInfo} class (@pxref{DisassembleInfo
7488 The @code{DisassemblerPart} class has a single property:
7490 @defvar DisassemblerPart.string
7491 A read-only property that contains a non-empty string representing
7492 this part of the disassembled instruction. The string within this
7493 property doesn't include any styling information.
7497 @deftp {class} gdb.disassembler.DisassemblerTextPart
7498 The @code{DisassemblerTextPart} class represents a piece of the
7499 disassembled instruction and the associated style for that piece.
7500 Instances of this class can't be created directly, instead call
7501 @code{DisassembleInfo.text_part} to create a new instance of this
7502 class (@pxref{DisassembleInfo Class}).
7504 As well as the properties of its parent class, the
7505 @code{DisassemblerTextPart} has the following additional property:
7507 @defvar DisassemblerTextPart.style
7508 A read-only property that contains one of the defined style constants.
7509 @value{GDBN} will use this style when styling this part of the
7510 disassembled instruction (@pxref{Disassembler Style Constants}).
7514 @deftp {class} gdb.disassembler.DisassemblerAddressPart
7515 The @code{DisassemblerAddressPart} class represents an absolute
7516 address within a disassembled instruction. Using a
7517 @code{DisassemblerAddressPart} instead of a
7518 @code{DisassemblerTextPart} with @code{STYLE_ADDRESS} is preferred,
7519 @value{GDBN} will display the address as both an absolute address, and
7520 will look up a suitable symbol to display next to the address. Using
7521 @code{DisassemblerAddressPart} also ensures that user settings such as
7522 @code{set print max-symbolic-offset} are respected.
7524 Here is an example of an x86-64 instruction:
7531 In this instruction the @code{0x401136 <foo>} was generated from a
7532 single @code{DisassemblerAddressPart}. The @code{0x401136} will be
7533 styled with @code{STYLE_ADDRESS}, and @code{foo} will be styled with
7534 @code{STYLE_SYMBOL}. The @code{<} and @code{>} will be styled as
7537 If the inclusion of the symbol name is not required then a
7538 @code{DisassemblerTextPart} with style @code{STYLE_ADDRESS} can be
7541 Instances of this class can't be created directly, instead call
7542 @code{DisassembleInfo.address_part} to create a new instance of this
7543 class (@pxref{DisassembleInfo Class}).
7545 As well as the properties of its parent class, the
7546 @code{DisassemblerAddressPart} has the following additional property:
7548 @defvar DisassemblerAddressPart.address
7549 A read-only property that contains the @var{address} passed to this
7550 object's @code{__init__} method.
7554 @anchor{Disassembler Style Constants}
7556 The following table lists all of the disassembler styles that are
7557 available. @value{GDBN} maps these style constants onto its style
7558 settings (@pxref{Output Styling}). In some cases, several style
7559 constants produce the same style settings, and thus will produce the
7560 same visual effect on the screen. This could change in future
7561 releases of @value{GDBN}, so care should be taken to select the
7562 correct style constant to ensure correct output styling in future
7563 releases of @value{GDBN}.
7567 @item gdb.disassembler.STYLE_TEXT
7568 This is the default style used by @value{GDBN} when styling
7569 disassembler output. This style should be used for any parts of the
7570 instruction that don't fit any of the other styles listed below.
7571 @value{GDBN} styles text with this style using its default style.
7573 @vindex STYLE_MNEMONIC
7574 @item gdb.disassembler.STYLE_MNEMONIC
7575 This style is used for styling the primary instruction mnemonic, which
7576 usually appears at, or near, the start of the disassembled instruction
7579 @value{GDBN} styles text with this style using the @code{disassembler
7580 mnemonic} style setting.
7582 @vindex STYLE_SUB_MNEMONIC
7583 @item gdb.disassembler.STYLE_SUB_MNEMONIC
7584 This style is used for styling any sub-mnemonics within a disassembled
7585 instruction. A sub-mnemonic is any text within the instruction that
7586 controls the function of the instruction, but which is disjoint from
7587 the primary mnemonic (which will have styled @code{STYLE_MNEMONIC}).
7589 As an example, consider this AArch64 instruction:
7592 add w16, w7, w1, lsl #1
7596 The @code{add} is the primary instruction mnemonic, and would be given
7597 style @code{STYLE_MNEMONIC}, while @code{lsl} is the sub-mnemonic, and
7598 would be given the style @code{STYLE_SUB_MNEMONIC}.
7600 @value{GDBN} styles text with this style using the @code{disassembler
7601 mnemonic} style setting.
7603 @vindex STYLE_ASSEMBLER_DIRECTIVE
7604 @item gdb.disassembler.STYLE_ASSEMBLER_DIRECTIVE
7605 Sometimes a series of bytes doesn't decode to a valid instruction. In
7606 this case the disassembler may choose to represent the result of
7607 disassembling using an assembler directive, for example:
7614 In this case, the @code{.word} would be give the
7615 @code{STYLE_ASSEMBLER_DIRECTIVE} style. An assembler directive is
7616 similar to a mnemonic in many ways but is something that is not part
7617 of the architecture's instruction set.
7619 @value{GDBN} styles text with this style using the @code{disassembler
7620 mnemonic} style setting.
7622 @vindex STYLE_REGISTER
7623 @item gdb.disassembler.STYLE_REGISTER
7624 This style is used for styling any text that represents a register
7625 name, or register number, within a disassembled instruction.
7627 @value{GDBN} styles text with this style using the @code{disassembler
7628 register} style setting.
7630 @vindex STYLE_ADDRESS
7631 @item gdb.disassembler.STYLE_ADDRESS
7632 This style is used for styling numerical values that represent
7633 absolute addresses within the disassembled instruction.
7635 When creating a @code{DisassemblerTextPart} with this style, you
7636 should consider if a @code{DisassemblerAddressPart} would be more
7637 appropriate. See @ref{Disassembler Styling Parts} for a description
7638 of what each part offers.
7640 @value{GDBN} styles text with this style using the @code{disassembler
7641 address} style setting.
7643 @vindex STYLE_ADDRESS_OFFSET
7644 @item gdb.disassembler.STYLE_ADDRESS_OFFSET
7645 This style is used for styling numerical values that represent offsets
7646 to addresses within the disassembled instruction. A value is
7647 considered an address offset when the instruction itself is going to
7648 access memory, and the value is being used to offset which address is
7651 For example, an architecture might have an instruction that loads from
7652 memory using an address within a register. If that instruction also
7653 allowed for an immediate offset to be encoded into the instruction,
7654 this would be an address offset. Similarly, a branch instruction
7655 might jump to an address in a register plus an address offset that is
7656 encoded into the instruction.
7658 @value{GDBN} styles text with this style using the @code{disassembler
7659 immediate} style setting.
7661 @vindex STYLE_IMMEDIATE
7662 @item gdb.disassembler.STYLE_IMMEDIATE
7663 Use @code{STYLE_IMMEDIATE} for any numerical values within a
7664 disassembled instruction when those values are not addresses, address
7665 offsets, or register numbers (The styles @code{STYLE_ADDRESS},
7666 @code{STYLE_ADDRESS_OFFSET}, or @code{STYLE_REGISTER} can be used in
7669 @value{GDBN} styles text with this style using the @code{disassembler
7670 immediate} style setting.
7672 @vindex STYLE_SYMBOL
7673 @item gdb.disassembler.STYLE_SYMBOL
7674 This style is used for styling the textual name of a symbol that is
7675 included within a disassembled instruction. A symbol name is often
7676 included next to an absolute address within a disassembled instruction
7677 to make it easier for the user to understand what the address is
7678 referring too. For example:
7685 Here @code{foo} is the name of a symbol, and should be given the
7686 @code{STYLE_SYMBOL} style.
7688 Adding symbols next to absolute addresses like this is handled
7689 automatically by the @code{DisassemblerAddressPart} class
7690 (@pxref{Disassembler Styling Parts}).
7692 @value{GDBN} styles text with this style using the @code{disassembler
7693 symbol} style setting.
7695 @vindex STYLE_COMMENT_START
7696 @item gdb.disassembler.STYLE_COMMENT_START
7697 This style is used to start a line comment in the disassembly output.
7698 Unlike other styles, which only apply to the single
7699 @code{DisassemblerTextPiece} to which they are applied, the comment
7700 style is sticky, and overrides the style of any further pieces within
7703 This means that, after a @code{STYLE_COMMENT_START} piece has been
7704 seen, @value{GDBN} will apply the comment style until the end of the
7705 line, ignoring the specific style within a piece.
7707 @value{GDBN} styles text with this style using the @code{disassembler
7708 comment} style setting.
7711 The following functions are also contained in the
7712 @code{gdb.disassembler} module:
7714 @defun register_disassembler (disassembler, architecture)
7715 The @var{disassembler} must be a sub-class of
7716 @code{gdb.disassembler.Disassembler} or @code{None}.
7718 The optional @var{architecture} is either a string, or the value
7719 @code{None}. If it is a string, then it should be the name of an
7720 architecture known to @value{GDBN}, as returned either from
7721 @code{gdb.Architecture.name}
7722 (@pxref{gdbpy_architecture_name,,gdb.Architecture.name}), or from
7723 @code{gdb.architecture_names}
7724 (@pxref{gdb_architecture_names,,gdb.architecture_names}).
7726 The @var{disassembler} will be installed for the architecture named by
7727 @var{architecture}, or if @var{architecture} is @code{None}, then
7728 @var{disassembler} will be installed as a global disassembler for use
7729 by all architectures.
7731 @cindex disassembler in Python, global vs.@: specific
7732 @cindex search order for disassembler in Python
7733 @cindex look up of disassembler in Python
7734 @value{GDBN} only records a single disassembler for each architecture,
7735 and a single global disassembler. Calling
7736 @code{register_disassembler} for an architecture, or for the global
7737 disassembler, will replace any existing disassembler registered for
7738 that @var{architecture} value. The previous disassembler is returned.
7740 If @var{disassembler} is @code{None} then any disassembler currently
7741 registered for @var{architecture} is deregistered and returned.
7743 When @value{GDBN} is looking for a disassembler to use, @value{GDBN}
7744 first looks for an architecture specific disassembler. If none has
7745 been registered then @value{GDBN} looks for a global disassembler (one
7746 registered with @var{architecture} set to @code{None}). Only one
7747 disassembler is called to perform disassembly, so, if there is both an
7748 architecture specific disassembler, and a global disassembler
7749 registered, it is the architecture specific disassembler that will be
7752 @value{GDBN} tracks the architecture specific, and global
7753 disassemblers separately, so it doesn't matter in which order
7754 disassemblers are created or registered; an architecture specific
7755 disassembler, if present, will always be used in preference to a
7756 global disassembler.
7758 You can use the @kbd{maint info python-disassemblers} command
7759 (@pxref{maint info python-disassemblers}) to see which disassemblers
7760 have been registered.
7763 @anchor{builtin_disassemble}
7764 @defun builtin_disassemble (info)
7765 This function calls back into @value{GDBN}'s builtin disassembler to
7766 disassemble the instruction identified by @var{info}, an instance, or
7767 sub-class, of @code{DisassembleInfo}.
7769 When the builtin disassembler needs to read memory the
7770 @code{read_memory} method on @var{info} will be called. By
7771 sub-classing @code{DisassembleInfo} and overriding the
7772 @code{read_memory} method, it is possible to intercept calls to
7773 @code{read_memory} from the builtin disassembler, and to modify the
7776 It is important to understand that, even when
7777 @code{DisassembleInfo.read_memory} raises a @code{gdb.MemoryError}, it
7778 is the internal disassembler itself that reports the memory error to
7779 @value{GDBN}. The reason for this is that the disassembler might
7780 probe memory to see if a byte is readable or not; if the byte can't be
7781 read then the disassembler may choose not to report an error, but
7782 instead to disassemble the bytes that it does have available.
7784 If the builtin disassembler is successful then an instance of
7785 @code{DisassemblerResult} is returned from @code{builtin_disassemble},
7786 alternatively, if something goes wrong, an exception will be raised.
7788 A @code{MemoryError} will be raised if @code{builtin_disassemble} is
7789 unable to read some memory that is required in order to perform
7790 disassembly correctly.
7792 Any exception that is not a @code{MemoryError}, that is raised in a
7793 call to @code{read_memory}, will pass through
7794 @code{builtin_disassemble}, and be visible to the caller.
7796 Finally, there are a few cases where @value{GDBN}'s builtin
7797 disassembler can fail for reasons that are not covered by
7798 @code{MemoryError}. In these cases, a @code{GdbError} will be raised.
7799 The contents of the exception will be a string describing the problem
7800 the disassembler encountered.
7803 Here is an example that registers a global disassembler. The new
7804 disassembler invokes the builtin disassembler, and then adds a
7805 comment, @code{## Comment}, to each line of disassembly output:
7808 class ExampleDisassembler(gdb.disassembler.Disassembler):
7810 super().__init__("ExampleDisassembler")
7812 def __call__(self, info):
7813 result = gdb.disassembler.builtin_disassemble(info)
7814 length = result.length
7815 text = result.string + "\t## Comment"
7816 return gdb.disassembler.DisassemblerResult(length, text)
7818 gdb.disassembler.register_disassembler(ExampleDisassembler())
7821 The following example creates a sub-class of @code{DisassembleInfo} in
7822 order to intercept the @code{read_memory} calls, within
7823 @code{read_memory} any bytes read from memory have the two 4-bit
7824 nibbles swapped around. This isn't a very useful adjustment, but
7825 serves as an example.
7828 class MyInfo(gdb.disassembler.DisassembleInfo):
7829 def __init__(self, info):
7830 super().__init__(info)
7832 def read_memory(self, length, offset):
7833 buffer = super().read_memory(length, offset)
7834 result = bytearray()
7836 v = int.from_bytes(b, 'little')
7837 v = (v << 4) & 0xf0 | (v >> 4)
7839 return memoryview(result)
7841 class NibbleSwapDisassembler(gdb.disassembler.Disassembler):
7843 super().__init__("NibbleSwapDisassembler")
7845 def __call__(self, info):
7847 return gdb.disassembler.builtin_disassemble(info)
7849 gdb.disassembler.register_disassembler(NibbleSwapDisassembler())
7852 @node Missing Debug Info In Python
7853 @subsubsection Missing Debug Info In Python
7854 @cindex python, handle missing debug information
7856 When @value{GDBN} encounters a new objfile (@pxref{Objfiles In
7857 Python}), e.g.@: the primary executable, or any shared libraries used
7858 by the inferior, @value{GDBN} will attempt to load the corresponding
7859 debug information for that objfile. The debug information might be
7860 found within the objfile itself, or within a separate objfile which
7861 @value{GDBN} will automatically locate and load.
7863 Sometimes though, @value{GDBN} might not find any debug information
7864 for an objfile, in this case the debugging experience will be
7867 If @value{GDBN} fails to locate any debug information for a particular
7868 objfile, there is an opportunity for a Python extension to step in. A
7869 Python extension can potentially locate the missing debug information
7870 using some platform- or project-specific steps, and inform
7871 @value{GDBN} of its location. Or a Python extension might provide
7872 some platform- or project-specific advice to the user about how to
7873 obtain the missing debug information.
7875 A missing debug information Python extension consists of a handler
7876 object which has the @code{name} and @code{enabled} attributes, and
7877 implements the @code{__call__} method. When @value{GDBN} encounters
7878 an objfile for which it is unable to find any debug information, it
7879 invokes the @code{__call__} method. Full details of how handlers are
7880 written can be found below.
7882 @subheading The @code{gdb.missing_debug} Module
7884 @value{GDBN} comes with a @code{gdb.missing_debug} module which
7885 contains the following class and global function:
7887 @deftp{class} gdb.missing_debug.MissingDebugHandler
7889 @code{MissingDebugHandler} is a base class from which user-created
7890 handlers can derive, though it is not required that handlers derive
7891 from this class, so long as any user created handler has the
7892 @code{name} and @code{enabled} attributes, and implements the
7893 @code{__call__} method.
7895 @defun MissingDebugHandler.__init__ (name)
7896 The @var{name} is a string used to reference this missing debug
7897 handler within some @value{GDBN} commands. Valid names consist of the
7898 characters @code{[-_a-zA-Z0-9]}, creating a handler with an invalid
7899 name raises a @code{ValueError} exception.
7902 @defun MissingDebugHandler.__call__ (objfile)
7903 Sub-classes must override the @code{__call__} method. The
7904 @var{objfile} argument will be a @code{gdb.Objfile}, this is the
7905 objfile for which @value{GDBN} was unable to find any debug
7908 The return value from the @code{__call__} method indicates what
7909 @value{GDBN} should do next. The possible return values are:
7914 This indicates that this handler could not help with @var{objfile},
7915 @value{GDBN} should call any other registered handlers.
7919 This indicates that this handler has installed the debug information
7920 into a location where @value{GDBN} would normally expect to find it
7921 when looking for separate debug information files (@pxref{Separate
7922 Debug Files}). @value{GDBN} will repeat the normal lookup process,
7923 which should now find the separate debug file.
7925 If @value{GDBN} still doesn't find the separate debug information file
7926 after this second attempt, then the Python missing debug information
7927 handlers are not invoked a second time, this prevents a badly behaved
7928 handler causing @value{GDBN} to get stuck in a loop. @value{GDBN}
7929 will continue without any debug information for @var{objfile}.
7933 This indicates that this handler has done everything that it intends
7934 to do with @var{objfile}, but no separate debug information can be
7935 found. @value{GDBN} will not call any other registered handlers for
7936 @var{objfile}. @value{GDBN} will continue without debugging
7937 information for @var{objfile}.
7941 The returned string should contain a filename. @value{GDBN} will not
7942 call any further registered handlers, and will instead load the debug
7943 information from the file identified by the returned filename.
7946 Invoking the @code{__call__} method from this base class will raise a
7947 @code{NotImplementedError} exception.
7950 @defvar MissingDebugHandler.name
7951 A read-only attribute which is a string, the name of this handler
7952 passed to the @code{__init__} method.
7955 @defvar MissingDebugHandler.enabled
7956 A modifiable attribute containing a boolean; when @code{True}, the
7957 handler is enabled, and will be used by @value{GDBN}. When
7958 @code{False}, the handler has been disabled, and will not be used.
7962 @defun gdb.missing_debug.register_handler (locus, handler, replace=@code{False})
7963 Register a new missing debug handler with @value{GDBN}.
7965 @var{handler} is an instance of a sub-class of
7966 @code{MissingDebugHandler}, or at least an instance of an object that
7967 has the same attributes and methods as @code{MissingDebugHandler}.
7969 @var{locus} specifies to which handler list to prepend @var{handler}.
7970 It can be either a @code{gdb.Progspace} (@pxref{Progspaces In Python})
7971 or @code{None}, in which case the handler is registered globally. The
7972 newly registered @var{handler} will be called before any other handler
7973 from the same locus. Two handlers in the same locus cannot have the
7974 same name, an attempt to add a handler with an already existing name
7975 raises an exception unless @var{replace} is @code{True}, in which case
7976 the old handler is deleted and the new handler is prepended to the
7977 selected handler list.
7979 @value{GDBN} first calls the handlers for the current program space,
7980 and then the globally registered handlers. As soon as a handler
7981 returns a value other than @code{None}, no further handlers are called
7985 @node Python Auto-loading
7986 @subsection Python Auto-loading
7987 @cindex Python auto-loading
7989 When a new object file is read (for example, due to the @code{file}
7990 command, or because the inferior has loaded a shared library),
7991 @value{GDBN} will look for Python support scripts in several ways:
7992 @file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
7993 @xref{Auto-loading extensions}.
7995 The auto-loading feature is useful for supplying application-specific
7996 debugging commands and scripts.
7998 Auto-loading can be enabled or disabled,
7999 and the list of auto-loaded scripts can be printed.
8002 @anchor{set auto-load python-scripts}
8003 @kindex set auto-load python-scripts
8004 @item set auto-load python-scripts [on|off]
8005 Enable or disable the auto-loading of Python scripts.
8007 @anchor{show auto-load python-scripts}
8008 @kindex show auto-load python-scripts
8009 @item show auto-load python-scripts
8010 Show whether auto-loading of Python scripts is enabled or disabled.
8012 @anchor{info auto-load python-scripts}
8013 @kindex info auto-load python-scripts
8014 @cindex print list of auto-loaded Python scripts
8015 @item info auto-load python-scripts [@var{regexp}]
8016 Print the list of all Python scripts that @value{GDBN} auto-loaded.
8018 Also printed is the list of Python scripts that were mentioned in
8019 the @code{.debug_gdb_scripts} section and were either not found
8020 (@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to
8021 @code{auto-load safe-path} rejection (@pxref{Auto-loading}).
8022 This is useful because their names are not printed when @value{GDBN}
8023 tries to load them and fails. There may be many of them, and printing
8024 an error message for each one is problematic.
8026 If @var{regexp} is supplied only Python scripts with matching names are printed.
8031 (gdb) info auto-load python-scripts
8033 Yes py-section-script.py
8034 full name: /tmp/py-section-script.py
8035 No my-foo-pretty-printers.py
8039 When reading an auto-loaded file or script, @value{GDBN} sets the
8040 @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
8041 function (@pxref{Objfiles In Python}). This can be useful for
8042 registering objfile-specific pretty-printers and frame-filters.
8044 @node Python modules
8045 @subsection Python modules
8046 @cindex python modules
8048 @value{GDBN} comes with several modules to assist writing Python code.
8051 * gdb.printing:: Building and registering pretty-printers.
8052 * gdb.types:: Utilities for working with types.
8053 * gdb.prompt:: Utilities for prompt value substitution.
8057 @subsubsection gdb.printing
8058 @cindex gdb.printing
8060 This module provides a collection of utilities for working with
8064 @item PrettyPrinter (@var{name}, @var{subprinters}=None)
8065 This class specifies the API that makes @samp{info pretty-printer},
8066 @samp{enable pretty-printer} and @samp{disable pretty-printer} work.
8067 Pretty-printers should generally inherit from this class.
8069 @item SubPrettyPrinter (@var{name})
8070 For printers that handle multiple types, this class specifies the
8071 corresponding API for the subprinters.
8073 @item RegexpCollectionPrettyPrinter (@var{name})
8074 Utility class for handling multiple printers, all recognized via
8075 regular expressions.
8076 @xref{Writing a Pretty-Printer}, for an example.
8078 @item FlagEnumerationPrinter (@var{name})
8079 A pretty-printer which handles printing of @code{enum} values. Unlike
8080 @value{GDBN}'s built-in @code{enum} printing, this printer attempts to
8081 work properly when there is some overlap between the enumeration
8082 constants. The argument @var{name} is the name of the printer and
8083 also the name of the @code{enum} type to look up.
8085 @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
8086 Register @var{printer} with the pretty-printer list of @var{obj}.
8087 If @var{replace} is @code{True} then any existing copy of the printer
8088 is replaced. Otherwise a @code{RuntimeError} exception is raised
8089 if a printer with the same name already exists.
8093 @subsubsection gdb.types
8096 This module provides a collection of utilities for working with
8097 @code{gdb.Type} objects.
8100 @item get_basic_type (@var{type})
8101 Return @var{type} with const and volatile qualifiers stripped,
8102 and with typedefs and C@t{++} references converted to the underlying type.
8107 typedef const int const_int;
8109 const_int& foo_ref (foo);
8110 int main () @{ return 0; @}
8117 (gdb) python import gdb.types
8118 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
8119 (gdb) python print gdb.types.get_basic_type(foo_ref.type)
8123 @item has_field (@var{type}, @var{field})
8124 Return @code{True} if @var{type}, assumed to be a type with fields
8125 (e.g., a structure or union), has field @var{field}.
8127 @item make_enum_dict (@var{enum_type})
8128 Return a Python @code{dictionary} type produced from @var{enum_type}.
8130 @item deep_items (@var{type})
8131 Returns a Python iterator similar to the standard
8132 @code{gdb.Type.iteritems} method, except that the iterator returned
8133 by @code{deep_items} will recursively traverse anonymous struct or
8134 union fields. For example:
8148 Then in @value{GDBN}:
8150 (@value{GDBP}) python import gdb.types
8151 (@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
8152 (@value{GDBP}) python print struct_a.keys ()
8154 (@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
8155 @{['a', 'b0', 'b1']@}
8158 @item get_type_recognizers ()
8159 Return a list of the enabled type recognizers for the current context.
8160 This is called by @value{GDBN} during the type-printing process
8161 (@pxref{Type Printing API}).
8163 @item apply_type_recognizers (recognizers, type_obj)
8164 Apply the type recognizers, @var{recognizers}, to the type object
8165 @var{type_obj}. If any recognizer returns a string, return that
8166 string. Otherwise, return @code{None}. This is called by
8167 @value{GDBN} during the type-printing process (@pxref{Type Printing
8170 @item register_type_printer (locus, printer)
8171 This is a convenience function to register a type printer
8172 @var{printer}. The printer must implement the type printer protocol.
8173 The @var{locus} argument is either a @code{gdb.Objfile}, in which case
8174 the printer is registered with that objfile; a @code{gdb.Progspace},
8175 in which case the printer is registered with that progspace; or
8176 @code{None}, in which case the printer is registered globally.
8179 This is a base class that implements the type printer protocol. Type
8180 printers are encouraged, but not required, to derive from this class.
8181 It defines a constructor:
8183 @defmethod TypePrinter __init__ (self, name)
8184 Initialize the type printer with the given name. The new printer
8185 starts in the enabled state.
8191 @subsubsection gdb.prompt
8194 This module provides a method for prompt value-substitution.
8197 @item substitute_prompt (@var{string})
8198 Return @var{string} with escape sequences substituted by values. Some
8199 escape sequences take arguments. You can specify arguments inside
8200 ``@{@}'' immediately following the escape sequence.
8202 The escape sequences you can pass to this function are:
8206 Substitute a backslash.
8208 Substitute an ESC character.
8210 Substitute the selected frame; an argument names a frame parameter.
8212 Substitute a newline.
8214 Substitute a parameter's value; the argument names the parameter.
8216 Substitute a carriage return.
8218 Substitute the selected thread; an argument names a thread parameter.
8220 Substitute the version of GDB.
8222 Substitute the current working directory.
8224 Begin a sequence of non-printing characters. These sequences are
8225 typically used with the ESC character, and are not counted in the string
8226 length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
8227 blue-colored ``(gdb)'' prompt where the length is five.
8229 End a sequence of non-printing characters.
8235 substitute_prompt ("frame: \f, args: \p@{print frame-arguments@}")
8238 @exdent will return the string:
8241 "frame: main, args: scalars"