\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2013 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2014 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2014 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2013 Free Software Foundation, Inc.
+Copyright (C) 1988-2014 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
instead of the current directory.
@item -data-directory @var{directory}
+@itemx -D @var{directory}
@cindex @code{--data-directory}
+@cindex @code{-D}
Run @value{GDBN} using @var{directory} as its data directory.
The data directory is where @value{GDBN} searches for its
auxiliary files. @xref{Data Files}.
elaboration phase. Under these circumstances, insert breakpoints in your
elaboration code before running your program.
+@anchor{set exec-wrapper}
@kindex set exec-wrapper
@item set exec-wrapper @var{wrapper}
@itemx show exec-wrapper
@kindex set environment
@item set environment @var{varname} @r{[}=@var{value}@r{]}
Set environment variable @var{varname} to @var{value}. The value
-changes for your program only, not for @value{GDBN} itself. @var{value} may
-be any string; the values of environment variables are just strings, and
-any interpretation is supplied by your program itself. The @var{value}
+changes for your program (and the shell @value{GDBN} uses to launch
+it), not for @value{GDBN} itself. @var{value} may be any string; the
+values of environment variables are just strings, and any
+interpretation is supplied by your program itself. The @var{value}
parameter is optional; if it is eliminated, the variable is set to a
null value.
@c "any string" here does not include leading, trailing
@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
are not actually required.)
+Note that on Unix systems, @value{GDBN} runs your program via a shell,
+which also inherits the environment set with @code{set environment}.
+If necessary, you can avoid that by using the @samp{env} program as a
+wrapper instead of using @code{set environment}. @xref{set
+exec-wrapper}, for an example doing just that.
+
@kindex unset environment
@item unset environment @var{varname}
Remove variable @var{varname} from the environment to be passed to your
@cindex non-stop mode
@c This section is really only a place-holder, and needs to be expanded
-@c with more details.
+@c with more details.
For some multi-threaded targets, @value{GDBN} supports an optional
mode of operation in which you can examine stopped program threads in
the debugger while other threads continue to execute freely. This
-minimizes intrusion when debugging live systems, such as programs
-where some threads have real-time constraints or must continue to
+minimizes intrusion when debugging live systems, such as programs
+where some threads have real-time constraints or must continue to
respond to external events. This is referred to as @dfn{non-stop} mode.
In non-stop mode, when a thread stops to report a debugging event,
execution commands such as @code{continue} and @code{step} apply by default
only to the current thread in non-stop mode, rather than all threads as
in all-stop mode. This allows you to control threads explicitly in
-ways that are not possible in all-stop mode --- for example, stepping
+ways that are not possible in all-stop mode --- for example, stepping
one thread while allowing others to run freely, stepping
-one thread while holding all others stopped, or stepping several threads
+one thread while holding all others stopped, or stepping several threads
independently and simultaneously.
To enter non-stop mode, use this sequence of commands before you run
or attach to your program:
@smallexample
-# Enable the async interface.
+# Enable the async interface.
set target-async 1
# If using the CLI, pagination breaks non-stop.
@end table
Note these commands only reflect whether non-stop mode is enabled,
-not whether the currently-executing program is being run in non-stop mode.
+not whether the currently-executing program is being run in non-stop mode.
In particular, the @code{set non-stop} preference is only consulted when
-@value{GDBN} starts or connects to the target program, and it is generally
+@value{GDBN} starts or connects to the target program, and it is generally
not possible to switch modes once debugging has started. Furthermore,
since not all targets support non-stop mode, even when you have enabled
non-stop mode, @value{GDBN} may still fall back to all-stop operation by
default.
In non-stop mode, all execution commands apply only to the current thread
-by default. That is, @code{continue} only continues one thread.
+by default. That is, @code{continue} only continues one thread.
To continue all threads, issue @code{continue -a} or @code{c -a}.
-You can use @value{GDBN}'s background execution commands
+You can use @value{GDBN}'s background execution commands
(@pxref{Background Execution}) to run some threads in the background
-while you continue to examine or step others from @value{GDBN}.
+while you continue to examine or step others from @value{GDBN}.
The MI execution commands (@pxref{GDB/MI Program Execution}) are
always executed asynchronously in non-stop mode.
Suspending execution is done with the @code{interrupt} command when
-running in the background, or @kbd{Ctrl-c} during foreground execution.
-In all-stop mode, this stops the whole process;
-but in non-stop mode the interrupt applies only to the current thread.
+running in the background, or @kbd{Ctrl-c} during foreground execution.
+In all-stop mode, this stops the whole process;
+but in non-stop mode the interrupt applies only to the current thread.
To stop the whole program, use @code{interrupt -a}.
Other execution commands do not currently support the @code{-a} option.
In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make
that thread current, as it does in all-stop mode. This is because the
-thread stop notifications are asynchronous with respect to @value{GDBN}'s
+thread stop notifications are asynchronous with respect to @value{GDBN}'s
command interpreter, and it would be confusing if @value{GDBN} unexpectedly
changed to a different thread just as you entered a command to operate on the
previously current thread.
@value{GDBN}'s execution commands have two variants: the normal
foreground (synchronous) behavior, and a background
-(asynchronous) behavior. In foreground execution, @value{GDBN} waits for
+(asynchronous) behavior. In foreground execution, @value{GDBN} waits for
the program to report that some thread has stopped before prompting for
another command. In background execution, @value{GDBN} immediately gives
a command prompt so that you can issue other commands while your program runs.
@item interrupt
@itemx interrupt -a
-Suspend execution of the running program. In all-stop mode,
+Suspend execution of the running program. In all-stop mode,
@code{interrupt} stops the whole process, but in non-stop mode, it stops
-only the current thread. To stop the whole program in non-stop mode,
+only the current thread. To stop the whole program in non-stop mode,
use @code{interrupt -a}.
@end table
execution.
@item btrace
-Hardware-supported instruction recording. This method does not allow
-replaying and reverse execution.
+Hardware-supported instruction recording. This method does not record
+data. Further, the data is collected in a ring buffer so old data will
+be overwritten when the buffer is full. It allows limited replay and
+reverse execution.
This recording method may not be available on all processors.
@end table
@item record instruction-history @var{begin} @var{end}
Disassembles instructions beginning with instruction number
@var{begin} until instruction number @var{end}. The instruction
-number @var{end} is not included.
+number @var{end} is included.
@end table
This command may not be available for all recording methods.
function giving the name of that function, the source lines
for this instruction sequence (if the @code{/l} modifier is
specified), and the instructions numbers that form the sequence (if
-the @code{/i} modifier is specified).
+the @code{/i} modifier is specified). The function names are indented
+to reflect the call stack depth if the @code{/c} modifier is
+specified. The @code{/l}, @code{/i}, and @code{/c} modifiers can be
+given together.
@smallexample
(@value{GDBP}) @b{list 1, 10}
8 foo ();
9 ...
10 @}
-(@value{GDBP}) @b{record function-call-history /l}
-1 foo.c:6-8 bar
-2 foo.c:2-3 foo
-3 foo.c:9-10 bar
+(@value{GDBP}) @b{record function-call-history /ilc}
+1 bar inst 1,4 at foo.c:6,8
+2 foo inst 5,10 at foo.c:2,3
+3 bar inst 11,13 at foo.c:9,10
@end smallexample
By default, ten lines are printed. This can be changed using the
@item record function-call-history @var{begin} @var{end}
Prints functions beginning with function number @var{begin} until
-function number @var{end}. The function number @var{end} is not
-included.
+function number @var{end}. The function number @var{end} is included.
@end table
This command may not be available for all recording methods.
@table @code
@kindex compare-sections
-@item compare-sections @r{[}@var{section-name}@r{]}
+@item compare-sections @r{[}@var{section-name}@r{|}@code{-r}@r{]}
Compare the data of a loadable section @var{section-name} in the
executable file of the program being debugged with the same section in
the remote machine's memory, and report any mismatches. With no
-arguments, compares all loadable sections. This command's
+arguments, compares all loadable sections. With an argument of
+@code{-r}, compares all loadable read-only sections. This command's
availability depends on the target's support for the @code{"qCRC"}
remote request.
@end table
@end table
+@cindex GNAT descriptive types
+@cindex GNAT encoding
+Internally, the debugger also relies on the compiler following a number
+of conventions known as the @samp{GNAT Encoding}, all documented in
+@file{gcc/ada/exp_dbug.ads} in the GCC sources. This encoding describes
+how the debugging information should be generated for certain types.
+In particular, this convention makes use of @dfn{descriptive types},
+which are artificial types generated purely to help the debugger.
+
+These encodings were defined at a time when the debugging information
+format used was not powerful enough to describe some of the more complex
+types available in Ada. Since DWARF allows us to express nearly all
+Ada features, the long-term goal is to slowly replace these descriptive
+types by their pure DWARF equivalent. To facilitate that transition,
+a new maintenance option is available to force the debugger to ignore
+those descriptive types. It allows the user to quickly evaluate how
+well @value{GDBN} works without them.
+
+@table @code
+
+@kindex maint ada set ignore-descriptive-types
+@item maintenance ada set ignore-descriptive-types [on|off]
+Control whether the debugger should ignore descriptive types.
+The default is not to ignore descriptives types (@code{off}).
+
+@kindex maint ada show ignore-descriptive-types
+@item maintenance ada show ignore-descriptive-types
+Show if descriptive types are ignored by @value{GDBN}.
+
+@end table
+
@node Unsupported Languages
@section Unsupported Languages
@item show opaque-type-resolution
Show whether opaque types are resolved or not.
+@kindex set print symbol-loading
+@cindex print messages when symbols are loaded
+@item set print symbol-loading
+@itemx set print symbol-loading full
+@itemx set print symbol-loading brief
+@itemx set print symbol-loading off
+The @code{set print symbol-loading} command allows you to control the
+printing of messages when @value{GDBN} loads symbol information.
+By default a message is printed for the executable and one for each
+shared library, and normally this is what you want. However, when
+debugging apps with large numbers of shared libraries these messages
+can be annoying.
+When set to @code{brief} a message is printed for each executable,
+and when @value{GDBN} loads a collection of shared libraries at once
+it will only print one message regardless of the number of shared
+libraries. When set to @code{off} no messages are printed.
+
+@kindex show print symbol-loading
+@item show print symbol-loading
+Show whether messages will be printed when a @value{GDBN} command
+entered from the keyboard causes symbol information to be loaded.
+
@kindex maint print symbols
@cindex symbol dump
@kindex maint print psymbols
@kindex assf
@item add-shared-symbol-files @var{library-file}
@itemx assf @var{library-file}
+This command is deprecated and will be removed in future versions
+of @value{GDBN}. Use the @code{sharedlibrary} command instead.
+
The @code{add-shared-symbol-files} command can currently be used only
in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an
alias for the @code{dll-symbols} command (@pxref{Cygwin Native}).
multiple instances of @code{gdbserver} running on the same host, since each
instance closes its port after the first connection.
+@anchor{Other Command-Line Arguments for gdbserver}
@subsubsection Other Command-Line Arguments for @code{gdbserver}
@cindex @option{--debug}, @code{gdbserver} option
remote protocol debug output. These options are intended for
@code{gdbserver} development and for bug reports to the developers.
+@cindex @option{--debug-format}, @code{gdbserver} option
+The @option{--debug-format=option1[,option2,...]} option tells
+@code{gdbserver} to include additional information in each output.
+Possible options are:
+
+@table @code
+@item none
+Turn off all extra information in debugging output.
+@item all
+Turn on all extra information in debugging output.
+@item timestamps
+Include a timestamp in each line of debugging output.
+@end table
+
+Options are processed in order. Thus, for example, if @option{none}
+appears last then no additional information is added to debugging output.
+
@cindex @option{--wrapper}, @code{gdbserver} option
The @option{--wrapper} option specifies a wrapper to launch programs
for debugging. The option should be followed by the name of the
Disable or enable specific debugging messages associated with the remote
protocol (@pxref{Remote Protocol}).
+@item monitor set debug-format option1@r{[},option2,...@r{]}
+Specify additional text to add to debugging messages.
+Possible options are:
+
+@table @code
+@item none
+Turn off all extra information in debugging output.
+@item all
+Turn on all extra information in debugging output.
+@item timestamps
+Include a timestamp in each line of debugging output.
+@end table
+
+Options are processed in order. Thus, for example, if @option{none}
+appears last then no additional information is added to debugging output.
+
@item monitor set libthread-db-search-path [PATH]
@cindex gdbserver, search path for @code{libthread_db}
When this command is issued, @var{path} is a colon-separated list of
@kindex dll-symbols
@item dll-symbols
+This command is deprecated and will be removed in future versions
+of @value{GDBN}. Use the @code{sharedlibrary} command instead.
+
This command loads symbols from a dll similarly to
add-sym command but without the need to specify a base address.
Note that before the debugged program has started execution, no DLLs
will have been loaded. The easiest way around this problem is simply to
start the program --- either by setting a breakpoint or letting the
-program run once to completion. It is also possible to force
-@value{GDBN} to load a particular DLL before starting the executable ---
-see the shared library information in @ref{Files}, or the
-@code{dll-symbols} command in @ref{Cygwin Native}. Currently,
-explicitly loading symbols from a DLL with no debugging information will
-cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
-which may adversely affect symbol lookup performance.
+program run once to completion.
@subsubsection DLL Name Prefixes
@tab Show setting of @value{GDBN} Python scripts.
@item @xref{info auto-load python-scripts}.
@tab Show state of @value{GDBN} Python scripts.
+@item @xref{set auto-load guile-scripts}.
+@tab Control for @value{GDBN} Guile scripts.
+@item @xref{show auto-load guile-scripts}.
+@tab Show setting of @value{GDBN} Guile scripts.
+@item @xref{info auto-load guile-scripts}.
+@tab Show state of @value{GDBN} Guile scripts.
@item @xref{set auto-load scripts-directory}.
@tab Control for @value{GDBN} auto-loaded scripts location.
@item @xref{show auto-load scripts-directory}.
@item show debug timestamp
Displays the current state of displaying timestamps with @value{GDBN}
debugging info.
-@item set debugvarobj
+@item set debug varobj
@cindex variable object debugging info
Turns on or off display of @value{GDBN} variable object debugging
info. The default is off.
-@item show debugvarobj
+@item show debug varobj
Displays the current state of displaying @value{GDBN} variable object
debugging info.
@item set debug xml
@menu
* Sequences:: Canned Sequences of @value{GDBN} Commands
* Python:: Extending @value{GDBN} using Python
+* Guile:: Extending @value{GDBN} using Guile
* Auto-loading extensions:: Automatically loading extensions
+* Multiple Extension Languages:: Working with multiple extension languages
* Aliases:: Creating new spellings of existing commands
@end menu
If @var{regexp} is supplied only canned sequences of commands scripts with
matching names are printed.
-@node Python
-@section Extending @value{GDBN} using Python
-@cindex python scripting
-@cindex scripting with python
-
-You can extend @value{GDBN} using the @uref{http://www.python.org/,
-Python programming language}. This feature is available only if
-@value{GDBN} was configured using @option{--with-python}.
-
-@cindex python directory
-Python scripts used by @value{GDBN} should be installed in
-@file{@var{data-directory}/python}, where @var{data-directory} is
-the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).
-This directory, known as the @dfn{python directory},
-is automatically added to the Python Search Path in order to allow
-the Python interpreter to locate all scripts installed at this location.
-
-Additionally, @value{GDBN} commands and convenience functions which
-are written in Python and are located in the
-@file{@var{data-directory}/python/gdb/command} or
-@file{@var{data-directory}/python/gdb/function} directories are
-automatically imported when @value{GDBN} starts.
-
-@menu
-* Python Commands:: Accessing Python from @value{GDBN}.
-* Python API:: Accessing @value{GDBN} from Python.
-* Python Auto-loading:: Automatically loading Python code.
-* Python modules:: Python modules provided by @value{GDBN}.
-@end menu
-
-@node Python Commands
-@subsection Python Commands
-@cindex python commands
-@cindex commands to access python
-
-@value{GDBN} provides two commands for accessing the Python interpreter,
-and one related setting:
-
-@table @code
-@kindex python-interactive
-@kindex pi
-@item python-interactive @r{[}@var{command}@r{]}
-@itemx pi @r{[}@var{command}@r{]}
-Without an argument, the @code{python-interactive} command can be used
-to start an interactive Python prompt. To return to @value{GDBN},
-type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
-
-Alternatively, a single-line Python command can be given as an
-argument and evaluated. If the command is an expression, the result
-will be printed; otherwise, nothing will be printed. For example:
-
-@smallexample
-(@value{GDBP}) python-interactive 2 + 3
-5
-@end smallexample
-
-@kindex python
-@kindex py
-@item python @r{[}@var{command}@r{]}
-@itemx py @r{[}@var{command}@r{]}
-The @code{python} command can be used to evaluate Python code.
-
-If given an argument, the @code{python} command will evaluate the
-argument as a Python command. For example:
-
-@smallexample
-(@value{GDBP}) python print 23
-23
-@end smallexample
-
-If you do not provide an argument to @code{python}, it will act as a
-multi-line command, like @code{define}. In this case, the Python
-script is made up of subsequent command lines, given after the
-@code{python} command. This command list is terminated using a line
-containing @code{end}. For example:
-
-@smallexample
-(@value{GDBP}) python
-Type python script
-End with a line saying just "end".
->print 23
->end
-23
-@end smallexample
-
-@kindex set python print-stack
-@item set python print-stack
-By default, @value{GDBN} will print only the message component of a
-Python exception when an error occurs in a Python script. This can be
-controlled using @code{set python print-stack}: if @code{full}, then
-full Python stack printing is enabled; if @code{none}, then Python stack
-and message printing is disabled; if @code{message}, the default, only
-the message component of the error is printed.
-@end table
-
-It is also possible to execute a Python script from the @value{GDBN}
-interpreter:
-
-@table @code
-@item source @file{script-name}
-The script name must end with @samp{.py} and @value{GDBN} must be configured
-to recognize the script language based on filename extension using
-the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
-
-@item python execfile ("script-name")
-This method is based on the @code{execfile} Python built-in function,
-and thus is always available.
-@end table
-
-@node Python API
-@subsection Python API
-@cindex python api
-@cindex programming in python
-
-You can get quick online help for @value{GDBN}'s Python API by issuing
-the command @w{@kbd{python help (gdb)}}.
-
-Functions and methods which have two or more optional arguments allow
-them to be specified using keyword syntax. This allows passing some
-optional arguments while skipping others. Example:
-@w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
-
-@menu
-* Basic Python:: Basic Python Functions.
-* Exception Handling:: How Python exceptions are translated.
-* Values From Inferior:: Python representation of values.
-* Types In Python:: Python representation of types.
-* Pretty Printing API:: Pretty-printing values.
-* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
-* Writing a Pretty-Printer:: Writing a Pretty-Printer.
-* Type Printing API:: Pretty-printing types.
-* Frame Filter API:: Filtering Frames.
-* Frame Decorator API:: Decorating Frames.
-* Writing a Frame Filter:: Writing a Frame Filter.
-* Inferiors In Python:: Python representation of inferiors (processes)
-* Events In Python:: Listening for events from @value{GDBN}.
-* Threads In Python:: Accessing inferior threads from Python.
-* Commands In Python:: Implementing new commands in Python.
-* Parameters In Python:: Adding new @value{GDBN} parameters.
-* Functions In Python:: Writing new convenience functions.
-* Progspaces In Python:: Program spaces.
-* Objfiles In Python:: Object files.
-* Frames In Python:: Accessing inferior stack frames from Python.
-* Blocks In Python:: Accessing blocks from Python.
-* Symbols In Python:: Python representation of symbols.
-* Symbol Tables In Python:: Python representation of symbol tables.
-* Line Tables In Python:: Python representation of line tables.
-* Breakpoints In Python:: Manipulating breakpoints using Python.
-* Finish Breakpoints in Python:: Setting Breakpoints on function return
- using Python.
-* Lazy Strings In Python:: Python representation of lazy strings.
-* Architectures In Python:: Python representation of architectures.
-@end menu
-
-@node Basic Python
-@subsubsection Basic Python
-
-@cindex python stdout
-@cindex python pagination
-At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
-@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
-A Python program which outputs to one of these streams may have its
-output interrupted by the user (@pxref{Screen Size}). In this
-situation, a Python @code{KeyboardInterrupt} exception is thrown.
-
-Some care must be taken when writing Python code to run in
-@value{GDBN}. Two things worth noting in particular:
-
-@itemize @bullet
-@item
-@value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
-Python code must not override these, or even change the options using
-@code{sigaction}. If your program changes the handling of these
-signals, @value{GDBN} will most likely stop working correctly. Note
-that it is unfortunately common for GUI toolkits to install a
-@code{SIGCHLD} handler.
-
-@item
-@value{GDBN} takes care to mark its internal file descriptors as
-close-on-exec. However, this cannot be done in a thread-safe way on
-all platforms. Your Python programs should be aware of this and
-should both create new file descriptors with the close-on-exec flag
-set and arrange to close unneeded file descriptors before starting a
-child process.
-@end itemize
-
-@cindex python functions
-@cindex python module
-@cindex gdb module
-@value{GDBN} introduces a new Python module, named @code{gdb}. All
-methods and classes added by @value{GDBN} are placed in this module.
-@value{GDBN} automatically @code{import}s the @code{gdb} module for
-use in all scripts evaluated by the @code{python} command.
-
-@findex gdb.PYTHONDIR
-@defvar gdb.PYTHONDIR
-A string containing the python directory (@pxref{Python}).
-@end defvar
-
-@findex gdb.execute
-@defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
-Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
-If a GDB exception happens while @var{command} runs, it is
-translated as described in @ref{Exception Handling,,Exception Handling}.
-
-@var{from_tty} specifies whether @value{GDBN} ought to consider this
-command as having originated from the user invoking it interactively.
-It must be a boolean value. If omitted, it defaults to @code{False}.
-
-By default, any output produced by @var{command} is sent to
-@value{GDBN}'s standard output. If the @var{to_string} parameter is
-@code{True}, then output will be collected by @code{gdb.execute} and
-returned as a string. The default is @code{False}, in which case the
-return value is @code{None}. If @var{to_string} is @code{True}, the
-@value{GDBN} virtual terminal will be temporarily set to unlimited width
-and height, and its pagination will be disabled; @pxref{Screen Size}.
-@end defun
-
-@findex gdb.breakpoints
-@defun gdb.breakpoints ()
-Return a sequence holding all of @value{GDBN}'s breakpoints.
-@xref{Breakpoints In Python}, for more information.
-@end defun
-
-@findex gdb.parameter
-@defun gdb.parameter (parameter)
-Return the value of a @value{GDBN} parameter. @var{parameter} is a
-string naming the parameter to look up; @var{parameter} may contain
-spaces if the parameter has a multi-part name. For example,
-@samp{print object} is a valid parameter name.
-
-If the named parameter does not exist, this function throws a
-@code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
-parameter's value is converted to a Python value of the appropriate
-type, and returned.
-@end defun
-
-@findex gdb.history
-@defun gdb.history (number)
-Return a value from @value{GDBN}'s value history (@pxref{Value
-History}). @var{number} indicates which history element to return.
-If @var{number} is negative, then @value{GDBN} will take its absolute value
-and count backward from the last element (i.e., the most recent element) to
-find the value to return. If @var{number} is zero, then @value{GDBN} will
-return the most recent element. If the element specified by @var{number}
-doesn't exist in the value history, a @code{gdb.error} exception will be
-raised.
-
-If no exception is raised, the return value is always an instance of
-@code{gdb.Value} (@pxref{Values From Inferior}).
-@end defun
-
-@findex gdb.parse_and_eval
-@defun gdb.parse_and_eval (expression)
-Parse @var{expression} as an expression in the current language,
-evaluate it, and return the result as a @code{gdb.Value}.
-@var{expression} must be a string.
-
-This function can be useful when implementing a new command
-(@pxref{Commands In Python}), as it provides a way to parse the
-command's argument as an expression. It is also useful simply to
-compute values, for example, it is the only way to get the value of a
-convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
-@end defun
-
-@findex gdb.find_pc_line
-@defun gdb.find_pc_line (pc)
-Return the @code{gdb.Symtab_and_line} object corresponding to the
-@var{pc} value. @xref{Symbol Tables In Python}. If an invalid
-value of @var{pc} is passed as an argument, then the @code{symtab} and
-@code{line} attributes of the returned @code{gdb.Symtab_and_line} object
-will be @code{None} and 0 respectively.
-@end defun
-
-@findex gdb.post_event
-@defun gdb.post_event (event)
-Put @var{event}, a callable object taking no arguments, into
-@value{GDBN}'s internal event queue. This callable will be invoked at
-some later point, during @value{GDBN}'s event processing. Events
-posted using @code{post_event} will be run in the order in which they
-were posted; however, there is no way to know when they will be
-processed relative to other events inside @value{GDBN}.
-
-@value{GDBN} is not thread-safe. If your Python program uses multiple
-threads, you must be careful to only call @value{GDBN}-specific
-functions in the main @value{GDBN} thread. @code{post_event} ensures
-this. For example:
-
-@smallexample
-(@value{GDBP}) python
->import threading
->
->class Writer():
-> def __init__(self, message):
-> self.message = message;
-> def __call__(self):
-> gdb.write(self.message)
->
->class MyThread1 (threading.Thread):
-> def run (self):
-> gdb.post_event(Writer("Hello "))
->
->class MyThread2 (threading.Thread):
-> def run (self):
-> gdb.post_event(Writer("World\n"))
->
->MyThread1().start()
->MyThread2().start()
->end
-(@value{GDBP}) Hello World
-@end smallexample
-@end defun
-
-@findex gdb.write
-@defun gdb.write (string @r{[}, stream{]})
-Print a string to @value{GDBN}'s paginated output stream. The
-optional @var{stream} determines the stream to print to. The default
-stream is @value{GDBN}'s standard output stream. Possible stream
-values are:
-
-@table @code
-@findex STDOUT
-@findex gdb.STDOUT
-@item gdb.STDOUT
-@value{GDBN}'s standard output stream.
-
-@findex STDERR
-@findex gdb.STDERR
-@item gdb.STDERR
-@value{GDBN}'s standard error stream.
-
-@findex STDLOG
-@findex gdb.STDLOG
-@item gdb.STDLOG
-@value{GDBN}'s log stream (@pxref{Logging Output}).
-@end table
-
-Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
-call this function and will automatically direct the output to the
-relevant stream.
-@end defun
-
-@findex gdb.flush
-@defun gdb.flush ()
-Flush the buffer of a @value{GDBN} paginated stream so that the
-contents are displayed immediately. @value{GDBN} will flush the
-contents of a stream automatically when it encounters a newline in the
-buffer. The optional @var{stream} determines the stream to flush. The
-default stream is @value{GDBN}'s standard output stream. Possible
-stream values are:
-
-@table @code
-@findex STDOUT
-@findex gdb.STDOUT
-@item gdb.STDOUT
-@value{GDBN}'s standard output stream.
-
-@findex STDERR
-@findex gdb.STDERR
-@item gdb.STDERR
-@value{GDBN}'s standard error stream.
-
-@findex STDLOG
-@findex gdb.STDLOG
-@item gdb.STDLOG
-@value{GDBN}'s log stream (@pxref{Logging Output}).
-
-@end table
-
-Flushing @code{sys.stdout} or @code{sys.stderr} will automatically
-call this function for the relevant stream.
-@end defun
-
-@findex gdb.target_charset
-@defun gdb.target_charset ()
-Return the name of the current target character set (@pxref{Character
-Sets}). This differs from @code{gdb.parameter('target-charset')} in
-that @samp{auto} is never returned.
-@end defun
-
-@findex gdb.target_wide_charset
-@defun gdb.target_wide_charset ()
-Return the name of the current target wide character set
-(@pxref{Character Sets}). This differs from
-@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
-never returned.
-@end defun
-
-@findex gdb.solib_name
-@defun gdb.solib_name (address)
-Return the name of the shared library holding the given @var{address}
-as a string, or @code{None}.
-@end defun
-
-@findex gdb.decode_line
-@defun gdb.decode_line @r{[}expression@r{]}
-Return locations of the line specified by @var{expression}, or of the
-current line if no argument was given. This function returns a Python
-tuple containing two elements. The first element contains a string
-holding any unparsed section of @var{expression} (or @code{None} if
-the expression has been fully parsed). The second element contains
-either @code{None} or another tuple that contains all the locations
-that match the expression represented as @code{gdb.Symtab_and_line}
-objects (@pxref{Symbol Tables In Python}). If @var{expression} is
-provided, it is decoded the way that @value{GDBN}'s inbuilt
-@code{break} or @code{edit} commands do (@pxref{Specify Location}).
-@end defun
-
-@defun gdb.prompt_hook (current_prompt)
-@anchor{prompt_hook}
-
-If @var{prompt_hook} is callable, @value{GDBN} will call the method
-assigned to this operation before a prompt is displayed by
-@value{GDBN}.
-
-The parameter @code{current_prompt} contains the current @value{GDBN}
-prompt. This method must return a Python string, or @code{None}. If
-a string is returned, the @value{GDBN} prompt will be set to that
-string. If @code{None} is returned, @value{GDBN} will continue to use
-the current prompt.
-
-Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
-such as those used by readline for command input, and annotation
-related prompts are prohibited from being changed.
-@end defun
-
-@node Exception Handling
-@subsubsection Exception Handling
-@cindex python exceptions
-@cindex exceptions, python
-
-When executing the @code{python} command, Python exceptions
-uncaught within the Python code are translated to calls to
-@value{GDBN} error-reporting mechanism. If the command that called
-@code{python} does not handle the error, @value{GDBN} will
-terminate it and print an error message containing the Python
-exception name, the associated value, and the Python call stack
-backtrace at the point where the exception was raised. Example:
-
-@smallexample
-(@value{GDBP}) python print foo
-Traceback (most recent call last):
- File "<string>", line 1, in <module>
-NameError: name 'foo' is not defined
-@end smallexample
-
-@value{GDBN} errors that happen in @value{GDBN} commands invoked by
-Python code are converted to Python exceptions. The type of the
-Python exception depends on the error.
-
-@ftable @code
-@item gdb.error
-This is the base class for most exceptions generated by @value{GDBN}.
-It is derived from @code{RuntimeError}, for compatibility with earlier
-versions of @value{GDBN}.
-
-If an error occurring in @value{GDBN} does not fit into some more
-specific category, then the generated exception will have this type.
-
-@item gdb.MemoryError
-This is a subclass of @code{gdb.error} which is thrown when an
-operation tried to access invalid memory in the inferior.
-
-@item KeyboardInterrupt
-User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
-prompt) is translated to a Python @code{KeyboardInterrupt} exception.
-@end ftable
-
-In all cases, your exception handler will see the @value{GDBN} error
-message as its value and the Python call stack backtrace at the Python
-statement closest to where the @value{GDBN} error occured as the
-traceback.
-
-@findex gdb.GdbError
-When implementing @value{GDBN} commands in Python via @code{gdb.Command},
-it is useful to be able to throw an exception that doesn't cause a
-traceback to be printed. For example, the user may have invoked the
-command incorrectly. Use the @code{gdb.GdbError} exception
-to handle this case. Example:
-
-@smallexample
-(gdb) python
->class HelloWorld (gdb.Command):
-> """Greet the whole world."""
-> def __init__ (self):
-> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
-> def invoke (self, args, from_tty):
-> argv = gdb.string_to_argv (args)
-> if len (argv) != 0:
-> raise gdb.GdbError ("hello-world takes no arguments")
-> print "Hello, World!"
->HelloWorld ()
->end
-(gdb) hello-world 42
-hello-world takes no arguments
-@end smallexample
-
-@node Values From Inferior
-@subsubsection Values From Inferior
-@cindex values from inferior, with Python
-@cindex python, working with values from inferior
-
-@cindex @code{gdb.Value}
-@value{GDBN} provides values it obtains from the inferior program in
-an object of type @code{gdb.Value}. @value{GDBN} uses this object
-for its internal bookkeeping of the inferior's values, and for
-fetching values when necessary.
-
-Inferior values that are simple scalars can be used directly in
-Python expressions that are valid for the value's data type. Here's
-an example for an integer or floating-point value @code{some_val}:
-
-@smallexample
-bar = some_val + 2
-@end smallexample
-
-@noindent
-As result of this, @code{bar} will also be a @code{gdb.Value} object
-whose values are of the same type as those of @code{some_val}.
-
-Inferior values that are structures or instances of some class can
-be accessed using the Python @dfn{dictionary syntax}. For example, if
-@code{some_val} is a @code{gdb.Value} instance holding a structure, you
-can access its @code{foo} element with:
-
-@smallexample
-bar = some_val['foo']
-@end smallexample
-
-@cindex getting structure elements using gdb.Field objects as subscripts
-Again, @code{bar} will also be a @code{gdb.Value} object. Structure
-elements can also be accessed by using @code{gdb.Field} objects as
-subscripts (@pxref{Types In Python}, for more information on
-@code{gdb.Field} objects). For example, if @code{foo_field} is a
-@code{gdb.Field} object corresponding to element @code{foo} of the above
-structure, then @code{bar} can also be accessed as follows:
-
-@smallexample
-bar = some_val[foo_field]
-@end smallexample
-
-A @code{gdb.Value} that represents a function can be executed via
-inferior function call. Any arguments provided to the call must match
-the function's prototype, and must be provided in the order specified
-by that prototype.
-
-For example, @code{some_val} is a @code{gdb.Value} instance
-representing a function that takes two integers as arguments. To
-execute this function, call it like so:
-
-@smallexample
-result = some_val (10,20)
-@end smallexample
-
-Any values returned from a function call will be stored as a
-@code{gdb.Value}.
-
-The following attributes are provided:
-
-@defvar Value.address
-If this object is addressable, this read-only attribute holds a
-@code{gdb.Value} object representing the address. Otherwise,
-this attribute holds @code{None}.
-@end defvar
-
-@cindex optimized out value in Python
-@defvar Value.is_optimized_out
-This read-only boolean attribute is true if the compiler optimized out
-this value, thus it is not available for fetching from the inferior.
-@end defvar
-
-@defvar Value.type
-The type of this @code{gdb.Value}. The value of this attribute is a
-@code{gdb.Type} object (@pxref{Types In Python}).
-@end defvar
-
-@defvar Value.dynamic_type
-The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time
-type information (@acronym{RTTI}) to determine the dynamic type of the
-value. If this value is of class type, it will return the class in
-which the value is embedded, if any. If this value is of pointer or
-reference to a class type, it will compute the dynamic type of the
-referenced object, and return a pointer or reference to that type,
-respectively. In all other cases, it will return the value's static
-type.
-
-Note that this feature will only work when debugging a C@t{++} program
-that includes @acronym{RTTI} for the object in question. Otherwise,
-it will just return the static type of the value as in @kbd{ptype foo}
-(@pxref{Symbols, ptype}).
-@end defvar
-
-@defvar Value.is_lazy
-The value of this read-only boolean attribute is @code{True} if this
-@code{gdb.Value} has not yet been fetched from the inferior.
-@value{GDBN} does not fetch values until necessary, for efficiency.
-For example:
-
-@smallexample
-myval = gdb.parse_and_eval ('somevar')
-@end smallexample
-
-The value of @code{somevar} is not fetched at this time. It will be
-fetched when the value is needed, or when the @code{fetch_lazy}
-method is invoked.
-@end defvar
-
-The following methods are provided:
-
-@defun Value.__init__ (@var{val})
-Many Python values can be converted directly to a @code{gdb.Value} via
-this object initializer. Specifically:
-
-@table @asis
-@item Python boolean
-A Python boolean is converted to the boolean type from the current
-language.
-
-@item Python integer
-A Python integer is converted to the C @code{long} type for the
-current architecture.
-
-@item Python long
-A Python long is converted to the C @code{long long} type for the
-current architecture.
-
-@item Python float
-A Python float is converted to the C @code{double} type for the
-current architecture.
-
-@item Python string
-A Python string is converted to a target string, using the current
-target encoding.
-
-@item @code{gdb.Value}
-If @code{val} is a @code{gdb.Value}, then a copy of the value is made.
-
-@item @code{gdb.LazyString}
-If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In
-Python}), then the lazy string's @code{value} method is called, and
-its result is used.
-@end table
-@end defun
-
-@defun Value.cast (type)
-Return a new instance of @code{gdb.Value} that is the result of
-casting this instance to the type described by @var{type}, which must
-be a @code{gdb.Type} object. If the cast cannot be performed for some
-reason, this method throws an exception.
-@end defun
-
-@defun Value.dereference ()
-For pointer data types, this method returns a new @code{gdb.Value} object
-whose contents is the object pointed to by the pointer. For example, if
-@code{foo} is a C pointer to an @code{int}, declared in your C program as
-
-@smallexample
-int *foo;
-@end smallexample
-
-@noindent
-then you can use the corresponding @code{gdb.Value} to access what
-@code{foo} points to like this:
-
-@smallexample
-bar = foo.dereference ()
-@end smallexample
-
-The result @code{bar} will be a @code{gdb.Value} object holding the
-value pointed to by @code{foo}.
-
-A similar function @code{Value.referenced_value} exists which also
-returns @code{gdb.Value} objects corresonding to the values pointed to
-by pointer values (and additionally, values referenced by reference
-values). However, the behavior of @code{Value.dereference}
-differs from @code{Value.referenced_value} by the fact that the
-behavior of @code{Value.dereference} is identical to applying the C
-unary operator @code{*} on a given value. For example, consider a
-reference to a pointer @code{ptrref}, declared in your C@t{++} program
-as
-
-@smallexample
-typedef int *intptr;
-...
-int val = 10;
-intptr ptr = &val;
-intptr &ptrref = ptr;
-@end smallexample
-
-Though @code{ptrref} is a reference value, one can apply the method
-@code{Value.dereference} to the @code{gdb.Value} object corresponding
-to it and obtain a @code{gdb.Value} which is identical to that
-corresponding to @code{val}. However, if you apply the method
-@code{Value.referenced_value}, the result would be a @code{gdb.Value}
-object identical to that corresponding to @code{ptr}.
-
-@smallexample
-py_ptrref = gdb.parse_and_eval ("ptrref")
-py_val = py_ptrref.dereference ()
-py_ptr = py_ptrref.referenced_value ()
-@end smallexample
-
-The @code{gdb.Value} object @code{py_val} is identical to that
-corresponding to @code{val}, and @code{py_ptr} is identical to that
-corresponding to @code{ptr}. In general, @code{Value.dereference} can
-be applied whenever the C unary operator @code{*} can be applied
-to the corresponding C value. For those cases where applying both
-@code{Value.dereference} and @code{Value.referenced_value} is allowed,
-the results obtained need not be identical (as we have seen in the above
-example). The results are however identical when applied on
-@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
-objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
-@end defun
-
-@defun Value.referenced_value ()
-For pointer or reference data types, this method returns a new
-@code{gdb.Value} object corresponding to the value referenced by the
-pointer/reference value. For pointer data types,
-@code{Value.dereference} and @code{Value.referenced_value} produce
-identical results. The difference between these methods is that
-@code{Value.dereference} cannot get the values referenced by reference
-values. For example, consider a reference to an @code{int}, declared
-in your C@t{++} program as
-
-@smallexample
-int val = 10;
-int &ref = val;
-@end smallexample
-
-@noindent
-then applying @code{Value.dereference} to the @code{gdb.Value} object
-corresponding to @code{ref} will result in an error, while applying
-@code{Value.referenced_value} will result in a @code{gdb.Value} object
-identical to that corresponding to @code{val}.
-
-@smallexample
-py_ref = gdb.parse_and_eval ("ref")
-er_ref = py_ref.dereference () # Results in error
-py_val = py_ref.referenced_value () # Returns the referenced value
-@end smallexample
-
-The @code{gdb.Value} object @code{py_val} is identical to that
-corresponding to @code{val}.
-@end defun
-
-@defun Value.dynamic_cast (type)
-Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast}
-operator were used. Consult a C@t{++} reference for details.
-@end defun
-
-@defun Value.reinterpret_cast (type)
-Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast}
-operator were used. Consult a C@t{++} reference for details.
-@end defun
-
-@defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]})
-If this @code{gdb.Value} represents a string, then this method
-converts the contents to a Python string. Otherwise, this method will
-throw an exception.
-
-Strings are recognized in a language-specific way; whether a given
-@code{gdb.Value} represents a string is determined by the current
-language.
-
-For C-like languages, a value is a string if it is a pointer to or an
-array of characters or ints. The string is assumed to be terminated
-by a zero of the appropriate width. However if the optional length
-argument is given, the string will be converted to that given length,
-ignoring any embedded zeros that the string may contain.
-
-If the optional @var{encoding} argument is given, it must be a string
-naming the encoding of the string in the @code{gdb.Value}, such as
-@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
-the same encodings as the corresponding argument to Python's
-@code{string.decode} method, and the Python codec machinery will be used
-to convert the string. If @var{encoding} is not given, or if
-@var{encoding} is the empty string, then either the @code{target-charset}
-(@pxref{Character Sets}) will be used, or a language-specific encoding
-will be used, if the current language is able to supply one.
-
-The optional @var{errors} argument is the same as the corresponding
-argument to Python's @code{string.decode} method.
-
-If the optional @var{length} argument is given, the string will be
-fetched and converted to the given length.
-@end defun
-
-@defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]})
-If this @code{gdb.Value} represents a string, then this method
-converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
-In Python}). Otherwise, this method will throw an exception.
-
-If the optional @var{encoding} argument is given, it must be a string
-naming the encoding of the @code{gdb.LazyString}. Some examples are:
-@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
-@var{encoding} argument is an encoding that @value{GDBN} does
-recognize, @value{GDBN} will raise an error.
-
-When a lazy string is printed, the @value{GDBN} encoding machinery is
-used to convert the string during printing. If the optional
-@var{encoding} argument is not provided, or is an empty string,
-@value{GDBN} will automatically select the encoding most suitable for
-the string type. For further information on encoding in @value{GDBN}
-please see @ref{Character Sets}.
-
-If the optional @var{length} argument is given, the string will be
-fetched and encoded to the length of characters specified. If
-the @var{length} argument is not provided, the string will be fetched
-and encoded until a null of appropriate width is found.
-@end defun
-
-@defun Value.fetch_lazy ()
-If the @code{gdb.Value} object is currently a lazy value
-(@code{gdb.Value.is_lazy} is @code{True}), then the value is
-fetched from the inferior. Any errors that occur in the process
-will produce a Python exception.
-
-If the @code{gdb.Value} object is not a lazy value, this method
-has no effect.
-
-This method does not return a value.
-@end defun
-
-
-@node Types In Python
-@subsubsection Types In Python
-@cindex types in Python
-@cindex Python, working with types
-
-@tindex gdb.Type
-@value{GDBN} represents types from the inferior using the class
-@code{gdb.Type}.
-
-The following type-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.lookup_type
-@defun gdb.lookup_type (name @r{[}, block@r{]})
-This function looks up a type by name. @var{name} is the name of the
-type to look up. It must be a string.
-
-If @var{block} is given, then @var{name} is looked up in that scope.
-Otherwise, it is searched for globally.
-
-Ordinarily, this function will return an instance of @code{gdb.Type}.
-If the named type cannot be found, it will throw an exception.
-@end defun
-
-If the type is a structure or class type, or an enum type, the fields
-of that type can be accessed using the Python @dfn{dictionary syntax}.
-For example, if @code{some_type} is a @code{gdb.Type} instance holding
-a structure type, you can access its @code{foo} field with:
-
-@smallexample
-bar = some_type['foo']
-@end smallexample
-
-@code{bar} will be a @code{gdb.Field} object; see below under the
-description of the @code{Type.fields} method for a description of the
-@code{gdb.Field} class.
-
-An instance of @code{Type} has the following attributes:
-
-@defvar Type.code
-The type code for this type. The type code will be one of the
-@code{TYPE_CODE_} constants defined below.
-@end defvar
-
-@defvar Type.sizeof
-The size of this type, in target @code{char} units. Usually, a
-target's @code{char} type will be an 8-bit byte. However, on some
-unusual platforms, this type may have a different size.
-@end defvar
-
-@defvar Type.tag
-The tag name for this type. The tag name is the name after
-@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
-languages have this concept. If this type has no tag name, then
-@code{None} is returned.
-@end defvar
-
-The following methods are provided:
-
-@defun Type.fields ()
-For structure and union types, this method returns the fields. Range
-types have two fields, the minimum and maximum values. Enum types
-have one field per enum constant. Function and method types have one
-field per parameter. The base types of C@t{++} classes are also
-represented as fields. If the type has no fields, or does not fit
-into one of these categories, an empty sequence will be returned.
-
-Each field is a @code{gdb.Field} object, with some pre-defined attributes:
-@table @code
-@item bitpos
-This attribute is not available for @code{static} fields (as in
-C@t{++} or Java). For non-@code{static} fields, the value is the bit
-position of the field. For @code{enum} fields, the value is the
-enumeration member's integer representation.
-
-@item name
-The name of the field, or @code{None} for anonymous fields.
-
-@item artificial
-This is @code{True} if the field is artificial, usually meaning that
-it was provided by the compiler and not the user. This attribute is
-always provided, and is @code{False} if the field is not artificial.
-
-@item is_base_class
-This is @code{True} if the field represents a base class of a C@t{++}
-structure. This attribute is always provided, and is @code{False}
-if the field is not a base class of the type that is the argument of
-@code{fields}, or if that type was not a C@t{++} class.
-
-@item bitsize
-If the field is packed, or is a bitfield, then this will have a
-non-zero value, which is the size of the field in bits. Otherwise,
-this will be zero; in this case the field's size is given by its type.
-
-@item type
-The type of the field. This is usually an instance of @code{Type},
-but it can be @code{None} in some situations.
-
-@item parent_type
-The type which contains this field. This is an instance of
-@code{gdb.Type}.
-@end table
-@end defun
-
-@defun Type.array (@var{n1} @r{[}, @var{n2}@r{]})
-Return a new @code{gdb.Type} object which represents an array of this
-type. If one argument is given, it is the inclusive upper bound of
-the array; in this case the lower bound is zero. If two arguments are
-given, the first argument is the lower bound of the array, and the
-second argument is the upper bound of the array. An array's length
-must not be negative, but the bounds can be.
-@end defun
-
-@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
-Return a new @code{gdb.Type} object which represents a vector of this
-type. If one argument is given, it is the inclusive upper bound of
-the vector; in this case the lower bound is zero. If two arguments are
-given, the first argument is the lower bound of the vector, and the
-second argument is the upper bound of the vector. A vector's length
-must not be negative, but the bounds can be.
-
-The difference between an @code{array} and a @code{vector} is that
-arrays behave like in C: when used in expressions they decay to a pointer
-to the first element whereas vectors are treated as first class values.
-@end defun
-
-@defun Type.const ()
-Return a new @code{gdb.Type} object which represents a
-@code{const}-qualified variant of this type.
-@end defun
-
-@defun Type.volatile ()
-Return a new @code{gdb.Type} object which represents a
-@code{volatile}-qualified variant of this type.
-@end defun
-
-@defun Type.unqualified ()
-Return a new @code{gdb.Type} object which represents an unqualified
-variant of this type. That is, the result is neither @code{const} nor
-@code{volatile}.
-@end defun
-
-@defun Type.range ()
-Return a Python @code{Tuple} object that contains two elements: the
-low bound of the argument type and the high bound of that type. If
-the type does not have a range, @value{GDBN} will raise a
-@code{gdb.error} exception (@pxref{Exception Handling}).
-@end defun
-
-@defun Type.reference ()
-Return a new @code{gdb.Type} object which represents a reference to this
-type.
-@end defun
-
-@defun Type.pointer ()
-Return a new @code{gdb.Type} object which represents a pointer to this
-type.
-@end defun
-
-@defun Type.strip_typedefs ()
-Return a new @code{gdb.Type} that represents the real type,
-after removing all layers of typedefs.
-@end defun
-
-@defun Type.target ()
-Return a new @code{gdb.Type} object which represents the target type
-of this type.
-
-For a pointer type, the target type is the type of the pointed-to
-object. For an array type (meaning C-like arrays), the target type is
-the type of the elements of the array. For a function or method type,
-the target type is the type of the return value. For a complex type,
-the target type is the type of the elements. For a typedef, the
-target type is the aliased type.
-
-If the type does not have a target, this method will throw an
-exception.
-@end defun
-
-@defun Type.template_argument (n @r{[}, block@r{]})
-If this @code{gdb.Type} is an instantiation of a template, this will
-return a new @code{gdb.Type} which represents the type of the
-@var{n}th template argument.
-
-If this @code{gdb.Type} is not a template type, this will throw an
-exception. Ordinarily, only C@t{++} code will have template types.
-
-If @var{block} is given, then @var{name} is looked up in that scope.
-Otherwise, it is searched for globally.
-@end defun
-
-
-Each type has a code, which indicates what category this type falls
-into. The available type categories are represented by constants
-defined in the @code{gdb} module:
-
-@table @code
-@findex TYPE_CODE_PTR
-@findex gdb.TYPE_CODE_PTR
-@item gdb.TYPE_CODE_PTR
-The type is a pointer.
-
-@findex TYPE_CODE_ARRAY
-@findex gdb.TYPE_CODE_ARRAY
-@item gdb.TYPE_CODE_ARRAY
-The type is an array.
-
-@findex TYPE_CODE_STRUCT
-@findex gdb.TYPE_CODE_STRUCT
-@item gdb.TYPE_CODE_STRUCT
-The type is a structure.
-
-@findex TYPE_CODE_UNION
-@findex gdb.TYPE_CODE_UNION
-@item gdb.TYPE_CODE_UNION
-The type is a union.
-
-@findex TYPE_CODE_ENUM
-@findex gdb.TYPE_CODE_ENUM
-@item gdb.TYPE_CODE_ENUM
-The type is an enum.
-
-@findex TYPE_CODE_FLAGS
-@findex gdb.TYPE_CODE_FLAGS
-@item gdb.TYPE_CODE_FLAGS
-A bit flags type, used for things such as status registers.
-
-@findex TYPE_CODE_FUNC
-@findex gdb.TYPE_CODE_FUNC
-@item gdb.TYPE_CODE_FUNC
-The type is a function.
-
-@findex TYPE_CODE_INT
-@findex gdb.TYPE_CODE_INT
-@item gdb.TYPE_CODE_INT
-The type is an integer type.
-
-@findex TYPE_CODE_FLT
-@findex gdb.TYPE_CODE_FLT
-@item gdb.TYPE_CODE_FLT
-A floating point type.
-
-@findex TYPE_CODE_VOID
-@findex gdb.TYPE_CODE_VOID
-@item gdb.TYPE_CODE_VOID
-The special type @code{void}.
-
-@findex TYPE_CODE_SET
-@findex gdb.TYPE_CODE_SET
-@item gdb.TYPE_CODE_SET
-A Pascal set type.
-
-@findex TYPE_CODE_RANGE
-@findex gdb.TYPE_CODE_RANGE
-@item gdb.TYPE_CODE_RANGE
-A range type, that is, an integer type with bounds.
-
-@findex TYPE_CODE_STRING
-@findex gdb.TYPE_CODE_STRING
-@item gdb.TYPE_CODE_STRING
-A string type. Note that this is only used for certain languages with
-language-defined string types; C strings are not represented this way.
-
-@findex TYPE_CODE_BITSTRING
-@findex gdb.TYPE_CODE_BITSTRING
-@item gdb.TYPE_CODE_BITSTRING
-A string of bits. It is deprecated.
-
-@findex TYPE_CODE_ERROR
-@findex gdb.TYPE_CODE_ERROR
-@item gdb.TYPE_CODE_ERROR
-An unknown or erroneous type.
-
-@findex TYPE_CODE_METHOD
-@findex gdb.TYPE_CODE_METHOD
-@item gdb.TYPE_CODE_METHOD
-A method type, as found in C@t{++} or Java.
-
-@findex TYPE_CODE_METHODPTR
-@findex gdb.TYPE_CODE_METHODPTR
-@item gdb.TYPE_CODE_METHODPTR
-A pointer-to-member-function.
-
-@findex TYPE_CODE_MEMBERPTR
-@findex gdb.TYPE_CODE_MEMBERPTR
-@item gdb.TYPE_CODE_MEMBERPTR
-A pointer-to-member.
-
-@findex TYPE_CODE_REF
-@findex gdb.TYPE_CODE_REF
-@item gdb.TYPE_CODE_REF
-A reference type.
-
-@findex TYPE_CODE_CHAR
-@findex gdb.TYPE_CODE_CHAR
-@item gdb.TYPE_CODE_CHAR
-A character type.
-
-@findex TYPE_CODE_BOOL
-@findex gdb.TYPE_CODE_BOOL
-@item gdb.TYPE_CODE_BOOL
-A boolean type.
-
-@findex TYPE_CODE_COMPLEX
-@findex gdb.TYPE_CODE_COMPLEX
-@item gdb.TYPE_CODE_COMPLEX
-A complex float type.
-
-@findex TYPE_CODE_TYPEDEF
-@findex gdb.TYPE_CODE_TYPEDEF
-@item gdb.TYPE_CODE_TYPEDEF
-A typedef to some other type.
-
-@findex TYPE_CODE_NAMESPACE
-@findex gdb.TYPE_CODE_NAMESPACE
-@item gdb.TYPE_CODE_NAMESPACE
-A C@t{++} namespace.
-
-@findex TYPE_CODE_DECFLOAT
-@findex gdb.TYPE_CODE_DECFLOAT
-@item gdb.TYPE_CODE_DECFLOAT
-A decimal floating point type.
-
-@findex TYPE_CODE_INTERNAL_FUNCTION
-@findex gdb.TYPE_CODE_INTERNAL_FUNCTION
-@item gdb.TYPE_CODE_INTERNAL_FUNCTION
-A function internal to @value{GDBN}. This is the type used to represent
-convenience functions.
-@end table
-
-Further support for types is provided in the @code{gdb.types}
-Python module (@pxref{gdb.types}).
-
-@node Pretty Printing API
-@subsubsection Pretty Printing API
-
-An example output is provided (@pxref{Pretty Printing}).
-
-A pretty-printer is just an object that holds a value and implements a
-specific interface, defined here.
-
-@defun pretty_printer.children (self)
-@value{GDBN} will call this method on a pretty-printer to compute the
-children of the pretty-printer's value.
-
-This method must return an object conforming to the Python iterator
-protocol. Each item returned by the iterator must be a tuple holding
-two elements. The first element is the ``name'' of the child; the
-second element is the child's value. The value can be any Python
-object which is convertible to a @value{GDBN} value.
-
-This method is optional. If it does not exist, @value{GDBN} will act
-as though the value has no children.
-@end defun
-
-@defun pretty_printer.display_hint (self)
-The CLI may call this method and use its result to change the
-formatting of a value. The result will also be supplied to an MI
-consumer as a @samp{displayhint} attribute of the variable being
-printed.
-
-This method is optional. If it does exist, this method must return a
-string.
-
-Some display hints are predefined by @value{GDBN}:
-
-@table @samp
-@item array
-Indicate that the object being printed is ``array-like''. The CLI
-uses this to respect parameters such as @code{set print elements} and
-@code{set print array}.
-
-@item map
-Indicate that the object being printed is ``map-like'', and that the
-children of this value can be assumed to alternate between keys and
-values.
-
-@item string
-Indicate that the object being printed is ``string-like''. If the
-printer's @code{to_string} method returns a Python string of some
-kind, then @value{GDBN} will call its internal language-specific
-string-printing function to format the string. For the CLI this means
-adding quotation marks, possibly escaping some characters, respecting
-@code{set print elements}, and the like.
-@end table
-@end defun
-
-@defun pretty_printer.to_string (self)
-@value{GDBN} will call this method to display the string
-representation of the value passed to the object's constructor.
-
-When printing from the CLI, if the @code{to_string} method exists,
-then @value{GDBN} will prepend its result to the values returned by
-@code{children}. Exactly how this formatting is done is dependent on
-the display hint, and may change as more hints are added. Also,
-depending on the print settings (@pxref{Print Settings}), the CLI may
-print just the result of @code{to_string} in a stack trace, omitting
-the result of @code{children}.
-
-If this method returns a string, it is printed verbatim.
-
-Otherwise, if this method returns an instance of @code{gdb.Value},
-then @value{GDBN} prints this value. This may result in a call to
-another pretty-printer.
-
-If instead the method returns a Python value which is convertible to a
-@code{gdb.Value}, then @value{GDBN} performs the conversion and prints
-the resulting value. Again, this may result in a call to another
-pretty-printer. Python scalars (integers, floats, and booleans) and
-strings are convertible to @code{gdb.Value}; other types are not.
-
-Finally, if this method returns @code{None} then no further operations
-are peformed in this method and nothing is printed.
-
-If the result is not one of these types, an exception is raised.
-@end defun
-
-@value{GDBN} provides a function which can be used to look up the
-default pretty-printer for a @code{gdb.Value}:
-
-@findex gdb.default_visualizer
-@defun gdb.default_visualizer (value)
-This function takes a @code{gdb.Value} object as an argument. If a
-pretty-printer for this value exists, then it is returned. If no such
-printer exists, then this returns @code{None}.
-@end defun
-
-@node Selecting Pretty-Printers
-@subsubsection Selecting Pretty-Printers
-
-The Python list @code{gdb.pretty_printers} contains an array of
-functions or callable objects that have been registered via addition
-as a pretty-printer. Printers in this list are called @code{global}
-printers, they're available when debugging all inferiors.
-Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
-Each @code{gdb.Objfile} also contains a @code{pretty_printers}
-attribute.
-
-Each function on these lists is passed a single @code{gdb.Value}
-argument and should return a pretty-printer object conforming to the
-interface definition above (@pxref{Pretty Printing API}). If a function
-cannot create a pretty-printer for the value, it should return
-@code{None}.
-
-@value{GDBN} first checks the @code{pretty_printers} attribute of each
-@code{gdb.Objfile} in the current program space and iteratively calls
-each enabled lookup routine in the list for that @code{gdb.Objfile}
-until it receives a pretty-printer object.
-If no pretty-printer is found in the objfile lists, @value{GDBN} then
-searches the pretty-printer list of the current program space,
-calling each enabled function until an object is returned.
-After these lists have been exhausted, it tries the global
-@code{gdb.pretty_printers} list, again calling each enabled function until an
-object is returned.
-
-The order in which the objfiles are searched is not specified. For a
-given list, functions are always invoked from the head of the list,
-and iterated over sequentially until the end of the list, or a printer
-object is returned.
-
-For various reasons a pretty-printer may not work.
-For example, the underlying data structure may have changed and
-the pretty-printer is out of date.
-
-The consequences of a broken pretty-printer are severe enough that
-@value{GDBN} provides support for enabling and disabling individual
-printers. For example, if @code{print frame-arguments} is on,
-a backtrace can become highly illegible if any argument is printed
-with a broken printer.
-
-Pretty-printers are enabled and disabled by attaching an @code{enabled}
-attribute to the registered function or callable object. If this attribute
-is present and its value is @code{False}, the printer is disabled, otherwise
-the printer is enabled.
-
-@node Writing a Pretty-Printer
-@subsubsection Writing a Pretty-Printer
-@cindex writing a pretty-printer
-
-A pretty-printer consists of two parts: a lookup function to detect
-if the type is supported, and the printer itself.
-
-Here is an example showing how a @code{std::string} printer might be
-written. @xref{Pretty Printing API}, for details on the API this class
-must provide.
-
-@smallexample
-class StdStringPrinter(object):
- "Print a std::string"
-
- def __init__(self, val):
- self.val = val
-
- def to_string(self):
- return self.val['_M_dataplus']['_M_p']
-
- def display_hint(self):
- return 'string'
-@end smallexample
-
-And here is an example showing how a lookup function for the printer
-example above might be written.
-
-@smallexample
-def str_lookup_function(val):
- lookup_tag = val.type.tag
- if lookup_tag == None:
- return None
- regex = re.compile("^std::basic_string<char,.*>$")
- if regex.match(lookup_tag):
- return StdStringPrinter(val)
- return None
-@end smallexample
-
-The example lookup function extracts the value's type, and attempts to
-match it to a type that it can pretty-print. If it is a type the
-printer can pretty-print, it will return a printer object. If not, it
-returns @code{None}.
-
-We recommend that you put your core pretty-printers into a Python
-package. If your pretty-printers are for use with a library, we
-further recommend embedding a version number into the package name.
-This practice will enable @value{GDBN} to load multiple versions of
-your pretty-printers at the same time, because they will have
-different names.
-
-You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
-can be evaluated multiple times without changing its meaning. An
-ideal auto-load file will consist solely of @code{import}s of your
-printer modules, followed by a call to a register pretty-printers with
-the current objfile.
-
-Taken as a whole, this approach will scale nicely to multiple
-inferiors, each potentially using a different library version.
-Embedding a version number in the Python package name will ensure that
-@value{GDBN} is able to load both sets of printers simultaneously.
-Then, because the search for pretty-printers is done by objfile, and
-because your auto-loaded code took care to register your library's
-printers with a specific objfile, @value{GDBN} will find the correct
-printers for the specific version of the library used by each
-inferior.
-
-To continue the @code{std::string} example (@pxref{Pretty Printing API}),
-this code might appear in @code{gdb.libstdcxx.v6}:
-
-@smallexample
-def register_printers(objfile):
- objfile.pretty_printers.append(str_lookup_function)
-@end smallexample
-
-@noindent
-And then the corresponding contents of the auto-load file would be:
-
-@smallexample
-import gdb.libstdcxx.v6
-gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
-@end smallexample
-
-The previous example illustrates a basic pretty-printer.
-There are a few things that can be improved on.
-The printer doesn't have a name, making it hard to identify in a
-list of installed printers. The lookup function has a name, but
-lookup functions can have arbitrary, even identical, names.
-
-Second, the printer only handles one type, whereas a library typically has
-several types. One could install a lookup function for each desired type
-in the library, but one could also have a single lookup function recognize
-several types. The latter is the conventional way this is handled.
-If a pretty-printer can handle multiple data types, then its
-@dfn{subprinters} are the printers for the individual data types.
-
-The @code{gdb.printing} module provides a formal way of solving these
-problems (@pxref{gdb.printing}).
-Here is another example that handles multiple types.
-
-These are the types we are going to pretty-print:
-
-@smallexample
-struct foo @{ int a, b; @};
-struct bar @{ struct foo x, y; @};
-@end smallexample
-
-Here are the printers:
-
-@smallexample
-class fooPrinter:
- """Print a foo object."""
-
- def __init__(self, val):
- self.val = val
-
- def to_string(self):
- return ("a=<" + str(self.val["a"]) +
- "> b=<" + str(self.val["b"]) + ">")
-
-class barPrinter:
- """Print a bar object."""
-
- def __init__(self, val):
- self.val = val
-
- def to_string(self):
- return ("x=<" + str(self.val["x"]) +
- "> y=<" + str(self.val["y"]) + ">")
-@end smallexample
-
-This example doesn't need a lookup function, that is handled by the
-@code{gdb.printing} module. Instead a function is provided to build up
-the object that handles the lookup.
-
-@smallexample
-import gdb.printing
-
-def build_pretty_printer():
- pp = gdb.printing.RegexpCollectionPrettyPrinter(
- "my_library")
- pp.add_printer('foo', '^foo$', fooPrinter)
- pp.add_printer('bar', '^bar$', barPrinter)
- return pp
-@end smallexample
-
-And here is the autoload support:
-
-@smallexample
-import gdb.printing
-import my_library
-gdb.printing.register_pretty_printer(
- gdb.current_objfile(),
- my_library.build_pretty_printer())
-@end smallexample
-
-Finally, when this printer is loaded into @value{GDBN}, here is the
-corresponding output of @samp{info pretty-printer}:
-
-@smallexample
-(gdb) info pretty-printer
-my_library.so:
- my_library
- foo
- bar
-@end smallexample
-
-@node Type Printing API
-@subsubsection Type Printing API
-@cindex type printing API for Python
-
-@value{GDBN} provides a way for Python code to customize type display.
-This is mainly useful for substituting canonical typedef names for
-types.
-
-@cindex type printer
-A @dfn{type printer} is just a Python object conforming to a certain
-protocol. A simple base class implementing the protocol is provided;
-see @ref{gdb.types}. A type printer must supply at least:
-
-@defivar type_printer enabled
-A boolean which is True if the printer is enabled, and False
-otherwise. This is manipulated by the @code{enable type-printer}
-and @code{disable type-printer} commands.
-@end defivar
-
-@defivar type_printer name
-The name of the type printer. This must be a string. This is used by
-the @code{enable type-printer} and @code{disable type-printer}
-commands.
-@end defivar
-
-@defmethod type_printer instantiate (self)
-This is called by @value{GDBN} at the start of type-printing. It is
-only called if the type printer is enabled. This method must return a
-new object that supplies a @code{recognize} method, as described below.
-@end defmethod
-
-
-When displaying a type, say via the @code{ptype} command, @value{GDBN}
-will compute a list of type recognizers. This is done by iterating
-first over the per-objfile type printers (@pxref{Objfiles In Python}),
-followed by the per-progspace type printers (@pxref{Progspaces In
-Python}), and finally the global type printers.
-
-@value{GDBN} will call the @code{instantiate} method of each enabled
-type printer. If this method returns @code{None}, then the result is
-ignored; otherwise, it is appended to the list of recognizers.
-
-Then, when @value{GDBN} is going to display a type name, it iterates
-over the list of recognizers. For each one, it calls the recognition
-function, stopping if the function returns a non-@code{None} value.
-The recognition function is defined as:
-
-@defmethod type_recognizer recognize (self, type)
-If @var{type} is not recognized, return @code{None}. Otherwise,
-return a string which is to be printed as the name of @var{type}.
-@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
-Python}).
-@end defmethod
-
-@value{GDBN} uses this two-pass approach so that type printers can
-efficiently cache information without holding on to it too long. For
-example, it can be convenient to look up type information in a type
-printer and hold it for a recognizer's lifetime; if a single pass were
-done then type printers would have to make use of the event system in
-order to avoid holding information that could become stale as the
-inferior changed.
-
-@node Frame Filter API
-@subsubsection Filtering Frames.
-@cindex frame filters api
-
-Frame filters are Python objects that manipulate the visibility of a
-frame or frames when a backtrace (@pxref{Backtrace}) is printed by
-@value{GDBN}.
-
-Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
-commands (@pxref{GDB/MI}), those that return a collection of frames
-are affected. The commands that work with frame filters are:
-
-@code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
-@code{-stack-list-frames}
-(@pxref{-stack-list-frames,, The -stack-list-frames command}),
-@code{-stack-list-variables} (@pxref{-stack-list-variables,, The
--stack-list-variables command}), @code{-stack-list-arguments}
-@pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
-@code{-stack-list-locals} (@pxref{-stack-list-locals,, The
--stack-list-locals command}).
-
-A frame filter works by taking an iterator as an argument, applying
-actions to the contents of that iterator, and returning another
-iterator (or, possibly, the same iterator it was provided in the case
-where the filter does not perform any operations). Typically, frame
-filters utilize tools such as the Python's @code{itertools} module to
-work with and create new iterators from the source iterator.
-Regardless of how a filter chooses to apply actions, it must not alter
-the underlying @value{GDBN} frame or frames, or attempt to alter the
-call-stack within @value{GDBN}. This preserves data integrity within
-@value{GDBN}. Frame filters are executed on a priority basis and care
-should be taken that some frame filters may have been executed before,
-and that some frame filters will be executed after.
-
-An important consideration when designing frame filters, and well
-worth reflecting upon, is that frame filters should avoid unwinding
-the call stack if possible. Some stacks can run very deep, into the
-tens of thousands in some cases. To search every frame when a frame
-filter executes may be too expensive at that step. The frame filter
-cannot know how many frames it has to iterate over, and it may have to
-iterate through them all. This ends up duplicating effort as
-@value{GDBN} performs this iteration when it prints the frames. If
-the filter can defer unwinding frames until frame decorators are
-executed, after the last filter has executed, it should. @xref{Frame
-Decorator API}, for more information on decorators. Also, there are
-examples for both frame decorators and filters in later chapters.
-@xref{Writing a Frame Filter}, for more information.
-
-The Python dictionary @code{gdb.frame_filters} contains key/object
-pairings that comprise a frame filter. Frame filters in this
-dictionary are called @code{global} frame filters, and they are
-available when debugging all inferiors. These frame filters must
-register with the dictionary directly. In addition to the
-@code{global} dictionary, there are other dictionaries that are loaded
-with different inferiors via auto-loading (@pxref{Python
-Auto-loading}). The two other areas where frame filter dictionaries
-can be found are: @code{gdb.Progspace} which contains a
-@code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
-object which also contains a @code{frame_filters} dictionary
-attribute.
-
-When a command is executed from @value{GDBN} that is compatible with
-frame filters, @value{GDBN} combines the @code{global},
-@code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
-loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
-several frames, and thus several object files, might be in use.
-@value{GDBN} then prunes any frame filter whose @code{enabled}
-attribute is @code{False}. This pruned list is then sorted according
-to the @code{priority} attribute in each filter.
-
-Once the dictionaries are combined, pruned and sorted, @value{GDBN}
-creates an iterator which wraps each frame in the call stack in a
-@code{FrameDecorator} object, and calls each filter in order. The
-output from the previous filter will always be the input to the next
-filter, and so on.
-
-Frame filters have a mandatory interface which each frame filter must
-implement, defined here:
-
-@defun FrameFilter.filter (iterator)
-@value{GDBN} will call this method on a frame filter when it has
-reached the order in the priority list for that filter.
-
-For example, if there are four frame filters:
-
-@smallexample
-Name Priority
-
-Filter1 5
-Filter2 10
-Filter3 100
-Filter4 1
-@end smallexample
-
-The order that the frame filters will be called is:
-
-@smallexample
-Filter3 -> Filter2 -> Filter1 -> Filter4
-@end smallexample
-
-Note that the output from @code{Filter3} is passed to the input of
-@code{Filter2}, and so on.
-
-This @code{filter} method is passed a Python iterator. This iterator
-contains a sequence of frame decorators that wrap each
-@code{gdb.Frame}, or a frame decorator that wraps another frame
-decorator. The first filter that is executed in the sequence of frame
-filters will receive an iterator entirely comprised of default
-@code{FrameDecorator} objects. However, after each frame filter is
-executed, the previous frame filter may have wrapped some or all of
-the frame decorators with their own frame decorator. As frame
-decorators must also conform to a mandatory interface, these
-decorators can be assumed to act in a uniform manner (@pxref{Frame
-Decorator API}).
-
-This method must return an object conforming to the Python iterator
-protocol. Each item in the iterator must be an object conforming to
-the frame decorator interface. If a frame filter does not wish to
-perform any operations on this iterator, it should return that
-iterator untouched.
-
-This method is not optional. If it does not exist, @value{GDBN} will
-raise and print an error.
-@end defun
-
-@defvar FrameFilter.name
-The @code{name} attribute must be Python string which contains the
-name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
-Management}). This attribute may contain any combination of letters
-or numbers. Care should be taken to ensure that it is unique. This
-attribute is mandatory.
-@end defvar
-
-@defvar FrameFilter.enabled
-The @code{enabled} attribute must be Python boolean. This attribute
-indicates to @value{GDBN} whether the frame filter is enabled, and
-should be considered when frame filters are executed. If
-@code{enabled} is @code{True}, then the frame filter will be executed
-when any of the backtrace commands detailed earlier in this chapter
-are executed. If @code{enabled} is @code{False}, then the frame
-filter will not be executed. This attribute is mandatory.
-@end defvar
-
-@defvar FrameFilter.priority
-The @code{priority} attribute must be Python integer. This attribute
-controls the order of execution in relation to other frame filters.
-There are no imposed limits on the range of @code{priority} other than
-it must be a valid integer. The higher the @code{priority} attribute,
-the sooner the frame filter will be executed in relation to other
-frame filters. Although @code{priority} can be negative, it is
-recommended practice to assume zero is the lowest priority that a
-frame filter can be assigned. Frame filters that have the same
-priority are executed in unsorted order in that priority slot. This
-attribute is mandatory.
-@end defvar
-
-@node Frame Decorator API
-@subsubsection Decorating Frames.
-@cindex frame decorator api
-
-Frame decorators are sister objects to frame filters (@pxref{Frame
-Filter API}). Frame decorators are applied by a frame filter and can
-only be used in conjunction with frame filters.
-
-The purpose of a frame decorator is to customize the printed content
-of each @code{gdb.Frame} in commands where frame filters are executed.
-This concept is called decorating a frame. Frame decorators decorate
-a @code{gdb.Frame} with Python code contained within each API call.
-This separates the actual data contained in a @code{gdb.Frame} from
-the decorated data produced by a frame decorator. This abstraction is
-necessary to maintain integrity of the data contained in each
-@code{gdb.Frame}.
-
-Frame decorators have a mandatory interface, defined below.
-
-@value{GDBN} already contains a frame decorator called
-@code{FrameDecorator}. This contains substantial amounts of
-boilerplate code to decorate the content of a @code{gdb.Frame}. It is
-recommended that other frame decorators inherit and extend this
-object, and only to override the methods needed.
-
-@defun FrameDecorator.elided (self)
-
-The @code{elided} method groups frames together in a hierarchical
-system. An example would be an interpreter, where multiple low-level
-frames make up a single call in the interpreted language. In this
-example, the frame filter would elide the low-level frames and present
-a single high-level frame, representing the call in the interpreted
-language, to the user.
-
-The @code{elided} function must return an iterable and this iterable
-must contain the frames that are being elided wrapped in a suitable
-frame decorator. If no frames are being elided this function may
-return an empty iterable, or @code{None}. Elided frames are indented
-from normal frames in a @code{CLI} backtrace, or in the case of
-@code{GDB/MI}, are placed in the @code{children} field of the eliding
-frame.
-
-It is the frame filter's task to also filter out the elided frames from
-the source iterator. This will avoid printing the frame twice.
-@end defun
-
-@defun FrameDecorator.function (self)
-
-This method returns the name of the function in the frame that is to
-be printed.
-
-This method must return a Python string describing the function, or
-@code{None}.
-
-If this function returns @code{None}, @value{GDBN} will not print any
-data for this field.
-@end defun
-
-@defun FrameDecorator.address (self)
-
-This method returns the address of the frame that is to be printed.
-
-This method must return a Python numeric integer type of sufficient
-size to describe the address of the frame, or @code{None}.
-
-If this function returns a @code{None}, @value{GDBN} will not print
-any data for this field.
-@end defun
-
-@defun FrameDecorator.filename (self)
-
-This method returns the filename and path associated with this frame.
-
-This method must return a Python string containing the filename and
-the path to the object file backing the frame, or @code{None}.
-
-If this function returns a @code{None}, @value{GDBN} will not print
-any data for this field.
-@end defun
-
-@defun FrameDecorator.line (self):
-
-This method returns the line number associated with the current
-position within the function addressed by this frame.
-
-This method must return a Python integer type, or @code{None}.
+@c Python docs live in a separate file.
+@include python.texi
-If this function returns a @code{None}, @value{GDBN} will not print
-any data for this field.
-@end defun
-
-@defun FrameDecorator.frame_args (self)
-@anchor{frame_args}
-
-This method must return an iterable, or @code{None}. Returning an
-empty iterable, or @code{None} means frame arguments will not be
-printed for this frame. This iterable must contain objects that
-implement two methods, described here.
-
-This object must implement a @code{argument} method which takes a
-single @code{self} parameter and must return a @code{gdb.Symbol}
-(@pxref{Symbols In Python}), or a Python string. The object must also
-implement a @code{value} method which takes a single @code{self}
-parameter and must return a @code{gdb.Value} (@pxref{Values From
-Inferior}), a Python value, or @code{None}. If the @code{value}
-method returns @code{None}, and the @code{argument} method returns a
-@code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
-the @code{gdb.Symbol} automatically.
-
-A brief example:
-
-@smallexample
-class SymValueWrapper():
-
- def __init__(self, symbol, value):
- self.sym = symbol
- self.val = value
-
- def value(self):
- return self.val
-
- def symbol(self):
- return self.sym
-
-class SomeFrameDecorator()
-...
-...
- def frame_args(self):
- args = []
- try:
- block = self.inferior_frame.block()
- except:
- return None
-
- # Iterate over all symbols in a block. Only add
- # symbols that are arguments.
- for sym in block:
- if not sym.is_argument:
- continue
- args.append(SymValueWrapper(sym,None))
-
- # Add example synthetic argument.
- args.append(SymValueWrapper(``foo'', 42))
-
- return args
-@end smallexample
-@end defun
-
-@defun FrameDecorator.frame_locals (self)
-
-This method must return an iterable or @code{None}. Returning an
-empty iterable, or @code{None} means frame local arguments will not be
-printed for this frame.
-
-The object interface, the description of the various strategies for
-reading frame locals, and the example are largely similar to those
-described in the @code{frame_args} function, (@pxref{frame_args,,The
-frame filter frame_args function}). Below is a modified example:
-
-@smallexample
-class SomeFrameDecorator()
-...
-...
- def frame_locals(self):
- vars = []
- try:
- block = self.inferior_frame.block()
- except:
- return None
-
- # Iterate over all symbols in a block. Add all
- # symbols, except arguments.
- for sym in block:
- if sym.is_argument:
- continue
- vars.append(SymValueWrapper(sym,None))
-
- # Add an example of a synthetic local variable.
- vars.append(SymValueWrapper(``bar'', 99))
-
- return vars
-@end smallexample
-@end defun
-
-@defun FrameDecorator.inferior_frame (self):
-
-This method must return the underlying @code{gdb.Frame} that this
-frame decorator is decorating. @value{GDBN} requires the underlying
-frame for internal frame information to determine how to print certain
-values when printing a frame.
-@end defun
-
-@node Writing a Frame Filter
-@subsubsection Writing a Frame Filter
-@cindex writing a frame filter
-
-There are three basic elements that a frame filter must implement: it
-must correctly implement the documented interface (@pxref{Frame Filter
-API}), it must register itself with @value{GDBN}, and finally, it must
-decide if it is to work on the data provided by @value{GDBN}. In all
-cases, whether it works on the iterator or not, each frame filter must
-return an iterator. A bare-bones frame filter follows the pattern in
-the following example.
-
-@smallexample
-import gdb
-
-class FrameFilter():
-
- def __init__(self):
- # Frame filter attribute creation.
- #
- # 'name' is the name of the filter that GDB will display.
- #
- # 'priority' is the priority of the filter relative to other
- # filters.
- #
- # 'enabled' is a boolean that indicates whether this filter is
- # enabled and should be executed.
-
- self.name = "Foo"
- self.priority = 100
- self.enabled = True
-
- # Register this frame filter with the global frame_filters
- # dictionary.
- gdb.frame_filters[self.name] = self
-
- def filter(self, frame_iter):
- # Just return the iterator.
- return frame_iter
-@end smallexample
-
-The frame filter in the example above implements the three
-requirements for all frame filters. It implements the API, self
-registers, and makes a decision on the iterator (in this case, it just
-returns the iterator untouched).
-
-The first step is attribute creation and assignment, and as shown in
-the comments the filter assigns the following attributes: @code{name},
-@code{priority} and whether the filter should be enabled with the
-@code{enabled} attribute.
-
-The second step is registering the frame filter with the dictionary or
-dictionaries that the frame filter has interest in. As shown in the
-comments, this filter just registers itself with the global dictionary
-@code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
-is a dictionary that is initialized in the @code{gdb} module when
-@value{GDBN} starts. What dictionary a filter registers with is an
-important consideration. Generally, if a filter is specific to a set
-of code, it should be registered either in the @code{objfile} or
-@code{progspace} dictionaries as they are specific to the program
-currently loaded in @value{GDBN}. The global dictionary is always
-present in @value{GDBN} and is never unloaded. Any filters registered
-with the global dictionary will exist until @value{GDBN} exits. To
-avoid filters that may conflict, it is generally better to register
-frame filters against the dictionaries that more closely align with
-the usage of the filter currently in question. @xref{Python
-Auto-loading}, for further information on auto-loading Python scripts.
-
-@value{GDBN} takes a hands-off approach to frame filter registration,
-therefore it is the frame filter's responsibility to ensure
-registration has occurred, and that any exceptions are handled
-appropriately. In particular, you may wish to handle exceptions
-relating to Python dictionary key uniqueness. It is mandatory that
-the dictionary key is the same as frame filter's @code{name}
-attribute. When a user manages frame filters (@pxref{Frame Filter
-Management}), the names @value{GDBN} will display are those contained
-in the @code{name} attribute.
-
-The final step of this example is the implementation of the
-@code{filter} method. As shown in the example comments, we define the
-@code{filter} method and note that the method must take an iterator,
-and also must return an iterator. In this bare-bones example, the
-frame filter is not very useful as it just returns the iterator
-untouched. However this is a valid operation for frame filters that
-have the @code{enabled} attribute set, but decide not to operate on
-any frames.
-
-In the next example, the frame filter operates on all frames and
-utilizes a frame decorator to perform some work on the frames.
-@xref{Frame Decorator API}, for further information on the frame
-decorator interface.
-
-This example works on inlined frames. It highlights frames which are
-inlined by tagging them with an ``[inlined]'' tag. By applying a
-frame decorator to all frames with the Python @code{itertools imap}
-method, the example defers actions to the frame decorator. Frame
-decorators are only processed when @value{GDBN} prints the backtrace.
-
-This introduces a new decision making topic: whether to perform
-decision making operations at the filtering step, or at the printing
-step. In this example's approach, it does not perform any filtering
-decisions at the filtering step beyond mapping a frame decorator to
-each frame. This allows the actual decision making to be performed
-when each frame is printed. This is an important consideration, and
-well worth reflecting upon when designing a frame filter. An issue
-that frame filters should avoid is unwinding the stack if possible.
-Some stacks can run very deep, into the tens of thousands in some
-cases. To search every frame to determine if it is inlined ahead of
-time may be too expensive at the filtering step. The frame filter
-cannot know how many frames it has to iterate over, and it would have
-to iterate through them all. This ends up duplicating effort as
-@value{GDBN} performs this iteration when it prints the frames.
-
-In this example decision making can be deferred to the printing step.
-As each frame is printed, the frame decorator can examine each frame
-in turn when @value{GDBN} iterates. From a performance viewpoint,
-this is the most appropriate decision to make as it avoids duplicating
-the effort that the printing step would undertake anyway. Also, if
-there are many frame filters unwinding the stack during filtering, it
-can substantially delay the printing of the backtrace which will
-result in large memory usage, and a poor user experience.
-
-@smallexample
-class InlineFilter():
-
- def __init__(self):
- self.name = "InlinedFrameFilter"
- self.priority = 100
- self.enabled = True
- gdb.frame_filters[self.name] = self
-
- def filter(self, frame_iter):
- frame_iter = itertools.imap(InlinedFrameDecorator,
- frame_iter)
- return frame_iter
-@end smallexample
-
-This frame filter is somewhat similar to the earlier example, except
-that the @code{filter} method applies a frame decorator object called
-@code{InlinedFrameDecorator} to each element in the iterator. The
-@code{imap} Python method is light-weight. It does not proactively
-iterate over the iterator, but rather creates a new iterator which
-wraps the existing one.
-
-Below is the frame decorator for this example.
-
-@smallexample
-class InlinedFrameDecorator(FrameDecorator):
-
- def __init__(self, fobj):
- super(InlinedFrameDecorator, self).__init__(fobj)
-
- def function(self):
- frame = fobj.inferior_frame()
- name = str(frame.name())
-
- if frame.type() == gdb.INLINE_FRAME:
- name = name + " [inlined]"
-
- return name
-@end smallexample
-
-This frame decorator only defines and overrides the @code{function}
-method. It lets the supplied @code{FrameDecorator}, which is shipped
-with @value{GDBN}, perform the other work associated with printing
-this frame.
-
-The combination of these two objects create this output from a
-backtrace:
-
-@smallexample
-#0 0x004004e0 in bar () at inline.c:11
-#1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
-#2 0x00400566 in main () at inline.c:31
-@end smallexample
-
-So in the case of this example, a frame decorator is applied to all
-frames, regardless of whether they may be inlined or not. As
-@value{GDBN} iterates over the iterator produced by the frame filters,
-@value{GDBN} executes each frame decorator which then makes a decision
-on what to print in the @code{function} callback. Using a strategy
-like this is a way to defer decisions on the frame content to printing
-time.
-
-@subheading Eliding Frames
-
-It might be that the above example is not desirable for representing
-inlined frames, and a hierarchical approach may be preferred. If we
-want to hierarchically represent frames, the @code{elided} frame
-decorator interface might be preferable.
-
-This example approaches the issue with the @code{elided} method. This
-example is quite long, but very simplistic. It is out-of-scope for
-this section to write a complete example that comprehensively covers
-all approaches of finding and printing inlined frames. However, this
-example illustrates the approach an author might use.
-
-This example comprises of three sections.
-
-@smallexample
-class InlineFrameFilter():
-
- def __init__(self):
- self.name = "InlinedFrameFilter"
- self.priority = 100
- self.enabled = True
- gdb.frame_filters[self.name] = self
-
- def filter(self, frame_iter):
- return ElidingInlineIterator(frame_iter)
-@end smallexample
-
-This frame filter is very similar to the other examples. The only
-difference is this frame filter is wrapping the iterator provided to
-it (@code{frame_iter}) with a custom iterator called
-@code{ElidingInlineIterator}. This again defers actions to when
-@value{GDBN} prints the backtrace, as the iterator is not traversed
-until printing.
-
-The iterator for this example is as follows. It is in this section of
-the example where decisions are made on the content of the backtrace.
-
-@smallexample
-class ElidingInlineIterator:
- def __init__(self, ii):
- self.input_iterator = ii
-
- def __iter__(self):
- return self
-
- def next(self):
- frame = next(self.input_iterator)
-
- if frame.inferior_frame().type() != gdb.INLINE_FRAME:
- return frame
-
- try:
- eliding_frame = next(self.input_iterator)
- except StopIteration:
- return frame
- return ElidingFrameDecorator(eliding_frame, [frame])
-@end smallexample
-
-This iterator implements the Python iterator protocol. When the
-@code{next} function is called (when @value{GDBN} prints each frame),
-the iterator checks if this frame decorator, @code{frame}, is wrapping
-an inlined frame. If it is not, it returns the existing frame decorator
-untouched. If it is wrapping an inlined frame, it assumes that the
-inlined frame was contained within the next oldest frame,
-@code{eliding_frame}, which it fetches. It then creates and returns a
-frame decorator, @code{ElidingFrameDecorator}, which contains both the
-elided frame, and the eliding frame.
-
-@smallexample
-class ElidingInlineDecorator(FrameDecorator):
-
- def __init__(self, frame, elided_frames):
- super(ElidingInlineDecorator, self).__init__(frame)
- self.frame = frame
- self.elided_frames = elided_frames
-
- def elided(self):
- return iter(self.elided_frames)
-@end smallexample
-
-This frame decorator overrides one function and returns the inlined
-frame in the @code{elided} method. As before it lets
-@code{FrameDecorator} do the rest of the work involved in printing
-this frame. This produces the following output.
-
-@smallexample
-#0 0x004004e0 in bar () at inline.c:11
-#2 0x00400529 in main () at inline.c:25
- #1 0x00400529 in max (b=6, a=12) at inline.c:15
-@end smallexample
-
-In that output, @code{max} which has been inlined into @code{main} is
-printed hierarchically. Another approach would be to combine the
-@code{function} method, and the @code{elided} method to both print a
-marker in the inlined frame, and also show the hierarchical
-relationship.
-
-@node Inferiors In Python
-@subsubsection Inferiors In Python
-@cindex inferiors in Python
-
-@findex gdb.Inferior
-Programs which are being run under @value{GDBN} are called inferiors
-(@pxref{Inferiors and Programs}). Python scripts can access
-information about and manipulate inferiors controlled by @value{GDBN}
-via objects of the @code{gdb.Inferior} class.
-
-The following inferior-related functions are available in the @code{gdb}
-module:
-
-@defun gdb.inferiors ()
-Return a tuple containing all inferior objects.
-@end defun
-
-@defun gdb.selected_inferior ()
-Return an object representing the current inferior.
-@end defun
-
-A @code{gdb.Inferior} object has the following attributes:
-
-@defvar Inferior.num
-ID of inferior, as assigned by GDB.
-@end defvar
-
-@defvar Inferior.pid
-Process ID of the inferior, as assigned by the underlying operating
-system.
-@end defvar
-
-@defvar Inferior.was_attached
-Boolean signaling whether the inferior was created using `attach', or
-started by @value{GDBN} itself.
-@end defvar
-
-A @code{gdb.Inferior} object has the following methods:
-
-@defun Inferior.is_valid ()
-Returns @code{True} if the @code{gdb.Inferior} object is valid,
-@code{False} if not. A @code{gdb.Inferior} object will become invalid
-if the inferior no longer exists within @value{GDBN}. All other
-@code{gdb.Inferior} methods will throw an exception if it is invalid
-at the time the method is called.
-@end defun
-
-@defun Inferior.threads ()
-This method returns a tuple holding all the threads which are valid
-when it is called. If there are no valid threads, the method will
-return an empty tuple.
-@end defun
-
-@findex Inferior.read_memory
-@defun Inferior.read_memory (address, length)
-Read @var{length} bytes of memory from the inferior, starting at
-@var{address}. Returns a buffer object, which behaves much like an array
-or a string. It can be modified and given to the
-@code{Inferior.write_memory} function. In @code{Python} 3, the return
-value is a @code{memoryview} object.
-@end defun
-
-@findex Inferior.write_memory
-@defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
-Write the contents of @var{buffer} to the inferior, starting at
-@var{address}. The @var{buffer} parameter must be a Python object
-which supports the buffer protocol, i.e., a string, an array or the
-object returned from @code{Inferior.read_memory}. If given, @var{length}
-determines the number of bytes from @var{buffer} to be written.
-@end defun
-
-@findex gdb.search_memory
-@defun Inferior.search_memory (address, length, pattern)
-Search a region of the inferior memory starting at @var{address} with
-the given @var{length} using the search pattern supplied in
-@var{pattern}. The @var{pattern} parameter must be a Python object
-which supports the buffer protocol, i.e., a string, an array or the
-object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
-containing the address where the pattern was found, or @code{None} if
-the pattern could not be found.
-@end defun
-
-@node Events In Python
-@subsubsection Events In Python
-@cindex inferior events in Python
-
-@value{GDBN} provides a general event facility so that Python code can be
-notified of various state changes, particularly changes that occur in
-the inferior.
-
-An @dfn{event} is just an object that describes some state change. The
-type of the object and its attributes will vary depending on the details
-of the change. All the existing events are described below.
-
-In order to be notified of an event, you must register an event handler
-with an @dfn{event registry}. An event registry is an object in the
-@code{gdb.events} module which dispatches particular events. A registry
-provides methods to register and unregister event handlers:
-
-@defun EventRegistry.connect (object)
-Add the given callable @var{object} to the registry. This object will be
-called when an event corresponding to this registry occurs.
-@end defun
-
-@defun EventRegistry.disconnect (object)
-Remove the given @var{object} from the registry. Once removed, the object
-will no longer receive notifications of events.
-@end defun
-
-Here is an example:
-
-@smallexample
-def exit_handler (event):
- print "event type: exit"
- print "exit code: %d" % (event.exit_code)
-
-gdb.events.exited.connect (exit_handler)
-@end smallexample
-
-In the above example we connect our handler @code{exit_handler} to the
-registry @code{events.exited}. Once connected, @code{exit_handler} gets
-called when the inferior exits. The argument @dfn{event} in this example is
-of type @code{gdb.ExitedEvent}. As you can see in the example the
-@code{ExitedEvent} object has an attribute which indicates the exit code of
-the inferior.
-
-The following is a listing of the event registries that are available and
-details of the events they emit:
-
-@table @code
-
-@item events.cont
-Emits @code{gdb.ThreadEvent}.
-
-Some events can be thread specific when @value{GDBN} is running in non-stop
-mode. When represented in Python, these events all extend
-@code{gdb.ThreadEvent}. Note, this event is not emitted directly; instead,
-events which are emitted by this or other modules might extend this event.
-Examples of these events are @code{gdb.BreakpointEvent} and
-@code{gdb.ContinueEvent}.
-
-@defvar ThreadEvent.inferior_thread
-In non-stop mode this attribute will be set to the specific thread which was
-involved in the emitted event. Otherwise, it will be set to @code{None}.
-@end defvar
-
-Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
-
-This event indicates that the inferior has been continued after a stop. For
-inherited attribute refer to @code{gdb.ThreadEvent} above.
-
-@item events.exited
-Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
-@code{events.ExitedEvent} has two attributes:
-@defvar ExitedEvent.exit_code
-An integer representing the exit code, if available, which the inferior
-has returned. (The exit code could be unavailable if, for example,
-@value{GDBN} detaches from the inferior.) If the exit code is unavailable,
-the attribute does not exist.
-@end defvar
-@defvar ExitedEvent inferior
-A reference to the inferior which triggered the @code{exited} event.
-@end defvar
-
-@item events.stop
-Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
-
-Indicates that the inferior has stopped. All events emitted by this registry
-extend StopEvent. As a child of @code{gdb.ThreadEvent}, @code{gdb.StopEvent}
-will indicate the stopped thread when @value{GDBN} is running in non-stop
-mode. Refer to @code{gdb.ThreadEvent} above for more details.
-
-Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
-
-This event indicates that the inferior or one of its threads has received as
-signal. @code{gdb.SignalEvent} has the following attributes:
-
-@defvar SignalEvent.stop_signal
-A string representing the signal received by the inferior. A list of possible
-signal values can be obtained by running the command @code{info signals} in
-the @value{GDBN} command prompt.
-@end defvar
-
-Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
-
-@code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
-been hit, and has the following attributes:
-
-@defvar BreakpointEvent.breakpoints
-A sequence containing references to all the breakpoints (type
-@code{gdb.Breakpoint}) that were hit.
-@xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object.
-@end defvar
-@defvar BreakpointEvent.breakpoint
-A reference to the first breakpoint that was hit.
-This function is maintained for backward compatibility and is now deprecated
-in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
-@end defvar
-
-@item events.new_objfile
-Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
-been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
-
-@defvar NewObjFileEvent.new_objfile
-A reference to the object file (@code{gdb.Objfile}) which has been loaded.
-@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
-@end defvar
-
-@end table
-
-@node Threads In Python
-@subsubsection Threads In Python
-@cindex threads in python
-
-@findex gdb.InferiorThread
-Python scripts can access information about, and manipulate inferior threads
-controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
-
-The following thread-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.selected_thread
-@defun gdb.selected_thread ()
-This function returns the thread object for the selected thread. If there
-is no selected thread, this will return @code{None}.
-@end defun
-
-A @code{gdb.InferiorThread} object has the following attributes:
-
-@defvar InferiorThread.name
-The name of the thread. If the user specified a name using
-@code{thread name}, then this returns that name. Otherwise, if an
-OS-supplied name is available, then it is returned. Otherwise, this
-returns @code{None}.
-
-This attribute can be assigned to. The new value must be a string
-object, which sets the new name, or @code{None}, which removes any
-user-specified thread name.
-@end defvar
-
-@defvar InferiorThread.num
-ID of the thread, as assigned by GDB.
-@end defvar
-
-@defvar InferiorThread.ptid
-ID of the thread, as assigned by the operating system. This attribute is a
-tuple containing three integers. The first is the Process ID (PID); the second
-is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
-Either the LWPID or TID may be 0, which indicates that the operating system
-does not use that identifier.
-@end defvar
-
-A @code{gdb.InferiorThread} object has the following methods:
-
-@defun InferiorThread.is_valid ()
-Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
-@code{False} if not. A @code{gdb.InferiorThread} object will become
-invalid if the thread exits, or the inferior that the thread belongs
-is deleted. All other @code{gdb.InferiorThread} methods will throw an
-exception if it is invalid at the time the method is called.
-@end defun
-
-@defun InferiorThread.switch ()
-This changes @value{GDBN}'s currently selected thread to the one represented
-by this object.
-@end defun
-
-@defun InferiorThread.is_stopped ()
-Return a Boolean indicating whether the thread is stopped.
-@end defun
-
-@defun InferiorThread.is_running ()
-Return a Boolean indicating whether the thread is running.
-@end defun
-
-@defun InferiorThread.is_exited ()
-Return a Boolean indicating whether the thread is exited.
-@end defun
-
-@node Commands In Python
-@subsubsection Commands In Python
-
-@cindex commands in python
-@cindex python commands
-You can implement new @value{GDBN} CLI commands in Python. A CLI
-command is implemented using an instance of the @code{gdb.Command}
-class, most commonly using a subclass.
-
-@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
-The object initializer for @code{Command} registers the new command
-with @value{GDBN}. This initializer is normally invoked from the
-subclass' own @code{__init__} method.
-
-@var{name} is the name of the command. If @var{name} consists of
-multiple words, then the initial words are looked for as prefix
-commands. In this case, if one of the prefix commands does not exist,
-an exception is raised.
-
-There is no support for multi-line commands.
-
-@var{command_class} should be one of the @samp{COMMAND_} constants
-defined below. This argument tells @value{GDBN} how to categorize the
-new command in the help system.
-
-@var{completer_class} is an optional argument. If given, it should be
-one of the @samp{COMPLETE_} constants defined below. This argument
-tells @value{GDBN} how to perform completion for this command. If not
-given, @value{GDBN} will attempt to complete using the object's
-@code{complete} method (see below); if no such method is found, an
-error will occur when completion is attempted.
-
-@var{prefix} is an optional argument. If @code{True}, then the new
-command is a prefix command; sub-commands of this command may be
-registered.
-
-The help text for the new command is taken from the Python
-documentation string for the command's class, if there is one. If no
-documentation string is provided, the default value ``This command is
-not documented.'' is used.
-@end defun
-
-@cindex don't repeat Python command
-@defun Command.dont_repeat ()
-By default, a @value{GDBN} command is repeated when the user enters a
-blank line at the command prompt. A command can suppress this
-behavior by invoking the @code{dont_repeat} method. This is similar
-to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
-@end defun
-
-@defun Command.invoke (argument, from_tty)
-This method is called by @value{GDBN} when this command is invoked.
-
-@var{argument} is a string. It is the argument to the command, after
-leading and trailing whitespace has been stripped.
-
-@var{from_tty} is a boolean argument. When true, this means that the
-command was entered by the user at the terminal; when false it means
-that the command came from elsewhere.
-
-If this method throws an exception, it is turned into a @value{GDBN}
-@code{error} call. Otherwise, the return value is ignored.
-
-@findex gdb.string_to_argv
-To break @var{argument} up into an argv-like string use
-@code{gdb.string_to_argv}. This function behaves identically to
-@value{GDBN}'s internal argument lexer @code{buildargv}.
-It is recommended to use this for consistency.
-Arguments are separated by spaces and may be quoted.
-Example:
-
-@smallexample
-print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
-['1', '2 "3', '4 "5', "6 '7"]
-@end smallexample
-
-@end defun
-
-@cindex completion of Python commands
-@defun Command.complete (text, word)
-This method is called by @value{GDBN} when the user attempts
-completion on this command. All forms of completion are handled by
-this method, that is, the @key{TAB} and @key{M-?} key bindings
-(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
-complete}).
-
-The arguments @var{text} and @var{word} are both strings. @var{text}
-holds the complete command line up to the cursor's location.
-@var{word} holds the last word of the command line; this is computed
-using a word-breaking heuristic.
-
-The @code{complete} method can return several values:
-@itemize @bullet
-@item
-If the return value is a sequence, the contents of the sequence are
-used as the completions. It is up to @code{complete} to ensure that the
-contents actually do complete the word. A zero-length sequence is
-allowed, it means that there were no completions available. Only
-string elements of the sequence are used; other elements in the
-sequence are ignored.
-
-@item
-If the return value is one of the @samp{COMPLETE_} constants defined
-below, then the corresponding @value{GDBN}-internal completion
-function is invoked, and its result is used.
-
-@item
-All other results are treated as though there were no available
-completions.
-@end itemize
-@end defun
-
-When a new command is registered, it must be declared as a member of
-some general class of commands. This is used to classify top-level
-commands in the on-line help system; note that prefix commands are not
-listed under their own category but rather that of their top-level
-command. The available classifications are represented by constants
-defined in the @code{gdb} module:
-
-@table @code
-@findex COMMAND_NONE
-@findex gdb.COMMAND_NONE
-@item gdb.COMMAND_NONE
-The command does not belong to any particular class. A command in
-this category will not be displayed in any of the help categories.
-
-@findex COMMAND_RUNNING
-@findex gdb.COMMAND_RUNNING
-@item gdb.COMMAND_RUNNING
-The command is related to running the inferior. For example,
-@code{start}, @code{step}, and @code{continue} are in this category.
-Type @kbd{help running} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_DATA
-@findex gdb.COMMAND_DATA
-@item gdb.COMMAND_DATA
-The command is related to data or variables. For example,
-@code{call}, @code{find}, and @code{print} are in this category. Type
-@kbd{help data} at the @value{GDBN} prompt to see a list of commands
-in this category.
-
-@findex COMMAND_STACK
-@findex gdb.COMMAND_STACK
-@item gdb.COMMAND_STACK
-The command has to do with manipulation of the stack. For example,
-@code{backtrace}, @code{frame}, and @code{return} are in this
-category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
-list of commands in this category.
-
-@findex COMMAND_FILES
-@findex gdb.COMMAND_FILES
-@item gdb.COMMAND_FILES
-This class is used for file-related commands. For example,
-@code{file}, @code{list} and @code{section} are in this category.
-Type @kbd{help files} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_SUPPORT
-@findex gdb.COMMAND_SUPPORT
-@item gdb.COMMAND_SUPPORT
-This should be used for ``support facilities'', generally meaning
-things that are useful to the user when interacting with @value{GDBN},
-but not related to the state of the inferior. For example,
-@code{help}, @code{make}, and @code{shell} are in this category. Type
-@kbd{help support} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_STATUS
-@findex gdb.COMMAND_STATUS
-@item gdb.COMMAND_STATUS
-The command is an @samp{info}-related command, that is, related to the
-state of @value{GDBN} itself. For example, @code{info}, @code{macro},
-and @code{show} are in this category. Type @kbd{help status} at the
-@value{GDBN} prompt to see a list of commands in this category.
-
-@findex COMMAND_BREAKPOINTS
-@findex gdb.COMMAND_BREAKPOINTS
-@item gdb.COMMAND_BREAKPOINTS
-The command has to do with breakpoints. For example, @code{break},
-@code{clear}, and @code{delete} are in this category. Type @kbd{help
-breakpoints} at the @value{GDBN} prompt to see a list of commands in
-this category.
-
-@findex COMMAND_TRACEPOINTS
-@findex gdb.COMMAND_TRACEPOINTS
-@item gdb.COMMAND_TRACEPOINTS
-The command has to do with tracepoints. For example, @code{trace},
-@code{actions}, and @code{tfind} are in this category. Type
-@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
-commands in this category.
-
-@findex COMMAND_USER
-@findex gdb.COMMAND_USER
-@item gdb.COMMAND_USER
-The command is a general purpose command for the user, and typically
-does not fit in one of the other categories.
-Type @kbd{help user-defined} at the @value{GDBN} prompt to see
-a list of commands in this category, as well as the list of gdb macros
-(@pxref{Sequences}).
-
-@findex COMMAND_OBSCURE
-@findex gdb.COMMAND_OBSCURE
-@item gdb.COMMAND_OBSCURE
-The command is only used in unusual circumstances, or is not of
-general interest to users. For example, @code{checkpoint},
-@code{fork}, and @code{stop} are in this category. Type @kbd{help
-obscure} at the @value{GDBN} prompt to see a list of commands in this
-category.
-
-@findex COMMAND_MAINTENANCE
-@findex gdb.COMMAND_MAINTENANCE
-@item gdb.COMMAND_MAINTENANCE
-The command is only useful to @value{GDBN} maintainers. The
-@code{maintenance} and @code{flushregs} commands are in this category.
-Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
-commands in this category.
-@end table
-
-A new command can use a predefined completion function, either by
-specifying it via an argument at initialization, or by returning it
-from the @code{complete} method. These predefined completion
-constants are all defined in the @code{gdb} module:
-
-@table @code
-@findex COMPLETE_NONE
-@findex gdb.COMPLETE_NONE
-@item gdb.COMPLETE_NONE
-This constant means that no completion should be done.
-
-@findex COMPLETE_FILENAME
-@findex gdb.COMPLETE_FILENAME
-@item gdb.COMPLETE_FILENAME
-This constant means that filename completion should be performed.
-
-@findex COMPLETE_LOCATION
-@findex gdb.COMPLETE_LOCATION
-@item gdb.COMPLETE_LOCATION
-This constant means that location completion should be done.
-@xref{Specify Location}.
-
-@findex COMPLETE_COMMAND
-@findex gdb.COMPLETE_COMMAND
-@item gdb.COMPLETE_COMMAND
-This constant means that completion should examine @value{GDBN}
-command names.
-
-@findex COMPLETE_SYMBOL
-@findex gdb.COMPLETE_SYMBOL
-@item gdb.COMPLETE_SYMBOL
-This constant means that completion should be done using symbol names
-as the source.
-
-@findex COMPLETE_EXPRESSION
-@findex gdb.COMPLETE_EXPRESSION
-@item gdb.COMPLETE_EXPRESSION
-This constant means that completion should be done on expressions.
-Often this means completing on symbol names, but some language
-parsers also have support for completing on field names.
-@end table
-
-The following code snippet shows how a trivial CLI command can be
-implemented in Python:
-
-@smallexample
-class HelloWorld (gdb.Command):
- """Greet the whole world."""
-
- def __init__ (self):
- super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
-
- def invoke (self, arg, from_tty):
- print "Hello, World!"
-
-HelloWorld ()
-@end smallexample
-
-The last line instantiates the class, and is necessary to trigger the
-registration of the command with @value{GDBN}. Depending on how the
-Python code is read into @value{GDBN}, you may need to import the
-@code{gdb} module explicitly.
-
-@node Parameters In Python
-@subsubsection Parameters In Python
-
-@cindex parameters in python
-@cindex python parameters
-@tindex gdb.Parameter
-@tindex Parameter
-You can implement new @value{GDBN} parameters using Python. A new
-parameter is implemented as an instance of the @code{gdb.Parameter}
-class.
-
-Parameters are exposed to the user via the @code{set} and
-@code{show} commands. @xref{Help}.
-
-There are many parameters that already exist and can be set in
-@value{GDBN}. Two examples are: @code{set follow fork} and
-@code{set charset}. Setting these parameters influences certain
-behavior in @value{GDBN}. Similarly, you can define parameters that
-can be used to influence behavior in custom Python scripts and commands.
-
-@defun Parameter.__init__ (name, @var{command-class}, @var{parameter-class} @r{[}, @var{enum-sequence}@r{]})
-The object initializer for @code{Parameter} registers the new
-parameter with @value{GDBN}. This initializer is normally invoked
-from the subclass' own @code{__init__} method.
-
-@var{name} is the name of the new parameter. If @var{name} consists
-of multiple words, then the initial words are looked for as prefix
-parameters. An example of this can be illustrated with the
-@code{set print} set of parameters. If @var{name} is
-@code{print foo}, then @code{print} will be searched as the prefix
-parameter. In this case the parameter can subsequently be accessed in
-@value{GDBN} as @code{set print foo}.
-
-If @var{name} consists of multiple words, and no prefix parameter group
-can be found, an exception is raised.
-
-@var{command-class} should be one of the @samp{COMMAND_} constants
-(@pxref{Commands In Python}). This argument tells @value{GDBN} how to
-categorize the new parameter in the help system.
-
-@var{parameter-class} should be one of the @samp{PARAM_} constants
-defined below. This argument tells @value{GDBN} the type of the new
-parameter; this information is used for input validation and
-completion.
-
-If @var{parameter-class} is @code{PARAM_ENUM}, then
-@var{enum-sequence} must be a sequence of strings. These strings
-represent the possible values for the parameter.
-
-If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
-of a fourth argument will cause an exception to be thrown.
-
-The help text for the new parameter is taken from the Python
-documentation string for the parameter's class, if there is one. If
-there is no documentation string, a default value is used.
-@end defun
-
-@defvar Parameter.set_doc
-If this attribute exists, and is a string, then its value is used as
-the help text for this parameter's @code{set} command. The value is
-examined when @code{Parameter.__init__} is invoked; subsequent changes
-have no effect.
-@end defvar
-
-@defvar Parameter.show_doc
-If this attribute exists, and is a string, then its value is used as
-the help text for this parameter's @code{show} command. The value is
-examined when @code{Parameter.__init__} is invoked; subsequent changes
-have no effect.
-@end defvar
-
-@defvar Parameter.value
-The @code{value} attribute holds the underlying value of the
-parameter. It can be read and assigned to just as any other
-attribute. @value{GDBN} does validation when assignments are made.
-@end defvar
-
-There are two methods that should be implemented in any
-@code{Parameter} class. These are:
-
-@defun Parameter.get_set_string (self)
-@value{GDBN} will call this method when a @var{parameter}'s value has
-been changed via the @code{set} API (for example, @kbd{set foo off}).
-The @code{value} attribute has already been populated with the new
-value and may be used in output. This method must return a string.
-@end defun
-
-@defun Parameter.get_show_string (self, svalue)
-@value{GDBN} will call this method when a @var{parameter}'s
-@code{show} API has been invoked (for example, @kbd{show foo}). The
-argument @code{svalue} receives the string representation of the
-current value. This method must return a string.
-@end defun
-
-When a new parameter is defined, its type must be specified. The
-available types are represented by constants defined in the @code{gdb}
-module:
-
-@table @code
-@findex PARAM_BOOLEAN
-@findex gdb.PARAM_BOOLEAN
-@item gdb.PARAM_BOOLEAN
-The value is a plain boolean. The Python boolean values, @code{True}
-and @code{False} are the only valid values.
-
-@findex PARAM_AUTO_BOOLEAN
-@findex gdb.PARAM_AUTO_BOOLEAN
-@item gdb.PARAM_AUTO_BOOLEAN
-The value has three possible states: true, false, and @samp{auto}. In
-Python, true and false are represented using boolean constants, and
-@samp{auto} is represented using @code{None}.
-
-@findex PARAM_UINTEGER
-@findex gdb.PARAM_UINTEGER
-@item gdb.PARAM_UINTEGER
-The value is an unsigned integer. The value of 0 should be
-interpreted to mean ``unlimited''.
-
-@findex PARAM_INTEGER
-@findex gdb.PARAM_INTEGER
-@item gdb.PARAM_INTEGER
-The value is a signed integer. The value of 0 should be interpreted
-to mean ``unlimited''.
-
-@findex PARAM_STRING
-@findex gdb.PARAM_STRING
-@item gdb.PARAM_STRING
-The value is a string. When the user modifies the string, any escape
-sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
-translated into corresponding characters and encoded into the current
-host charset.
-
-@findex PARAM_STRING_NOESCAPE
-@findex gdb.PARAM_STRING_NOESCAPE
-@item gdb.PARAM_STRING_NOESCAPE
-The value is a string. When the user modifies the string, escapes are
-passed through untranslated.
-
-@findex PARAM_OPTIONAL_FILENAME
-@findex gdb.PARAM_OPTIONAL_FILENAME
-@item gdb.PARAM_OPTIONAL_FILENAME
-The value is a either a filename (a string), or @code{None}.
-
-@findex PARAM_FILENAME
-@findex gdb.PARAM_FILENAME
-@item gdb.PARAM_FILENAME
-The value is a filename. This is just like
-@code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
-
-@findex PARAM_ZINTEGER
-@findex gdb.PARAM_ZINTEGER
-@item gdb.PARAM_ZINTEGER
-The value is an integer. This is like @code{PARAM_INTEGER}, except 0
-is interpreted as itself.
-
-@findex PARAM_ENUM
-@findex gdb.PARAM_ENUM
-@item gdb.PARAM_ENUM
-The value is a string, which must be one of a collection string
-constants provided when the parameter is created.
-@end table
-
-@node Functions In Python
-@subsubsection Writing new convenience functions
-
-@cindex writing convenience functions
-@cindex convenience functions in python
-@cindex python convenience functions
-@tindex gdb.Function
-@tindex Function
-You can implement new convenience functions (@pxref{Convenience Vars})
-in Python. A convenience function is an instance of a subclass of the
-class @code{gdb.Function}.
-
-@defun Function.__init__ (name)
-The initializer for @code{Function} registers the new function with
-@value{GDBN}. The argument @var{name} is the name of the function,
-a string. The function will be visible to the user as a convenience
-variable of type @code{internal function}, whose name is the same as
-the given @var{name}.
-
-The documentation for the new function is taken from the documentation
-string for the new class.
-@end defun
-
-@defun Function.invoke (@var{*args})
-When a convenience function is evaluated, its arguments are converted
-to instances of @code{gdb.Value}, and then the function's
-@code{invoke} method is called. Note that @value{GDBN} does not
-predetermine the arity of convenience functions. Instead, all
-available arguments are passed to @code{invoke}, following the
-standard Python calling convention. In particular, a convenience
-function can have default values for parameters without ill effect.
-
-The return value of this method is used as its value in the enclosing
-expression. If an ordinary Python value is returned, it is converted
-to a @code{gdb.Value} following the usual rules.
-@end defun
-
-The following code snippet shows how a trivial convenience function can
-be implemented in Python:
-
-@smallexample
-class Greet (gdb.Function):
- """Return string to greet someone.
-Takes a name as argument."""
-
- def __init__ (self):
- super (Greet, self).__init__ ("greet")
-
- def invoke (self, name):
- return "Hello, %s!" % name.string ()
-
-Greet ()
-@end smallexample
-
-The last line instantiates the class, and is necessary to trigger the
-registration of the function with @value{GDBN}. Depending on how the
-Python code is read into @value{GDBN}, you may need to import the
-@code{gdb} module explicitly.
-
-Now you can use the function in an expression:
-
-@smallexample
-(gdb) print $greet("Bob")
-$1 = "Hello, Bob!"
-@end smallexample
-
-@node Progspaces In Python
-@subsubsection Program Spaces In Python
-
-@cindex progspaces in python
-@tindex gdb.Progspace
-@tindex Progspace
-A program space, or @dfn{progspace}, represents a symbolic view
-of an address space.
-It consists of all of the objfiles of the program.
-@xref{Objfiles In Python}.
-@xref{Inferiors and Programs, program spaces}, for more details
-about program spaces.
-
-The following progspace-related functions are available in the
-@code{gdb} module:
-
-@findex gdb.current_progspace
-@defun gdb.current_progspace ()
-This function returns the program space of the currently selected inferior.
-@xref{Inferiors and Programs}.
-@end defun
-
-@findex gdb.progspaces
-@defun gdb.progspaces ()
-Return a sequence of all the progspaces currently known to @value{GDBN}.
-@end defun
-
-Each progspace is represented by an instance of the @code{gdb.Progspace}
-class.
-
-@defvar Progspace.filename
-The file name of the progspace as a string.
-@end defvar
-
-@defvar Progspace.pretty_printers
-The @code{pretty_printers} attribute is a list of functions. It is
-used to look up pretty-printers. A @code{Value} is passed to each
-function in order; if the function returns @code{None}, then the
-search continues. Otherwise, the return value should be an object
-which is used to format the value. @xref{Pretty Printing API}, for more
-information.
-@end defvar
-
-@defvar Progspace.type_printers
-The @code{type_printers} attribute is a list of type printer objects.
-@xref{Type Printing API}, for more information.
-@end defvar
-
-@defvar Progspace.frame_filters
-The @code{frame_filters} attribute is a dictionary of frame filter
-objects. @xref{Frame Filter API}, for more information.
-@end defvar
-
-@node Objfiles In Python
-@subsubsection Objfiles In Python
-
-@cindex objfiles in python
-@tindex gdb.Objfile
-@tindex Objfile
-@value{GDBN} loads symbols for an inferior from various
-symbol-containing files (@pxref{Files}). These include the primary
-executable file, any shared libraries used by the inferior, and any
-separate debug info files (@pxref{Separate Debug Files}).
-@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
-
-The following objfile-related functions are available in the
-@code{gdb} module:
-
-@findex gdb.current_objfile
-@defun gdb.current_objfile ()
-When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
-sets the ``current objfile'' to the corresponding objfile. This
-function returns the current objfile. If there is no current objfile,
-this function returns @code{None}.
-@end defun
-
-@findex gdb.objfiles
-@defun gdb.objfiles ()
-Return a sequence of all the objfiles current known to @value{GDBN}.
-@xref{Objfiles In Python}.
-@end defun
-
-Each objfile is represented by an instance of the @code{gdb.Objfile}
-class.
-
-@defvar Objfile.filename
-The file name of the objfile as a string.
-@end defvar
-
-@defvar Objfile.pretty_printers
-The @code{pretty_printers} attribute is a list of functions. It is
-used to look up pretty-printers. A @code{Value} is passed to each
-function in order; if the function returns @code{None}, then the
-search continues. Otherwise, the return value should be an object
-which is used to format the value. @xref{Pretty Printing API}, for more
-information.
-@end defvar
-
-@defvar Objfile.type_printers
-The @code{type_printers} attribute is a list of type printer objects.
-@xref{Type Printing API}, for more information.
-@end defvar
-
-@defvar Objfile.frame_filters
-The @code{frame_filters} attribute is a dictionary of frame filter
-objects. @xref{Frame Filter API}, for more information.
-@end defvar
-
-A @code{gdb.Objfile} object has the following methods:
-
-@defun Objfile.is_valid ()
-Returns @code{True} if the @code{gdb.Objfile} object is valid,
-@code{False} if not. A @code{gdb.Objfile} object can become invalid
-if the object file it refers to is not loaded in @value{GDBN} any
-longer. All other @code{gdb.Objfile} methods will throw an exception
-if it is invalid at the time the method is called.
-@end defun
-
-@node Frames In Python
-@subsubsection Accessing inferior stack frames from Python.
-
-@cindex frames in python
-When the debugged program stops, @value{GDBN} is able to analyze its call
-stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
-represents a frame in the stack. A @code{gdb.Frame} object is only valid
-while its corresponding frame exists in the inferior's stack. If you try
-to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error}
-exception (@pxref{Exception Handling}).
-
-Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
-operator, like:
-
-@smallexample
-(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
-True
-@end smallexample
-
-The following frame-related functions are available in the @code{gdb} module:
-
-@findex gdb.selected_frame
-@defun gdb.selected_frame ()
-Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
-@end defun
-
-@findex gdb.newest_frame
-@defun gdb.newest_frame ()
-Return the newest frame object for the selected thread.
-@end defun
-
-@defun gdb.frame_stop_reason_string (reason)
-Return a string explaining the reason why @value{GDBN} stopped unwinding
-frames, as expressed by the given @var{reason} code (an integer, see the
-@code{unwind_stop_reason} method further down in this section).
-@end defun
-
-A @code{gdb.Frame} object has the following methods:
-
-@defun Frame.is_valid ()
-Returns true if the @code{gdb.Frame} object is valid, false if not.
-A frame object can become invalid if the frame it refers to doesn't
-exist anymore in the inferior. All @code{gdb.Frame} methods will throw
-an exception if it is invalid at the time the method is called.
-@end defun
-
-@defun Frame.name ()
-Returns the function name of the frame, or @code{None} if it can't be
-obtained.
-@end defun
-
-@defun Frame.architecture ()
-Returns the @code{gdb.Architecture} object corresponding to the frame's
-architecture. @xref{Architectures In Python}.
-@end defun
-
-@defun Frame.type ()
-Returns the type of the frame. The value can be one of:
-@table @code
-@item gdb.NORMAL_FRAME
-An ordinary stack frame.
-
-@item gdb.DUMMY_FRAME
-A fake stack frame that was created by @value{GDBN} when performing an
-inferior function call.
-
-@item gdb.INLINE_FRAME
-A frame representing an inlined function. The function was inlined
-into a @code{gdb.NORMAL_FRAME} that is older than this one.
-
-@item gdb.TAILCALL_FRAME
-A frame representing a tail call. @xref{Tail Call Frames}.
-
-@item gdb.SIGTRAMP_FRAME
-A signal trampoline frame. This is the frame created by the OS when
-it calls into a signal handler.
-
-@item gdb.ARCH_FRAME
-A fake stack frame representing a cross-architecture call.
-
-@item gdb.SENTINEL_FRAME
-This is like @code{gdb.NORMAL_FRAME}, but it is only used for the
-newest frame.
-@end table
-@end defun
-
-@defun Frame.unwind_stop_reason ()
-Return an integer representing the reason why it's not possible to find
-more frames toward the outermost frame. Use
-@code{gdb.frame_stop_reason_string} to convert the value returned by this
-function to a string. The value can be one of:
-
-@table @code
-@item gdb.FRAME_UNWIND_NO_REASON
-No particular reason (older frames should be available).
-
-@item gdb.FRAME_UNWIND_NULL_ID
-The previous frame's analyzer returns an invalid result. This is no
-longer used by @value{GDBN}, and is kept only for backward
-compatibility.
-
-@item gdb.FRAME_UNWIND_OUTERMOST
-This frame is the outermost.
-
-@item gdb.FRAME_UNWIND_UNAVAILABLE
-Cannot unwind further, because that would require knowing the
-values of registers or memory that have not been collected.
-
-@item gdb.FRAME_UNWIND_INNER_ID
-This frame ID looks like it ought to belong to a NEXT frame,
-but we got it for a PREV frame. Normally, this is a sign of
-unwinder failure. It could also indicate stack corruption.
-
-@item gdb.FRAME_UNWIND_SAME_ID
-This frame has the same ID as the previous one. That means
-that unwinding further would almost certainly give us another
-frame with exactly the same ID, so break the chain. Normally,
-this is a sign of unwinder failure. It could also indicate
-stack corruption.
-
-@item gdb.FRAME_UNWIND_NO_SAVED_PC
-The frame unwinder did not find any saved PC, but we needed
-one to unwind further.
-
-@item gdb.FRAME_UNWIND_FIRST_ERROR
-Any stop reason greater or equal to this value indicates some kind
-of error. This special value facilitates writing code that tests
-for errors in unwinding in a way that will work correctly even if
-the list of the other values is modified in future @value{GDBN}
-versions. Using it, you could write:
-@smallexample
-reason = gdb.selected_frame().unwind_stop_reason ()
-reason_str = gdb.frame_stop_reason_string (reason)
-if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
- print "An error occured: %s" % reason_str
-@end smallexample
-@end table
-
-@end defun
-
-@defun Frame.pc ()
-Returns the frame's resume address.
-@end defun
-
-@defun Frame.block ()
-Return the frame's code block. @xref{Blocks In Python}.
-@end defun
-
-@defun Frame.function ()
-Return the symbol for the function corresponding to this frame.
-@xref{Symbols In Python}.
-@end defun
-
-@defun Frame.older ()
-Return the frame that called this frame.
-@end defun
-
-@defun Frame.newer ()
-Return the frame called by this frame.
-@end defun
-
-@defun Frame.find_sal ()
-Return the frame's symtab and line object.
-@xref{Symbol Tables In Python}.
-@end defun
-
-@defun Frame.read_var (variable @r{[}, block@r{]})
-Return the value of @var{variable} in this frame. If the optional
-argument @var{block} is provided, search for the variable from that
-block; otherwise start at the frame's current block (which is
-determined by the frame's current program counter). @var{variable}
-must be a string or a @code{gdb.Symbol} object. @var{block} must be a
-@code{gdb.Block} object.
-@end defun
-
-@defun Frame.select ()
-Set this frame to be the selected frame. @xref{Stack, ,Examining the
-Stack}.
-@end defun
-
-@node Blocks In Python
-@subsubsection Accessing blocks from Python.
-
-@cindex blocks in python
-@tindex gdb.Block
-
-In @value{GDBN}, symbols are stored in blocks. A block corresponds
-roughly to a scope in the source code. Blocks are organized
-hierarchically, and are represented individually in Python as a
-@code{gdb.Block}. Blocks rely on debugging information being
-available.
-
-A frame has a block. Please see @ref{Frames In Python}, for a more
-in-depth discussion of frames.
-
-The outermost block is known as the @dfn{global block}. The global
-block typically holds public global variables and functions.
-
-The block nested just inside the global block is the @dfn{static
-block}. The static block typically holds file-scoped variables and
-functions.
-
-@value{GDBN} provides a method to get a block's superblock, but there
-is currently no way to examine the sub-blocks of a block, or to
-iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
-Python}).
-
-Here is a short example that should help explain blocks:
-
-@smallexample
-/* This is in the global block. */
-int global;
-
-/* This is in the static block. */
-static int file_scope;
-
-/* 'function' is in the global block, and 'argument' is
- in a block nested inside of 'function'. */
-int function (int argument)
-@{
- /* 'local' is in a block inside 'function'. It may or may
- not be in the same block as 'argument'. */
- int local;
-
- @{
- /* 'inner' is in a block whose superblock is the one holding
- 'local'. */
- int inner;
-
- /* If this call is expanded by the compiler, you may see
- a nested block here whose function is 'inline_function'
- and whose superblock is the one holding 'inner'. */
- inline_function ();
- @}
-@}
-@end smallexample
-
-A @code{gdb.Block} is iterable. The iterator returns the symbols
-(@pxref{Symbols In Python}) local to the block. Python programs
-should not assume that a specific block object will always contain a
-given symbol, since changes in @value{GDBN} features and
-infrastructure may cause symbols move across blocks in a symbol
-table.
-
-The following block-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.block_for_pc
-@defun gdb.block_for_pc (pc)
-Return the innermost @code{gdb.Block} containing the given @var{pc}
-value. If the block cannot be found for the @var{pc} value specified,
-the function will return @code{None}.
-@end defun
-
-A @code{gdb.Block} object has the following methods:
-
-@defun Block.is_valid ()
-Returns @code{True} if the @code{gdb.Block} object is valid,
-@code{False} if not. A block object can become invalid if the block it
-refers to doesn't exist anymore in the inferior. All other
-@code{gdb.Block} methods will throw an exception if it is invalid at
-the time the method is called. The block's validity is also checked
-during iteration over symbols of the block.
-@end defun
-
-A @code{gdb.Block} object has the following attributes:
-
-@defvar Block.start
-The start address of the block. This attribute is not writable.
-@end defvar
-
-@defvar Block.end
-The end address of the block. This attribute is not writable.
-@end defvar
-
-@defvar Block.function
-The name of the block represented as a @code{gdb.Symbol}. If the
-block is not named, then this attribute holds @code{None}. This
-attribute is not writable.
-
-For ordinary function blocks, the superblock is the static block.
-However, you should note that it is possible for a function block to
-have a superblock that is not the static block -- for instance this
-happens for an inlined function.
-@end defvar
-
-@defvar Block.superblock
-The block containing this block. If this parent block does not exist,
-this attribute holds @code{None}. This attribute is not writable.
-@end defvar
-
-@defvar Block.global_block
-The global block associated with this block. This attribute is not
-writable.
-@end defvar
-
-@defvar Block.static_block
-The static block associated with this block. This attribute is not
-writable.
-@end defvar
-
-@defvar Block.is_global
-@code{True} if the @code{gdb.Block} object is a global block,
-@code{False} if not. This attribute is not
-writable.
-@end defvar
-
-@defvar Block.is_static
-@code{True} if the @code{gdb.Block} object is a static block,
-@code{False} if not. This attribute is not writable.
-@end defvar
-
-@node Symbols In Python
-@subsubsection Python representation of Symbols.
-
-@cindex symbols in python
-@tindex gdb.Symbol
-
-@value{GDBN} represents every variable, function and type as an
-entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
-Similarly, Python represents these symbols in @value{GDBN} with the
-@code{gdb.Symbol} object.
-
-The following symbol-related functions are available in the @code{gdb}
-module:
-
-@findex gdb.lookup_symbol
-@defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]})
-This function searches for a symbol by name. The search scope can be
-restricted to the parameters defined in the optional domain and block
-arguments.
-
-@var{name} is the name of the symbol. It must be a string. The
-optional @var{block} argument restricts the search to symbols visible
-in that @var{block}. The @var{block} argument must be a
-@code{gdb.Block} object. If omitted, the block for the current frame
-is used. The optional @var{domain} argument restricts
-the search to the domain type. The @var{domain} argument must be a
-domain constant defined in the @code{gdb} module and described later
-in this chapter.
-
-The result is a tuple of two elements.
-The first element is a @code{gdb.Symbol} object or @code{None} if the symbol
-is not found.
-If the symbol is found, the second element is @code{True} if the symbol
-is a field of a method's object (e.g., @code{this} in C@t{++}),
-otherwise it is @code{False}.
-If the symbol is not found, the second element is @code{False}.
-@end defun
-
-@findex gdb.lookup_global_symbol
-@defun gdb.lookup_global_symbol (name @r{[}, domain@r{]})
-This function searches for a global symbol by name.
-The search scope can be restricted to by the domain argument.
-
-@var{name} is the name of the symbol. It must be a string.
-The optional @var{domain} argument restricts the search to the domain type.
-The @var{domain} argument must be a domain constant defined in the @code{gdb}
-module and described later in this chapter.
-
-The result is a @code{gdb.Symbol} object or @code{None} if the symbol
-is not found.
-@end defun
-
-A @code{gdb.Symbol} object has the following attributes:
-
-@defvar Symbol.type
-The type of the symbol or @code{None} if no type is recorded.
-This attribute is represented as a @code{gdb.Type} object.
-@xref{Types In Python}. This attribute is not writable.
-@end defvar
-
-@defvar Symbol.symtab
-The symbol table in which the symbol appears. This attribute is
-represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
-Python}. This attribute is not writable.
-@end defvar
-
-@defvar Symbol.line
-The line number in the source code at which the symbol was defined.
-This is an integer.
-@end defvar
-
-@defvar Symbol.name
-The name of the symbol as a string. This attribute is not writable.
-@end defvar
-
-@defvar Symbol.linkage_name
-The name of the symbol, as used by the linker (i.e., may be mangled).
-This attribute is not writable.
-@end defvar
-
-@defvar Symbol.print_name
-The name of the symbol in a form suitable for output. This is either
-@code{name} or @code{linkage_name}, depending on whether the user
-asked @value{GDBN} to display demangled or mangled names.
-@end defvar
-
-@defvar Symbol.addr_class
-The address class of the symbol. This classifies how to find the value
-of a symbol. Each address class is a constant defined in the
-@code{gdb} module and described later in this chapter.
-@end defvar
-
-@defvar Symbol.needs_frame
-This is @code{True} if evaluating this symbol's value requires a frame
-(@pxref{Frames In Python}) and @code{False} otherwise. Typically,
-local variables will require a frame, but other symbols will not.
-@end defvar
-
-@defvar Symbol.is_argument
-@code{True} if the symbol is an argument of a function.
-@end defvar
-
-@defvar Symbol.is_constant
-@code{True} if the symbol is a constant.
-@end defvar
-
-@defvar Symbol.is_function
-@code{True} if the symbol is a function or a method.
-@end defvar
-
-@defvar Symbol.is_variable
-@code{True} if the symbol is a variable.
-@end defvar
-
-A @code{gdb.Symbol} object has the following methods:
-
-@defun Symbol.is_valid ()
-Returns @code{True} if the @code{gdb.Symbol} object is valid,
-@code{False} if not. A @code{gdb.Symbol} object can become invalid if
-the symbol it refers to does not exist in @value{GDBN} any longer.
-All other @code{gdb.Symbol} methods will throw an exception if it is
-invalid at the time the method is called.
-@end defun
-
-@defun Symbol.value (@r{[}frame@r{]})
-Compute the value of the symbol, as a @code{gdb.Value}. For
-functions, this computes the address of the function, cast to the
-appropriate type. If the symbol requires a frame in order to compute
-its value, then @var{frame} must be given. If @var{frame} is not
-given, or if @var{frame} is invalid, then this method will throw an
-exception.
-@end defun
-
-The available domain categories in @code{gdb.Symbol} are represented
-as constants in the @code{gdb} module:
-
-@table @code
-@findex SYMBOL_UNDEF_DOMAIN
-@findex gdb.SYMBOL_UNDEF_DOMAIN
-@item gdb.SYMBOL_UNDEF_DOMAIN
-This is used when a domain has not been discovered or none of the
-following domains apply. This usually indicates an error either
-in the symbol information or in @value{GDBN}'s handling of symbols.
-@findex SYMBOL_VAR_DOMAIN
-@findex gdb.SYMBOL_VAR_DOMAIN
-@item gdb.SYMBOL_VAR_DOMAIN
-This domain contains variables, function names, typedef names and enum
-type values.
-@findex SYMBOL_STRUCT_DOMAIN
-@findex gdb.SYMBOL_STRUCT_DOMAIN
-@item gdb.SYMBOL_STRUCT_DOMAIN
-This domain holds struct, union and enum type names.
-@findex SYMBOL_LABEL_DOMAIN
-@findex gdb.SYMBOL_LABEL_DOMAIN
-@item gdb.SYMBOL_LABEL_DOMAIN
-This domain contains names of labels (for gotos).
-@findex SYMBOL_VARIABLES_DOMAIN
-@findex gdb.SYMBOL_VARIABLES_DOMAIN
-@item gdb.SYMBOL_VARIABLES_DOMAIN
-This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
-contains everything minus functions and types.
-@findex SYMBOL_FUNCTIONS_DOMAIN
-@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
-@item gdb.SYMBOL_FUNCTION_DOMAIN
-This domain contains all functions.
-@findex SYMBOL_TYPES_DOMAIN
-@findex gdb.SYMBOL_TYPES_DOMAIN
-@item gdb.SYMBOL_TYPES_DOMAIN
-This domain contains all types.
-@end table
-
-The available address class categories in @code{gdb.Symbol} are represented
-as constants in the @code{gdb} module:
-
-@table @code
-@findex SYMBOL_LOC_UNDEF
-@findex gdb.SYMBOL_LOC_UNDEF
-@item gdb.SYMBOL_LOC_UNDEF
-If this is returned by address class, it indicates an error either in
-the symbol information or in @value{GDBN}'s handling of symbols.
-@findex SYMBOL_LOC_CONST
-@findex gdb.SYMBOL_LOC_CONST
-@item gdb.SYMBOL_LOC_CONST
-Value is constant int.
-@findex SYMBOL_LOC_STATIC
-@findex gdb.SYMBOL_LOC_STATIC
-@item gdb.SYMBOL_LOC_STATIC
-Value is at a fixed address.
-@findex SYMBOL_LOC_REGISTER
-@findex gdb.SYMBOL_LOC_REGISTER
-@item gdb.SYMBOL_LOC_REGISTER
-Value is in a register.
-@findex SYMBOL_LOC_ARG
-@findex gdb.SYMBOL_LOC_ARG
-@item gdb.SYMBOL_LOC_ARG
-Value is an argument. This value is at the offset stored within the
-symbol inside the frame's argument list.
-@findex SYMBOL_LOC_REF_ARG
-@findex gdb.SYMBOL_LOC_REF_ARG
-@item gdb.SYMBOL_LOC_REF_ARG
-Value address is stored in the frame's argument list. Just like
-@code{LOC_ARG} except that the value's address is stored at the
-offset, not the value itself.
-@findex SYMBOL_LOC_REGPARM_ADDR
-@findex gdb.SYMBOL_LOC_REGPARM_ADDR
-@item gdb.SYMBOL_LOC_REGPARM_ADDR
-Value is a specified register. Just like @code{LOC_REGISTER} except
-the register holds the address of the argument instead of the argument
-itself.
-@findex SYMBOL_LOC_LOCAL
-@findex gdb.SYMBOL_LOC_LOCAL
-@item gdb.SYMBOL_LOC_LOCAL
-Value is a local variable.
-@findex SYMBOL_LOC_TYPEDEF
-@findex gdb.SYMBOL_LOC_TYPEDEF
-@item gdb.SYMBOL_LOC_TYPEDEF
-Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
-have this class.
-@findex SYMBOL_LOC_BLOCK
-@findex gdb.SYMBOL_LOC_BLOCK
-@item gdb.SYMBOL_LOC_BLOCK
-Value is a block.
-@findex SYMBOL_LOC_CONST_BYTES
-@findex gdb.SYMBOL_LOC_CONST_BYTES
-@item gdb.SYMBOL_LOC_CONST_BYTES
-Value is a byte-sequence.
-@findex SYMBOL_LOC_UNRESOLVED
-@findex gdb.SYMBOL_LOC_UNRESOLVED
-@item gdb.SYMBOL_LOC_UNRESOLVED
-Value is at a fixed address, but the address of the variable has to be
-determined from the minimal symbol table whenever the variable is
-referenced.
-@findex SYMBOL_LOC_OPTIMIZED_OUT
-@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
-@item gdb.SYMBOL_LOC_OPTIMIZED_OUT
-The value does not actually exist in the program.
-@findex SYMBOL_LOC_COMPUTED
-@findex gdb.SYMBOL_LOC_COMPUTED
-@item gdb.SYMBOL_LOC_COMPUTED
-The value's address is a computed location.
-@end table
-
-@node Symbol Tables In Python
-@subsubsection Symbol table representation in Python.
-
-@cindex symbol tables in python
-@tindex gdb.Symtab
-@tindex gdb.Symtab_and_line
-
-Access to symbol table data maintained by @value{GDBN} on the inferior
-is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
-@code{gdb.Symtab}. Symbol table and line data for a frame is returned
-from the @code{find_sal} method in @code{gdb.Frame} object.
-@xref{Frames In Python}.
-
-For more information on @value{GDBN}'s symbol table management, see
-@ref{Symbols, ,Examining the Symbol Table}, for more information.
-
-A @code{gdb.Symtab_and_line} object has the following attributes:
-
-@defvar Symtab_and_line.symtab
-The symbol table object (@code{gdb.Symtab}) for this frame.
-This attribute is not writable.
-@end defvar
-
-@defvar Symtab_and_line.pc
-Indicates the start of the address range occupied by code for the
-current source line. This attribute is not writable.
-@end defvar
-
-@defvar Symtab_and_line.last
-Indicates the end of the address range occupied by code for the current
-source line. This attribute is not writable.
-@end defvar
-
-@defvar Symtab_and_line.line
-Indicates the current line number for this object. This
-attribute is not writable.
-@end defvar
-
-A @code{gdb.Symtab_and_line} object has the following methods:
-
-@defun Symtab_and_line.is_valid ()
-Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
-@code{False} if not. A @code{gdb.Symtab_and_line} object can become
-invalid if the Symbol table and line object it refers to does not
-exist in @value{GDBN} any longer. All other
-@code{gdb.Symtab_and_line} methods will throw an exception if it is
-invalid at the time the method is called.
-@end defun
-
-A @code{gdb.Symtab} object has the following attributes:
-
-@defvar Symtab.filename
-The symbol table's source filename. This attribute is not writable.
-@end defvar
-
-@defvar Symtab.objfile
-The symbol table's backing object file. @xref{Objfiles In Python}.
-This attribute is not writable.
-@end defvar
-
-A @code{gdb.Symtab} object has the following methods:
-
-@defun Symtab.is_valid ()
-Returns @code{True} if the @code{gdb.Symtab} object is valid,
-@code{False} if not. A @code{gdb.Symtab} object can become invalid if
-the symbol table it refers to does not exist in @value{GDBN} any
-longer. All other @code{gdb.Symtab} methods will throw an exception
-if it is invalid at the time the method is called.
-@end defun
-
-@defun Symtab.fullname ()
-Return the symbol table's source absolute file name.
-@end defun
-
-@defun Symtab.global_block ()
-Return the global block of the underlying symbol table.
-@xref{Blocks In Python}.
-@end defun
-
-@defun Symtab.static_block ()
-Return the static block of the underlying symbol table.
-@xref{Blocks In Python}.
-@end defun
-
-@defun Symtab.linetable ()
-Return the line table associated with the symbol table.
-@xref{Line Tables In Python}.
-@end defun
-
-@node Line Tables In Python
-@subsubsection Manipulating line tables using Python
-
-@cindex line tables in python
-@tindex gdb.LineTable
-
-Python code can request and inspect line table information from a
-symbol table that is loaded in @value{GDBN}. A line table is a
-mapping of source lines to their executable locations in memory. To
-acquire the line table information for a particular symbol table, use
-the @code{linetable} function (@pxref{Symbol Tables In Python}).
-
-A @code{gdb.LineTable} is iterable. The iterator returns
-@code{LineTableEntry} objects that correspond to the source line and
-address for each line table entry. @code{LineTableEntry} objects have
-the following attributes:
-
-@defvar LineTableEntry.line
-The source line number for this line table entry. This number
-corresponds to the actual line of source. This attribute is not
-writable.
-@end defvar
-
-@defvar LineTableEntry.pc
-The address that is associated with the line table entry where the
-executable code for that source line resides in memory. This
-attribute is not writable.
-@end defvar
-
-As there can be multiple addresses for a single source line, you may
-receive multiple @code{LineTableEntry} objects with matching
-@code{line} attributes, but with different @code{pc} attributes. The
-iterator is sorted in ascending @code{pc} order. Here is a small
-example illustrating iterating over a line table.
-
-@smallexample
-symtab = gdb.selected_frame().find_sal().symtab
-linetable = symtab.linetable()
-for line in linetable:
- print "Line: "+str(line.line)+" Address: "+hex(line.pc)
-@end smallexample
-
-This will have the following output:
-
-@smallexample
-Line: 33 Address: 0x4005c8L
-Line: 37 Address: 0x4005caL
-Line: 39 Address: 0x4005d2L
-Line: 40 Address: 0x4005f8L
-Line: 42 Address: 0x4005ffL
-Line: 44 Address: 0x400608L
-Line: 42 Address: 0x40060cL
-Line: 45 Address: 0x400615L
-@end smallexample
-
-In addition to being able to iterate over a @code{LineTable}, it also
-has the following direct access methods:
-
-@defun LineTable.line (line)
-Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
-entries in the line table for the given @var{line}. @var{line} refers
-to the source code line. If there are no entries for that source code
-@var{line}, the Python @code{None} is returned.
-@end defun
-
-@defun LineTable.has_line (line)
-Return a Python @code{Boolean} indicating whether there is an entry in
-the line table for this source line. Return @code{True} if an entry
-is found, or @code{False} if not.
-@end defun
-
-@defun LineTable.source_lines ()
-Return a Python @code{List} of the source line numbers in the symbol
-table. Only lines with executable code locations are returned. The
-contents of the @code{List} will just be the source line entries
-represented as Python @code{Long} values.
-@end defun
-
-@node Breakpoints In Python
-@subsubsection Manipulating breakpoints using Python
-
-@cindex breakpoints in python
-@tindex gdb.Breakpoint
-
-Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
-class.
-
-@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
-Create a new breakpoint. @var{spec} is a string naming the location
-of the breakpoint, or an expression that defines a watchpoint. The
-contents can be any location recognized by the @code{break} command,
-or in the case of a watchpoint, by the @code{watch} command. The
-optional @var{type} denotes the breakpoint to create from the types
-defined later in this chapter. This argument can be either:
-@code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
-defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
-argument allows the breakpoint to become invisible to the user. The
-breakpoint will neither be reported when created, nor will it be
-listed in the output from @code{info breakpoints} (but will be listed
-with the @code{maint info breakpoints} command). The optional
-@var{temporary} argument makes the breakpoint a temporary breakpoint.
-Temporary breakpoints are deleted after they have been hit. Any
-further access to the Python breakpoint after it has been hit will
-result in a runtime error (as that breakpoint has now been
-automatically deleted). The optional @var{wp_class} argument defines
-the class of watchpoint to create, if @var{type} is
-@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
-is assumed to be a @code{gdb.WP_WRITE} class.
-@end defun
-
-@defun Breakpoint.stop (self)
-The @code{gdb.Breakpoint} class can be sub-classed and, in
-particular, you may choose to implement the @code{stop} method.
-If this method is defined in a sub-class of @code{gdb.Breakpoint},
-it will be called when the inferior reaches any location of a
-breakpoint which instantiates that sub-class. If the method returns
-@code{True}, the inferior will be stopped at the location of the
-breakpoint, otherwise the inferior will continue.
-
-If there are multiple breakpoints at the same location with a
-@code{stop} method, each one will be called regardless of the
-return status of the previous. This ensures that all @code{stop}
-methods have a chance to execute at that location. In this scenario
-if one of the methods returns @code{True} but the others return
-@code{False}, the inferior will still be stopped.
-
-You should not alter the execution state of the inferior (i.e.@:, step,
-next, etc.), alter the current frame context (i.e.@:, change the current
-active frame), or alter, add or delete any breakpoint. As a general
-rule, you should not alter any data within @value{GDBN} or the inferior
-at this time.
-
-Example @code{stop} implementation:
-
-@smallexample
-class MyBreakpoint (gdb.Breakpoint):
- def stop (self):
- inf_val = gdb.parse_and_eval("foo")
- if inf_val == 3:
- return True
- return False
-@end smallexample
-@end defun
-
-The available watchpoint types represented by constants are defined in the
-@code{gdb} module:
-
-@table @code
-@findex WP_READ
-@findex gdb.WP_READ
-@item gdb.WP_READ
-Read only watchpoint.
-
-@findex WP_WRITE
-@findex gdb.WP_WRITE
-@item gdb.WP_WRITE
-Write only watchpoint.
-
-@findex WP_ACCESS
-@findex gdb.WP_ACCESS
-@item gdb.WP_ACCESS
-Read/Write watchpoint.
-@end table
-
-@defun Breakpoint.is_valid ()
-Return @code{True} if this @code{Breakpoint} object is valid,
-@code{False} otherwise. A @code{Breakpoint} object can become invalid
-if the user deletes the breakpoint. In this case, the object still
-exists, but the underlying breakpoint does not. In the cases of
-watchpoint scope, the watchpoint remains valid even if execution of the
-inferior leaves the scope of that watchpoint.
-@end defun
-
-@defun Breakpoint.delete
-Permanently deletes the @value{GDBN} breakpoint. This also
-invalidates the Python @code{Breakpoint} object. Any further access
-to this object's attributes or methods will raise an error.
-@end defun
-
-@defvar Breakpoint.enabled
-This attribute is @code{True} if the breakpoint is enabled, and
-@code{False} otherwise. This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.silent
-This attribute is @code{True} if the breakpoint is silent, and
-@code{False} otherwise. This attribute is writable.
-
-Note that a breakpoint can also be silent if it has commands and the
-first command is @code{silent}. This is not reported by the
-@code{silent} attribute.
-@end defvar
-
-@defvar Breakpoint.thread
-If the breakpoint is thread-specific, this attribute holds the thread
-id. If the breakpoint is not thread-specific, this attribute is
-@code{None}. This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.task
-If the breakpoint is Ada task-specific, this attribute holds the Ada task
-id. If the breakpoint is not task-specific (or the underlying
-language is not Ada), this attribute is @code{None}. This attribute
-is writable.
-@end defvar
-
-@defvar Breakpoint.ignore_count
-This attribute holds the ignore count for the breakpoint, an integer.
-This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.number
-This attribute holds the breakpoint's number --- the identifier used by
-the user to manipulate the breakpoint. This attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.type
-This attribute holds the breakpoint's type --- the identifier used to
-determine the actual breakpoint type or use-case. This attribute is not
-writable.
-@end defvar
-
-@defvar Breakpoint.visible
-This attribute tells whether the breakpoint is visible to the user
-when set, or when the @samp{info breakpoints} command is run. This
-attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.temporary
-This attribute indicates whether the breakpoint was created as a
-temporary breakpoint. Temporary breakpoints are automatically deleted
-after that breakpoint has been hit. Access to this attribute, and all
-other attributes and functions other than the @code{is_valid}
-function, will result in an error after the breakpoint has been hit
-(as it has been automatically deleted). This attribute is not
-writable.
-@end defvar
-
-The available types are represented by constants defined in the @code{gdb}
-module:
-
-@table @code
-@findex BP_BREAKPOINT
-@findex gdb.BP_BREAKPOINT
-@item gdb.BP_BREAKPOINT
-Normal code breakpoint.
-
-@findex BP_WATCHPOINT
-@findex gdb.BP_WATCHPOINT
-@item gdb.BP_WATCHPOINT
-Watchpoint breakpoint.
-
-@findex BP_HARDWARE_WATCHPOINT
-@findex gdb.BP_HARDWARE_WATCHPOINT
-@item gdb.BP_HARDWARE_WATCHPOINT
-Hardware assisted watchpoint.
-
-@findex BP_READ_WATCHPOINT
-@findex gdb.BP_READ_WATCHPOINT
-@item gdb.BP_READ_WATCHPOINT
-Hardware assisted read watchpoint.
-
-@findex BP_ACCESS_WATCHPOINT
-@findex gdb.BP_ACCESS_WATCHPOINT
-@item gdb.BP_ACCESS_WATCHPOINT
-Hardware assisted access watchpoint.
-@end table
-
-@defvar Breakpoint.hit_count
-This attribute holds the hit count for the breakpoint, an integer.
-This attribute is writable, but currently it can only be set to zero.
-@end defvar
-
-@defvar Breakpoint.location
-This attribute holds the location of the breakpoint, as specified by
-the user. It is a string. If the breakpoint does not have a location
-(that is, it is a watchpoint) the attribute's value is @code{None}. This
-attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.expression
-This attribute holds a breakpoint expression, as specified by
-the user. It is a string. If the breakpoint does not have an
-expression (the breakpoint is not a watchpoint) the attribute's value
-is @code{None}. This attribute is not writable.
-@end defvar
-
-@defvar Breakpoint.condition
-This attribute holds the condition of the breakpoint, as specified by
-the user. It is a string. If there is no condition, this attribute's
-value is @code{None}. This attribute is writable.
-@end defvar
-
-@defvar Breakpoint.commands
-This attribute holds the commands attached to the breakpoint. If
-there are commands, this attribute's value is a string holding all the
-commands, separated by newlines. If there are no commands, this
-attribute is @code{None}. This attribute is not writable.
-@end defvar
-
-@node Finish Breakpoints in Python
-@subsubsection Finish Breakpoints
-
-@cindex python finish breakpoints
-@tindex gdb.FinishBreakpoint
-
-A finish breakpoint is a temporary breakpoint set at the return address of
-a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
-extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
-and deleted when the execution will run out of the breakpoint scope (i.e.@:
-@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
-Finish breakpoints are thread specific and must be create with the right
-thread selected.
-
-@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
-Create a finish breakpoint at the return address of the @code{gdb.Frame}
-object @var{frame}. If @var{frame} is not provided, this defaults to the
-newest frame. The optional @var{internal} argument allows the breakpoint to
-become invisible to the user. @xref{Breakpoints In Python}, for further
-details about this argument.
-@end defun
-
-@defun FinishBreakpoint.out_of_scope (self)
-In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
-@code{return} command, @dots{}), a function may not properly terminate, and
-thus never hit the finish breakpoint. When @value{GDBN} notices such a
-situation, the @code{out_of_scope} callback will be triggered.
-
-You may want to sub-class @code{gdb.FinishBreakpoint} and override this
-method:
-
-@smallexample
-class MyFinishBreakpoint (gdb.FinishBreakpoint)
- def stop (self):
- print "normal finish"
- return True
-
- def out_of_scope ():
- print "abnormal finish"
-@end smallexample
-@end defun
-
-@defvar FinishBreakpoint.return_value
-When @value{GDBN} is stopped at a finish breakpoint and the frame
-used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
-attribute will contain a @code{gdb.Value} object corresponding to the return
-value of the function. The value will be @code{None} if the function return
-type is @code{void} or if the return value was not computable. This attribute
-is not writable.
-@end defvar
-
-@node Lazy Strings In Python
-@subsubsection Python representation of lazy strings.
-
-@cindex lazy strings in python
-@tindex gdb.LazyString
-
-A @dfn{lazy string} is a string whose contents is not retrieved or
-encoded until it is needed.
-
-A @code{gdb.LazyString} is represented in @value{GDBN} as an
-@code{address} that points to a region of memory, an @code{encoding}
-that will be used to encode that region of memory, and a @code{length}
-to delimit the region of memory that represents the string. The
-difference between a @code{gdb.LazyString} and a string wrapped within
-a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
-differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
-retrieved and encoded during printing, while a @code{gdb.Value}
-wrapping a string is immediately retrieved and encoded on creation.
-
-A @code{gdb.LazyString} object has the following functions:
-
-@defun LazyString.value ()
-Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
-will point to the string in memory, but will lose all the delayed
-retrieval, encoding and handling that @value{GDBN} applies to a
-@code{gdb.LazyString}.
-@end defun
-
-@defvar LazyString.address
-This attribute holds the address of the string. This attribute is not
-writable.
-@end defvar
-
-@defvar LazyString.length
-This attribute holds the length of the string in characters. If the
-length is -1, then the string will be fetched and encoded up to the
-first null of appropriate width. This attribute is not writable.
-@end defvar
-
-@defvar LazyString.encoding
-This attribute holds the encoding that will be applied to the string
-when the string is printed by @value{GDBN}. If the encoding is not
-set, or contains an empty string, then @value{GDBN} will select the
-most appropriate encoding when the string is printed. This attribute
-is not writable.
-@end defvar
-
-@defvar LazyString.type
-This attribute holds the type that is represented by the lazy string's
-type. For a lazy string this will always be a pointer type. To
-resolve this to the lazy string's character type, use the type's
-@code{target} method. @xref{Types In Python}. This attribute is not
-writable.
-@end defvar
-
-@node Architectures In Python
-@subsubsection Python representation of architectures
-@cindex Python architectures
-
-@value{GDBN} uses architecture specific parameters and artifacts in a
-number of its various computations. An architecture is represented
-by an instance of the @code{gdb.Architecture} class.
-
-A @code{gdb.Architecture} class has the following methods:
-
-@defun Architecture.name ()
-Return the name (string value) of the architecture.
-@end defun
-
-@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
-Return a list of disassembled instructions starting from the memory
-address @var{start_pc}. The optional arguments @var{end_pc} and
-@var{count} determine the number of instructions in the returned list.
-If both the optional arguments @var{end_pc} and @var{count} are
-specified, then a list of at most @var{count} disassembled instructions
-whose start address falls in the closed memory address interval from
-@var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
-specified, but @var{count} is specified, then @var{count} number of
-instructions starting from the address @var{start_pc} are returned. If
-@var{count} is not specified but @var{end_pc} is specified, then all
-instructions whose start address falls in the closed memory address
-interval from @var{start_pc} to @var{end_pc} are returned. If neither
-@var{end_pc} nor @var{count} are specified, then a single instruction at
-@var{start_pc} is returned. For all of these cases, each element of the
-returned list is a Python @code{dict} with the following string keys:
-
-@table @code
-
-@item addr
-The value corresponding to this key is a Python long integer capturing
-the memory address of the instruction.
-
-@item asm
-The value corresponding to this key is a string value which represents
-the instruction with assembly language mnemonics. The assembly
-language flavor used is the same as that specified by the current CLI
-variable @code{disassembly-flavor}. @xref{Machine Code}.
-
-@item length
-The value corresponding to this key is the length (integer value) of the
-instruction in bytes.
-
-@end table
-@end defun
-
-@node Python Auto-loading
-@subsection Python Auto-loading
-@cindex Python auto-loading
-
-When a new object file is read (for example, due to the @code{file}
-command, or because the inferior has loaded a shared library),
-@value{GDBN} will look for Python support scripts in several ways:
-@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
-@xref{Auto-loading extensions}.
-
-The auto-loading feature is useful for supplying application-specific
-debugging commands and scripts.
-
-Auto-loading can be enabled or disabled,
-and the list of auto-loaded scripts can be printed.
-
-@table @code
-@anchor{set auto-load python-scripts}
-@kindex set auto-load python-scripts
-@item set auto-load python-scripts [on|off]
-Enable or disable the auto-loading of Python scripts.
-
-@anchor{show auto-load python-scripts}
-@kindex show auto-load python-scripts
-@item show auto-load python-scripts
-Show whether auto-loading of Python scripts is enabled or disabled.
-
-@anchor{info auto-load python-scripts}
-@kindex info auto-load python-scripts
-@cindex print list of auto-loaded Python scripts
-@item info auto-load python-scripts [@var{regexp}]
-Print the list of all Python scripts that @value{GDBN} auto-loaded.
-
-Also printed is the list of Python scripts that were mentioned in
-the @code{.debug_gdb_scripts} section and were not found
-(@pxref{dotdebug_gdb_scripts section}).
-This is useful because their names are not printed when @value{GDBN}
-tries to load them and fails. There may be many of them, and printing
-an error message for each one is problematic.
-
-If @var{regexp} is supplied only Python scripts with matching names are printed.
-
-Example:
-
-@smallexample
-(gdb) info auto-load python-scripts
-Loaded Script
-Yes py-section-script.py
- full name: /tmp/py-section-script.py
-No my-foo-pretty-printers.py
-@end smallexample
-@end table
-
-When reading an auto-loaded file, @value{GDBN} sets the
-@dfn{current objfile}. This is available via the @code{gdb.current_objfile}
-function (@pxref{Objfiles In Python}). This can be useful for
-registering objfile-specific pretty-printers and frame-filters.
-
-@node Python modules
-@subsection Python modules
-@cindex python modules
-
-@value{GDBN} comes with several modules to assist writing Python code.
-
-@menu
-* gdb.printing:: Building and registering pretty-printers.
-* gdb.types:: Utilities for working with types.
-* gdb.prompt:: Utilities for prompt value substitution.
-@end menu
-
-@node gdb.printing
-@subsubsection gdb.printing
-@cindex gdb.printing
-
-This module provides a collection of utilities for working with
-pretty-printers.
-
-@table @code
-@item PrettyPrinter (@var{name}, @var{subprinters}=None)
-This class specifies the API that makes @samp{info pretty-printer},
-@samp{enable pretty-printer} and @samp{disable pretty-printer} work.
-Pretty-printers should generally inherit from this class.
-
-@item SubPrettyPrinter (@var{name})
-For printers that handle multiple types, this class specifies the
-corresponding API for the subprinters.
-
-@item RegexpCollectionPrettyPrinter (@var{name})
-Utility class for handling multiple printers, all recognized via
-regular expressions.
-@xref{Writing a Pretty-Printer}, for an example.
-
-@item FlagEnumerationPrinter (@var{name})
-A pretty-printer which handles printing of @code{enum} values. Unlike
-@value{GDBN}'s built-in @code{enum} printing, this printer attempts to
-work properly when there is some overlap between the enumeration
-constants. @var{name} is the name of the printer and also the name of
-the @code{enum} type to look up.
-
-@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
-Register @var{printer} with the pretty-printer list of @var{obj}.
-If @var{replace} is @code{True} then any existing copy of the printer
-is replaced. Otherwise a @code{RuntimeError} exception is raised
-if a printer with the same name already exists.
-@end table
-
-@node gdb.types
-@subsubsection gdb.types
-@cindex gdb.types
-
-This module provides a collection of utilities for working with
-@code{gdb.Type} objects.
-
-@table @code
-@item get_basic_type (@var{type})
-Return @var{type} with const and volatile qualifiers stripped,
-and with typedefs and C@t{++} references converted to the underlying type.
-
-C@t{++} example:
-
-@smallexample
-typedef const int const_int;
-const_int foo (3);
-const_int& foo_ref (foo);
-int main () @{ return 0; @}
-@end smallexample
-
-Then in gdb:
-
-@smallexample
-(gdb) start
-(gdb) python import gdb.types
-(gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
-(gdb) python print gdb.types.get_basic_type(foo_ref.type)
-int
-@end smallexample
-
-@item has_field (@var{type}, @var{field})
-Return @code{True} if @var{type}, assumed to be a type with fields
-(e.g., a structure or union), has field @var{field}.
-
-@item make_enum_dict (@var{enum_type})
-Return a Python @code{dictionary} type produced from @var{enum_type}.
-
-@item deep_items (@var{type})
-Returns a Python iterator similar to the standard
-@code{gdb.Type.iteritems} method, except that the iterator returned
-by @code{deep_items} will recursively traverse anonymous struct or
-union fields. For example:
-
-@smallexample
-struct A
-@{
- int a;
- union @{
- int b0;
- int b1;
- @};
-@};
-@end smallexample
-
-@noindent
-Then in @value{GDBN}:
-@smallexample
-(@value{GDBP}) python import gdb.types
-(@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
-(@value{GDBP}) python print struct_a.keys ()
-@{['a', '']@}
-(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
-@{['a', 'b0', 'b1']@}
-@end smallexample
-
-@item get_type_recognizers ()
-Return a list of the enabled type recognizers for the current context.
-This is called by @value{GDBN} during the type-printing process
-(@pxref{Type Printing API}).
-
-@item apply_type_recognizers (recognizers, type_obj)
-Apply the type recognizers, @var{recognizers}, to the type object
-@var{type_obj}. If any recognizer returns a string, return that
-string. Otherwise, return @code{None}. This is called by
-@value{GDBN} during the type-printing process (@pxref{Type Printing
-API}).
-
-@item register_type_printer (locus, printer)
-This is a convenience function to register a type printer.
-@var{printer} is the type printer to register. It must implement the
-type printer protocol. @var{locus} is either a @code{gdb.Objfile}, in
-which case the printer is registered with that objfile; a
-@code{gdb.Progspace}, in which case the printer is registered with
-that progspace; or @code{None}, in which case the printer is
-registered globally.
-
-@item TypePrinter
-This is a base class that implements the type printer protocol. Type
-printers are encouraged, but not required, to derive from this class.
-It defines a constructor:
-
-@defmethod TypePrinter __init__ (self, name)
-Initialize the type printer with the given name. The new printer
-starts in the enabled state.
-@end defmethod
-
-@end table
-
-@node gdb.prompt
-@subsubsection gdb.prompt
-@cindex gdb.prompt
-
-This module provides a method for prompt value-substitution.
-
-@table @code
-@item substitute_prompt (@var{string})
-Return @var{string} with escape sequences substituted by values. Some
-escape sequences take arguments. You can specify arguments inside
-``@{@}'' immediately following the escape sequence.
-
-The escape sequences you can pass to this function are:
-
-@table @code
-@item \\
-Substitute a backslash.
-@item \e
-Substitute an ESC character.
-@item \f
-Substitute the selected frame; an argument names a frame parameter.
-@item \n
-Substitute a newline.
-@item \p
-Substitute a parameter's value; the argument names the parameter.
-@item \r
-Substitute a carriage return.
-@item \t
-Substitute the selected thread; an argument names a thread parameter.
-@item \v
-Substitute the version of GDB.
-@item \w
-Substitute the current working directory.
-@item \[
-Begin a sequence of non-printing characters. These sequences are
-typically used with the ESC character, and are not counted in the string
-length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
-blue-colored ``(gdb)'' prompt where the length is five.
-@item \]
-End a sequence of non-printing characters.
-@end table
-
-For example:
-
-@smallexample
-substitute_prompt (``frame: \f,
- print arguments: \p@{print frame-arguments@}'')
-@end smallexample
-
-@exdent will return the string:
-
-@smallexample
-"frame: main, print arguments: scalars"
-@end smallexample
-@end table
+@c Guile docs live in a separate file.
+@include guile.texi
@node Auto-loading extensions
@section Auto-loading extensions
GDB's own command language
@item @file{@var{objfile}-gdb.py}
Python
+@item @file{@var{objfile}-gdb.scm}
+Guile
@end table
@var{script-name} is formed by ensuring that the file name of @var{objfile}
@end example
@noindent
+For Guile scripts, replace @code{.byte 1} with @code{.byte 3}.
Then one can reference the macro in a header or source file like this:
@example
top of the source tree to the source search path.
@end itemize
+@node Multiple Extension Languages
+@section Multiple Extension Languages
+
+The Guile and Python extension languages do not share any state,
+and generally do not interfere with each other.
+There are some things to be aware of, however.
+
+@subsection Python comes first
+
+Python was @value{GDBN}'s first extension language, and to avoid breaking
+existing behaviour Python comes first. This is generally solved by the
+``first one wins'' principle. @value{GDBN} maintains a list of enabled
+extension languages, and when it makes a call to an extension language,
+(say to pretty-print a value), it tries each in turn until an extension
+language indicates it has performed the request (e.g., has returned the
+pretty-printed form of a value).
+This extends to errors while performing such requests: If an error happens
+while, for example, trying to pretty-print an object then the error is
+reported and any following extension languages are not tried.
+
@node Aliases
@section Creating new spellings of existing commands
@cindex aliases for commands
@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
@item @var{exec-async-output} @expansion{}
-@code{[ @var{token} ] "*" @var{async-output}}
+@code{[ @var{token} ] "*" @var{async-output nl}}
@item @var{status-async-output} @expansion{}
-@code{[ @var{token} ] "+" @var{async-output}}
+@code{[ @var{token} ] "+" @var{async-output nl}}
@item @var{notify-async-output} @expansion{}
-@code{[ @var{token} ] "=" @var{async-output}}
+@code{[ @var{token} ] "=" @var{async-output nl}}
@item @var{async-output} @expansion{}
-@code{@var{async-class} ( "," @var{result} )* @var{nl}}
+@code{@var{async-class} ( "," @var{result} )*}
@item @var{result-class} @expansion{}
@code{"done" | "running" | "connected" | "error" | "exit"}
@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
@item @var{console-stream-output} @expansion{}
-@code{"~" @var{c-string}}
+@code{"~" @var{c-string nl}}
@item @var{target-stream-output} @expansion{}
-@code{"@@" @var{c-string}}
+@code{"@@" @var{c-string nl}}
@item @var{log-stream-output} @expansion{}
-@code{"&" @var{c-string}}
+@code{"&" @var{c-string nl}}
@item @var{nl} @expansion{}
@code{CR | CR-LF}
The current list of features is:
-@table @samp
+@ftable @samp
@item frozen-varobjs
Indicates support for the @code{-var-set-frozen} command, as well
as possible presense of the @code{frozen} field in the output
@item exec-run-start-option
Indicates that the @code{-exec-run} command supports the @option{--start}
option (@pxref{GDB/MI Program Execution}).
-@end table
+@end ftable
@subheading The @code{-list-target-features} Command
@findex -list-target-features
@item ?
@cindex @samp{?} packet
+@anchor{? packet}
Indicate the reason the target halted. The reply is the same as for
step and continue. This packet has a special interpretation when the
target is in non-stop mode; see @ref{Remote Non-Stop}.
@cindex @samp{k} packet
Kill request.
-FIXME: @emph{There is no description of how to operate when a specific
-thread context has been selected (i.e.@: does 'k' kill only that
-thread?)}.
+The exact effect of this packet is not specified.
+
+For a bare-metal target, it may power cycle or reset the target
+system. For that reason, the @samp{k} packet has no reply.
+
+For a single-process target, it may kill that process if possible.
+
+A multiple-process target may choose to kill just one process, or all
+that are under @value{GDBN}'s control. For more precise control, use
+the vKill packet (@pxref{vKill packet}).
+
+If the target system immediately closes the connection in response to
+@samp{k}, @value{GDBN} does not consider the lack of packet
+acknowledgment to be an error, and assumes the kill was successful.
+
+If connected using @kbd{target extended-remote}, and the target does
+not close the connection in response to a kill request, @value{GDBN}
+probes the target state as if a new connection was opened
+(@pxref{? packet}).
@item m @var{addr},@var{length}
@cindex @samp{m} packet
@item vKill;@var{pid}
@cindex @samp{vKill} packet
+@anchor{vKill packet}
Kill the process with the specified process ID. @var{pid} is a
hexadecimal integer identifying the process. This packet is used in
preference to @samp{k} when multiprocess protocol extensions are
@item new
Returns all available branch trace if the branch trace changed since
the last read request.
+
+@item delta
+Returns the new branch trace since the last read request. Adds a new
+block to the end of the trace that begins at zero and ends at the source
+location of the first branch in the trace buffer. This extra block is
+used to stitch traces together.
+
+If the trace buffer overflowed, returns an error indicating the overflow.
@end table
This packet is not probed by default; the remote stub must request it
The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
describe a single register, @samp{orig_eax}.
+The @samp{org.gnu.gdb.i386.avx512} feature is optional and requires the
+@samp{org.gnu.gdb.i386.avx} feature. It should
+describe additional @sc{xmm} registers:
+
+@itemize @minus
+@item
+@samp{xmm16h} through @samp{xmm31h}, only valid for amd64.
+@end itemize
+
+It should describe the upper 128 bits of additional @sc{ymm} registers:
+
+@itemize @minus
+@item
+@samp{ymm16h} through @samp{ymm31h}, only valid for amd64.
+@end itemize
+
+It should
+describe the upper 256 bits of @sc{zmm} registers:
+
+@itemize @minus
+@item
+@samp{zmm0h} through @samp{zmm7h} for i386.
+@item
+@samp{zmm0h} through @samp{zmm15h} for amd64.
+@end itemize
+
+It should
+describe the additional @sc{zmm} registers:
+
+@itemize @minus
+@item
+@samp{zmm16h} through @samp{zmm31h}, only valid for amd64.
+@end itemize
+
@node MIPS Features
@subsection @acronym{MIPS} Features
@cindex target descriptions, @acronym{MIPS} features
This option is intended for @code{gdbserver} development and for bug reports to
the developers.
+@item --debug-format=option1@r{[},option2,...@r{]}
+Instruct @code{gdbserver} to include extra information in each line
+of debugging output.
+@xref{Other Command-Line Arguments for gdbserver}.
+
@item --wrapper
Specify a wrapper to launch programs
for debugging. The option should be followed by the name of the
projects / deliverable / binutils-gdb.git / blobdiff