\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
@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
You can run @code{@value{GDBP}} without printing the front material, which describes
-@value{GDBN}'s non-warranty, by specifying @code{-silent}:
+@value{GDBN}'s non-warranty, by specifying @code{--silent}
+(or @code{-q}/@code{--quiet}):
@smallexample
-@value{GDBP} -silent
+@value{GDBP} --silent
@end smallexample
@noindent
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}.
@item run
@itemx r
Use the @code{run} command to start your program under @value{GDBN}.
-You must first specify the program name (except on VxWorks) with an
-argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
-@value{GDBN}}), or by using the @code{file} or @code{exec-file} command
-(@pxref{Files, ,Commands to Specify Files}).
+You must first specify the program name with an argument to
+@value{GDBN} (@pxref{Invocation, ,Getting In and Out of
+@value{GDBN}}), or by using the @code{file} or @code{exec-file}
+command (@pxref{Files, ,Commands to Specify Files}).
@end table
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
$@file{.zshenv} for the Z shell, or the file specified in the
@samp{BASH_ENV} environment variable for BASH.
+@anchor{set auto-connect-native-target}
+@kindex set auto-connect-native-target
+@item set auto-connect-native-target
+@itemx set auto-connect-native-target on
+@itemx set auto-connect-native-target off
+@itemx show auto-connect-native-target
+
+By default, if not connected to any target yet (e.g., with
+@code{target remote}), the @code{run} command starts your program as a
+native process under @value{GDBN}, on your local machine. If you're
+sure you don't want to debug programs on your local machine, you can
+tell @value{GDBN} to not connect to the native target automatically
+with the @code{set auto-connect-native-target off} command.
+
+If @code{on}, which is the default, and if @value{GDBN} is not
+connected to a target already, the @code{run} command automaticaly
+connects to the native target, if one is available.
+
+If @code{off}, and if @value{GDBN} is not connected to a target
+already, the @code{run} command fails with an error:
+
+@smallexample
+(@value{GDBP}) run
+Don't know how to run. Try "help target".
+@end smallexample
+
+If @value{GDBN} is already connected to a target, @value{GDBN} always
+uses it with the @code{run} command.
+
+In any case, you can explicitly connect to the native target with the
+@code{target native} command. For example,
+
+@smallexample
+(@value{GDBP}) set auto-connect-native-target off
+(@value{GDBP}) run
+Don't know how to run. Try "help target".
+(@value{GDBP}) target native
+(@value{GDBP}) run
+Starting program: ./a.out
+[Inferior 1 (process 10421) exited normally]
+@end smallexample
+
+In case you connected explicitly to the @code{native} target,
+@value{GDBN} remains connected even if all inferiors exit, ready for
+the next @code{run} command. Use the @code{disconnect} command to
+disconnect.
+
+Examples of other commands that likewise respect the
+@code{auto-connect-native-target} setting: @code{attach}, @code{info
+proc}, @code{info os}.
+
@kindex set disable-randomization
@item set disable-randomization
@itemx set disable-randomization on
@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. The @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
@kindex add-inferior
@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
Adds @var{n} inferiors to be run using @var{executable} as the
-executable. @var{n} defaults to 1. If no executable is specified,
+executable; @var{n} defaults to 1. If no executable is specified,
the inferiors begins empty, with no program. You can still assign or
change the program assigned to the inferior at any time by using the
@code{file} command with the executable name as its argument.
@kindex clone-inferior
@item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
Adds @var{n} inferiors ready to execute the same program as inferior
-@var{infno}. @var{n} defaults to 1. @var{infno} defaults to the
+@var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the
number of the current inferior. This is a convenient command when you
want to run another instance of the inferior you are debugging.
@c thread without first checking `info threads'.
Whenever @value{GDBN} detects a new thread in your program, it displays
the target system's identification for the thread with a message in the
-form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
+form @samp{[New @var{systag}]}, where @var{systag} is a thread identifier
whose form varies depending on the particular system. For example, on
@sc{gnu}/Linux, you might see
@kindex tbreak
@item tbreak @var{args}
-Set a breakpoint enabled only for one stop. @var{args} are the
+Set a breakpoint enabled only for one stop. The @var{args} are the
same as for the @code{break} command, and the breakpoint is set in the same
way, but the breakpoint is automatically deleted after the first time your
program stops there. @xref{Disabling, ,Disabling Breakpoints}.
@kindex hbreak
@cindex hardware breakpoints
@item hbreak @var{args}
-Set a hardware-assisted breakpoint. @var{args} are the same as for the
+Set a hardware-assisted breakpoint. The @var{args} are the same as for the
@code{break} command and the breakpoint is set in the same way, but the
breakpoint requires hardware support and some target hardware may not
have this support. The main purpose of this is EPROM/ROM code
@kindex thbreak
@item thbreak @var{args}
-Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
+Set a hardware-assisted breakpoint enabled only for one stop. The @var{args}
are the same as for the @code{hbreak} command and the breakpoint is set in
the same way. However, like the @code{tbreak} command,
the breakpoint is automatically deleted after the
@item set breakpoint always-inserted off
All breakpoints, including newly added by the user, are inserted in
the target only when the target is resumed. All breakpoints are
-removed from the target when it stops.
+removed from the target when it stops. This is the default mode.
@item set breakpoint always-inserted on
Causes all breakpoints to be inserted in the target at all times. If
the user adds a new breakpoint, or changes an existing breakpoint, the
breakpoints in the target are updated immediately. A breakpoint is
-removed from the target only when breakpoint itself is removed.
-
-@cindex non-stop mode, and @code{breakpoint always-inserted}
-@item set breakpoint always-inserted auto
-This is the default mode. If @value{GDBN} is controlling the inferior
-in non-stop mode (@pxref{Non-Stop Mode}), gdb behaves as if
-@code{breakpoint always-inserted} mode is on. If @value{GDBN} is
-controlling the inferior in all-stop mode, @value{GDBN} behaves as if
-@code{breakpoint always-inserted} mode is off.
+removed from the target only when breakpoint itself is deleted.
@end table
@value{GDBN} handles conditional breakpoints by evaluating these conditions
@table @code
@kindex catch
@item catch @var{event}
-Stop when @var{event} occurs. @var{event} can be any of the following:
+Stop when @var{event} occurs. The @var{event} can be any of the following:
@table @code
@item throw @r{[}@var{regexp}@r{]}
particular command you use). Either when continuing or when stepping,
your program may stop even sooner, due to a breakpoint or a signal. (If
it stops due to a signal, you may want to use @code{handle}, or use
-@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
+@samp{signal 0} to resume execution (@pxref{Signals, ,Signals}),
+or you may step into the signal's handler (@pxref{stepping and signal
+handlers}).)
@table @code
@kindex continue
@item until @var{location}
@itemx u @var{location}
-Continue running your program until either the specified location is
-reached, or the current stack frame returns. @var{location} is any of
+Continue running your program until either the specified @var{location} is
+reached, or the current stack frame returns. The location is any of
the forms described in @ref{Specify Location}.
This form of the command uses temporary breakpoints, and
hence is quicker than @code{until} without an argument. The specified
@kindex handle
@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
-Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
+Change the way @value{GDBN} handles signal @var{signal}. The @var{signal}
can be the number of a signal or its name (with or without the
@samp{SIG} at the beginning); a list of signal numbers of the form
@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
Program a Signal}.
+@cindex stepping and signal handlers
+@anchor{stepping and signal handlers}
+
+@value{GDBN} optimizes for stepping the mainline code. If a signal
+that has @code{handle nostop} and @code{handle pass} set arrives while
+a stepping command (e.g., @code{stepi}, @code{step}, @code{next}) is
+in progress, @value{GDBN} lets the signal handler run and then resumes
+stepping the mainline code once the signal handler returns. In other
+words, @value{GDBN} steps over the signal handler. This prevents
+signals that you've specified as not interesting (with @code{handle
+nostop}) from changing the focus of debugging unexpectedly. Note that
+the signal handler itself may still hit a breakpoint, stop for another
+signal that has @code{handle stop} in effect, or for any other event
+that normally results in stopping the stepping command sooner. Also
+note that @value{GDBN} still informs you that the program received a
+signal if @code{handle print} is set.
+
+@anchor{stepping into signal handlers}
+
+If you set @code{handle pass} for a signal, and your program sets up a
+handler for it, then issuing a stepping command, such as @code{step}
+or @code{stepi}, when your program is stopped due to the signal will
+step @emph{into} the signal handler (if the target supports that).
+
+Likewise, if you use the @code{queue-signal} command to queue a signal
+to be delivered to the current thread when execution of the thread
+resumes (@pxref{Signaling, ,Giving your Program a Signal}), then a
+stepping command will step into the signal handler.
+
+Here's an example, using @code{stepi} to step to the first instruction
+of @code{SIGUSR1}'s handler:
+
+@smallexample
+(@value{GDBP}) handle SIGUSR1
+Signal Stop Print Pass to program Description
+SIGUSR1 Yes Yes Yes User defined signal 1
+(@value{GDBP}) c
+Continuing.
+
+Program received signal SIGUSR1, User defined signal 1.
+main () sigusr1.c:28
+28 p = 0;
+(@value{GDBP}) si
+sigusr1_handler () at sigusr1.c:9
+9 @{
+@end smallexample
+
+The same, but using @code{queue-signal} instead of waiting for the
+program to receive the signal first:
+
+@smallexample
+(@value{GDBP}) n
+28 p = 0;
+(@value{GDBP}) queue-signal SIGUSR1
+(@value{GDBP}) si
+sigusr1_handler () at sigusr1.c:9
+9 @{
+(@value{GDBP})
+@end smallexample
+
@cindex extra signal information
@anchor{extra signal information}
@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.
-set target-async 1
-
# If using the CLI, pagination breaks non-stop.
set pagination off
@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.
-You need to explicitly enable asynchronous mode before you can use
-background execution commands. You can use these commands to
-manipulate the asynchronous mode setting:
-
-@table @code
-@kindex set target-async
-@item set target-async on
-Enable asynchronous mode.
-@item set target-async off
-Disable asynchronous mode.
-@kindex show target-async
-@item show target-async
-Show the current target-async setting.
-@end table
-
If the target doesn't support async mode, @value{GDBN} issues an error
message if you attempt to use the background execution commands.
@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
Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
-particular thread reaches this breakpoint. @var{threadno} is one of the
-numeric thread identifiers assigned by @value{GDBN}, shown in the first
-column of the @samp{info threads} display.
+particular thread reaches this breakpoint. The @var{threadno} specifier
+is one of the numeric thread identifiers assigned by @value{GDBN}, shown
+in the first column of the @samp{info threads} display.
If you do not specify @samp{thread @var{threadno}} when you set a
breakpoint, the breakpoint applies to @emph{all} threads of your
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 show record full memory-query
Show the current setting of @code{memory-query}.
+@kindex set record btrace
+The @code{btrace} record target does not trace data. As a
+convenience, when replaying, @value{GDBN} reads read-only memory off
+the live program directly, assuming that the addresses of the
+read-only areas don't change. This for example makes it possible to
+disassemble code while replaying, but not to print variables.
+In some cases, being able to inspect variables might be useful.
+You can use the following command for that:
+
+@item set record btrace replay-memory-access
+Control the behavior of the @code{btrace} recording method when
+accessing memory during replay. If @code{read-only} (the default),
+@value{GDBN} will only allow accesses to read-only memory.
+If @code{read-write}, @value{GDBN} will allow accesses to read-only
+and to read-write memory. Beware that the accessed memory corresponds
+to the live target and not necessarily to the current replay
+position.
+
+@kindex show record btrace
+@item show record btrace replay-memory-access
+Show the current setting of @code{replay-memory-access}.
+
@kindex info record
@item info record
Show various statistics about the recording depending on the recording
@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 frame@r{, command}
@cindex current stack frame
-@item frame @var{args}
+@item frame @r{[}@var{framespec}@r{]}
The @code{frame} command allows you to move from one stack frame to another,
-and to print the stack frame you select. @var{args} may be either the
+and to print the stack frame you select. The @var{framespec} may be either the
address of the frame or the stack frame number. Without an argument,
@code{frame} prints the current stack frame.
@itemx bt full
@itemx bt full @var{n}
@itemx bt full -@var{n}
-Print the values of the local variables also. @var{n} specifies the
-number of frames to print, as described above.
+Print the values of the local variables also. As described above,
+@var{n} specifies the number of frames to print.
@item backtrace no-filters
@itemx bt no-filters
@anchor{disable frame-filter all}
@item disable frame-filter @var{filter-dictionary} @var{filter-name}
Disable a frame filter in the dictionary matching
-@var{filter-dictionary}, or @code{all}, and @var{filter-name}.
+@var{filter-dictionary} and @var{filter-name}. The
@var{filter-dictionary} may be @code{all}, @code{global},
-@code{progspace} or the name of the object file where the frame filter
+@code{progspace}, or the name of the object file where the frame filter
dictionary resides. When @code{all} is specified, all frame filters
-across all dictionaries are disabled. @var{filter-name} is the name
+across all dictionaries are disabled. The @var{filter-name} is the name
of the frame filter and is used when @code{all} is not the option for
@var{filter-dictionary}. A disabled frame-filter is not deleted, it
may be enabled again later.
@kindex enable frame-filter
@item enable frame-filter @var{filter-dictionary} @var{filter-name}
Enable a frame filter in the dictionary matching
-@var{filter-dictionary}, or @code{all}, and @var{filter-name}.
+@var{filter-dictionary} and @var{filter-name}. The
@var{filter-dictionary} may be @code{all}, @code{global},
@code{progspace} or the name of the object file where the frame filter
dictionary resides. When @code{all} is specified, all frame filters across
-all dictionaries are enabled. @var{filter-name} is the name of the frame
+all dictionaries are enabled. The @var{filter-name} is the name of the frame
filter and is used when @code{all} is not the option for
@var{filter-dictionary}.
@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority}
Set the @var{priority} of a frame filter in the dictionary matching
@var{filter-dictionary}, and the frame filter name matching
-@var{filter-name}. @var{filter-dictionary} may be @code{global},
+@var{filter-name}. The @var{filter-dictionary} may be @code{global},
@code{progspace} or the name of the object file where the frame filter
-dictionary resides. @var{priority} is an integer.
+dictionary resides. The @var{priority} is an integer.
@kindex show frame-filter priority
@item show frame-filter priority @var{filter-dictionary} @var{filter-name}
Show the @var{priority} of a frame filter in the dictionary matching
@var{filter-dictionary}, and the frame filter name matching
-@var{filter-name}. @var{filter-dictionary} may be @code{global},
+@var{filter-name}. The @var{filter-dictionary} may be @code{global},
@code{progspace} or the name of the object file where the frame filter
dictionary resides.
@kindex up
@item up @var{n}
-Move @var{n} frames up the stack. For positive numbers @var{n}, this
-advances toward the outermost frame, to higher frame numbers, to frames
-that have existed longer. @var{n} defaults to one.
+Move @var{n} frames up the stack; @var{n} defaults to 1. For positive
+numbers @var{n}, this advances toward the outermost frame, to higher
+frame numbers, to frames that have existed longer.
@kindex down
@kindex do @r{(@code{down})}
@item down @var{n}
-Move @var{n} frames down the stack. For positive numbers @var{n}, this
-advances toward the innermost frame, to lower frame numbers, to frames
-that were created more recently. @var{n} defaults to one. You may
-abbreviate @code{down} as @code{do}.
+Move @var{n} frames down the stack; @var{n} defaults to 1. For
+positive numbers @var{n}, this advances toward the innermost frame, to
+lower frame numbers, to frames that were created more recently.
+You may abbreviate @code{down} as @code{do}.
@end table
All of these commands end by printing two lines of output describing the
@cindex casts, to view memory
@item @{@var{type}@} @var{addr}
Refers to an object of type @var{type} stored at address @var{addr} in
-memory. @var{addr} may be any expression whose value is an integer or
-pointer (but parentheses are required around binary operators, just as in
-a cast). This construct is allowed regardless of what kind of data is
-normally supposed to reside at @var{addr}.
+memory. The address @var{addr} may be any expression whose value is
+an integer or pointer (but parentheses are required around binary
+operators, just as in a cast). This construct is allowed regardless
+of what kind of data is normally supposed to reside at @var{addr}.
@end table
@node Ambiguous Expressions
address printed if several units were printed on the last line of output.
@cindex remote memory comparison
+@cindex target memory comparison
@cindex verify remote memory image
+@cindex verify target memory image
When you are debugging a program running on a remote target machine
-(@pxref{Remote Debugging}), you may wish to verify the program's image in the
-remote machine's memory against the executable file you downloaded to
-the target. The @code{compare-sections} command is provided for such
-situations.
+(@pxref{Remote Debugging}), you may wish to verify the program's image
+in the remote machine's memory against the executable file you
+downloaded to the target. Or, on any target, you may want to check
+whether the program has corrupted its own read-only sections. The
+@code{compare-sections} command is provided for such situations.
@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
-availability depends on the target's support for the @code{"qCRC"}
-remote request.
+the target machine's memory, and report any mismatches. With no
+arguments, compares all loadable sections. With an argument of
+@code{-r}, compares all loadable read-only sections.
+
+Note: for remote targets, this command can be accelerated if the
+target supports computing the CRC checksum of a block of memory
+(@pxref{qCRC packet}).
@end table
@node Auto Display
@findex $_strlen@r{, convenience function}
Returns the length of string @var{str}.
+@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
+@findex $_caller_is@r{, convenience function}
+Returns one if the calling function's name is equal to @var{name}.
+Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+Example:
+
+@smallexample
+(gdb) backtrace
+#0 bottom_func ()
+ at testsuite/gdb.python/py-caller-is.c:21
+#1 0x00000000004005a0 in middle_func ()
+ at testsuite/gdb.python/py-caller-is.c:27
+#2 0x00000000004005ab in top_func ()
+ at testsuite/gdb.python/py-caller-is.c:33
+#3 0x00000000004005b6 in main ()
+ at testsuite/gdb.python/py-caller-is.c:39
+(gdb) print $_caller_is ("middle_func")
+$1 = 1
+(gdb) print $_caller_is ("top_func", 2)
+$1 = 1
+@end smallexample
+
+@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
+@findex $_caller_matches@r{, convenience function}
+Returns one if the calling function's name matches the regular expression
+@var{regexp}. Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
+@findex $_any_caller_is@r{, convenience function}
+Returns one if any calling function's name is equal to @var{name}.
+Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+This function differs from @code{$_caller_is} in that this function
+checks all stack frames from the immediate caller to the frame specified
+by @var{number_of_frames}, whereas @code{$_caller_is} only checks the
+frame specified by @var{number_of_frames}.
+
+@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
+@findex $_any_caller_matches@r{, convenience function}
+Returns one if any calling function's name matches the regular expression
+@var{regexp}. Otherwise it returns zero.
+
+If the optional argument @var{number_of_frames} is provided,
+it is the number of frames up in the stack to look.
+The default is 1.
+
+This function differs from @code{$_caller_matches} in that this function
+checks all stack frames from the immediate caller to the frame specified
+by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the
+frame specified by @var{number_of_frames}.
+
@end table
@value{GDBN} provides the ability to list and get help on
@item info registers @var{regname} @dots{}
Print the @dfn{relativized} value of each specified register @var{regname}.
As discussed in detail below, register values are normally relative to
-the selected stack frame. @var{regname} may be any register name valid on
+the selected stack frame. The @var{regname} may be any register name valid on
the machine you are using, with or without the initial @samp{$}.
@end table
@kindex tvariable
The @code{tvariable} command creates a new trace state variable named
@code{$@var{name}}, and optionally gives it an initial value of
-@var{expression}. @var{expression} is evaluated when this command is
+@var{expression}. The @var{expression} is evaluated when this command is
entered; the result will be converted to an integer if possible,
otherwise @value{GDBN} will report an error. A subsequent
@code{tvariable} command specifying the same name does not create a
a live target, but it is not possible to run any new trace experiments.
@code{tstatus} will report the state of the trace run at the moment
the data was saved, as well as the current trace frame you are examining.
-@var{filename} or @var{dirname} must be on a filesystem accessible to
+Both @var{filename} and @var{dirname} must be on a filesystem accessible to
the host.
@smallexample
@item @var{op}=
Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
and translated to @w{@code{@var{a} = @var{a op b}}}.
-@w{@code{@var{op}=}} and @code{=} have the same precedence.
+@w{@code{@var{op}=}} and @code{=} have the same precedence. The operator
@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
@item ?:
The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
-of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
-integral type.
+of as: if @var{a} then @var{b} else @var{c}. The argument @var{a}
+should be of an integral type.
@item ||
Logical @sc{or}. Defined on integral types.
@item ORD(@var{x})
Returns the ordinal value of its argument. For example, the ordinal
-value of a character is its @sc{ascii} value (on machines supporting the
-@sc{ascii} character set). @var{x} must be of an ordered type, which include
-integral, character and enumerated types.
+value of a character is its @sc{ascii} value (on machines supporting
+the @sc{ascii} character set). The argument @var{x} must be of an
+ordered type, which include integral, character and enumerated types.
@item SIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+Returns the size of its argument. The argument @var{x} can be a
+variable or a type.
@item TRUNC(@var{r})
Returns the integral part of @var{r}.
@item TSIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+Returns the size of its argument. The argument @var{x} can be a
+variable or a type.
@item VAL(@var{t},@var{i})
Returns the member of the type @var{t} whose ordinal value is @var{i}.
@cindex task breakpoints, in Ada
@kindex break @dots{} task @var{taskno}@r{ (Ada)}
These commands are like the @code{break @dots{} thread @dots{}}
-command (@pxref{Thread Stops}).
-@var{linespec} specifies source lines, as described
+command (@pxref{Thread Stops}). The
+@var{linespec} argument specifies source lines, as described
in @ref{Specify Location}.
Use the qualifier @samp{task @var{taskno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
-particular Ada task reaches this breakpoint. @var{taskno} is one of the
+particular Ada task reaches this breakpoint. The @var{taskno} is one of the
numeric task identifiers assigned by @value{GDBN}, shown in the first
column of the @samp{info tasks} display.
tasking support may be limited or even unavailable, depending on
the platform being used.
For instance, on x86-linux, the list of tasks is available, but task
-switching is not supported. On Tru64, however, task switching will work
-as usual.
+switching is not supported.
-On certain platforms, including Tru64, the debugger needs to perform some
+On certain platforms, the debugger needs to perform some
memory writes in order to provide Ada tasking support. When inspecting
a core file, this means that the core file must be opened with read-write
privileges, using the command @samp{"set write on"} (@pxref{Patching}).
@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
@table @code
@kindex signal
@item signal @var{signal}
-Resume execution where your program stopped, but immediately give it the
-signal @var{signal}. @var{signal} can be the name or the number of a
+Resume execution where your program is stopped, but immediately give it the
+signal @var{signal}. The @var{signal} can be the name or the number of a
signal. For example, on many systems @code{signal 2} and @code{signal
SIGINT} are both ways of sending an interrupt signal.
@code{continue} command; @samp{signal 0} causes it to resume without a
signal.
-@code{signal} does not repeat when you press @key{RET} a second time
-after executing the command.
-@end table
-@c @end group
+@emph{Note:} When resuming a multi-threaded program, @var{signal} is
+delivered to the currently selected thread, not the thread that last
+reported a stop. This includes the situation where a thread was
+stopped due to a signal. So if you want to continue execution
+suppressing the signal that stopped a thread, you should select that
+same thread before issuing the @samp{signal 0} command. If you issue
+the @samp{signal 0} command with another thread as the selected one,
+@value{GDBN} detects that and asks for confirmation.
Invoking the @code{signal} command is not the same as invoking the
@code{kill} utility from the shell. Sending a signal with @code{kill}
the signal handling tables (@pxref{Signals}). The @code{signal} command
passes the signal directly to your program.
+@code{signal} does not repeat when you press @key{RET} a second time
+after executing the command.
+
+@kindex queue-signal
+@item queue-signal @var{signal}
+Queue @var{signal} to be delivered immediately to the current thread
+when execution of the thread resumes. The @var{signal} can be the name or
+the number of a signal. For example, on many systems @code{signal 2} and
+@code{signal SIGINT} are both ways of sending an interrupt signal.
+The handling of the signal must be set to pass the signal to the program,
+otherwise @value{GDBN} will report an error.
+You can control the handling of signals from @value{GDBN} with the
+@code{handle} command (@pxref{Signals}).
+
+Alternatively, if @var{signal} is zero, any currently queued signal
+for the current thread is discarded and when execution resumes no signal
+will be delivered. This is useful when your program stopped on account
+of a signal and would ordinarily see the signal when resumed with the
+@code{continue} command.
+
+This command differs from the @code{signal} command in that the signal
+is just queued, execution is not resumed. And @code{queue-signal} cannot
+be used to pass a signal whose handling state has been set to @code{nopass}
+(@pxref{Signals}).
+@end table
+@c @end group
+
+@xref{stepping into signal handlers}, for information on how stepping
+commands behave when the thread has a signal queued.
@node Returning
@section Returning from a Function
@cindex inferior functions, calling
@item print @var{expr}
Evaluate the expression @var{expr} and display the resulting value.
-@var{expr} may include calls to functions in the program being
+The expression may include calls to functions in the program being
debugged.
@kindex call
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
when @var{filename} has been dynamically loaded (by some other means)
-into the program that is running. @var{address} should be the memory
+into the program that is running. The @var{address} should give the memory
address at which the file has been loaded; @value{GDBN} cannot figure
this out for itself. You can additionally specify an arbitrary number
of @samp{-s @var{section} @var{address}} pairs, to give an explicit
@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}).
CRC.
@emph{Note:} This is the same CRC polynomial as used in handling the
-@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{Remote Protocol,
-, @value{GDBN} Remote Serial Protocol}). However in the
-case of the Remote Serial Protocol, the CRC is computed @emph{most}
-significant bit first, and the result is not inverted, so trailing
-zeros have no effect on the CRC value.
+@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{qCRC packet}).
+However in the case of the Remote Serial Protocol, the CRC is computed
+@emph{most} significant bit first, and the result is not inverted, so
+trailing zeros have no effect on the CRC value.
To complete the description, we show below the code of the function
which produces the CRC used in @code{.gnu_debuglink}. Inverting the
see the appropriate section in @ref{Embedded Processors, ,Embedded
Processors}.
+@item target native
+@cindex native target
+Setup for local/native process debugging. Useful to make the
+@code{run} command spawn native processes (likewise @code{attach},
+etc.@:) even when @code{set auto-connect-native-target} is @code{off}
+(@pxref{set auto-connect-native-target}).
+
@end table
Different targets are available on different configurations of @value{GDBN};
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
way of knowing what the exception handling tables on your target system
are like (for example, the processor's table might be in @sc{rom},
containing entries which point to a table in @sc{ram}).
-@var{exception_number} is the exception number which should be changed;
+The @var{exception_number} specifies the exception which should be changed;
its meaning is architecture-dependent (for example, different numbers
might represent divide by zero, misaligned access, etc). When this
exception occurs, control should be transferred directly to
facility, the command @code{info proc} is available to report
information about the process running your program, or about any
process running on your system. This includes, as of this writing,
-@sc{gnu}/Linux, OSF/1 (Digital Unix), Solaris, and Irix, but
-not HP-UX, for example.
+@sc{gnu}/Linux and Solaris, but not HP-UX, for example.
This command may also work on core files that were created on a system
that has the @samp{/proc} facility.
@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
embedded operating systems that are available for several different
architectures.
-@menu
-* VxWorks:: Using @value{GDBN} with VxWorks
-@end menu
-
@value{GDBN} includes the ability to debug programs running on
various real-time operating systems.
-@node VxWorks
-@subsection Using @value{GDBN} with VxWorks
-
-@cindex VxWorks
-
-@table @code
-
-@kindex target vxworks
-@item target vxworks @var{machinename}
-A VxWorks system, attached via TCP/IP. The argument @var{machinename}
-is the target system's machine name or IP address.
-
-@end table
-
-On VxWorks, @code{load} links @var{filename} dynamically on the
-current target system as well as adding its symbols in @value{GDBN}.
-
-@value{GDBN} enables developers to spawn and debug tasks running on networked
-VxWorks targets from a Unix host. Already-running tasks spawned from
-the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
-both the Unix host and on the VxWorks target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
-installed with the name @code{vxgdb}, to distinguish it from a
-@value{GDBN} for debugging programs on the host itself.)
-
-@table @code
-@item VxWorks-timeout @var{args}
-@kindex vxworks-timeout
-All VxWorks-based targets now support the option @code{vxworks-timeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses to rpc's. You might use this if
-your VxWorks target is a slow software simulator or is on the far side
-of a thin network line.
-@end table
-
-The following information on connecting to VxWorks was current when
-this manual was produced; newer releases of VxWorks may use revised
-procedures.
-
-@findex INCLUDE_RDB
-To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
-to include the remote debugging interface routines in the VxWorks
-library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
-VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
-kernel. The resulting kernel contains @file{rdb.a}, and spawns the
-source debugging task @code{tRdbTask} when VxWorks is booted. For more
-information on configuring and remaking VxWorks, see the manufacturer's
-manual.
-@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
-
-Once you have included @file{rdb.a} in your VxWorks system image and set
-your Unix execution search path to find @value{GDBN}, you are ready to
-run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
-@code{vxgdb}, depending on your installation).
-
-@value{GDBN} comes up showing the prompt:
-
-@smallexample
-(vxgdb)
-@end smallexample
-
-@menu
-* VxWorks Connection:: Connecting to VxWorks
-* VxWorks Download:: VxWorks download
-* VxWorks Attach:: Running tasks
-@end menu
-
-@node VxWorks Connection
-@subsubsection Connecting to VxWorks
-
-The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
-network. To connect to a target whose host name is ``@code{tt}'', type:
-
-@smallexample
-(vxgdb) target vxworks tt
-@end smallexample
-
-@need 750
-@value{GDBN} displays messages like these:
-
-@smallexample
-Attaching remote machine across net...
-Connected to tt.
-@end smallexample
-
-@need 1000
-@value{GDBN} then attempts to read the symbol tables of any object modules
-loaded into the VxWorks target since it was last booted. @value{GDBN} locates
-these files by searching the directories listed in the command search
-path (@pxref{Environment, ,Your Program's Environment}); if it fails
-to find an object file, it displays a message such as:
-
-@smallexample
-prog.o: No such file or directory.
-@end smallexample
-
-When this happens, add the appropriate directory to the search path with
-the @value{GDBN} command @code{path}, and execute the @code{target}
-command again.
-
-@node VxWorks Download
-@subsubsection VxWorks Download
-
-@cindex download to VxWorks
-If you have connected to the VxWorks target and you want to debug an
-object that has not yet been loaded, you can use the @value{GDBN}
-@code{load} command to download a file from Unix to VxWorks
-incrementally. The object file given as an argument to the @code{load}
-command is actually opened twice: first by the VxWorks target in order
-to download the code, then by @value{GDBN} in order to read the symbol
-table. This can lead to problems if the current working directories on
-the two systems differ. If both systems have NFS mounted the same
-filesystems, you can avoid these problems by using absolute paths.
-Otherwise, it is simplest to set the working directory on both systems
-to the directory in which the object file resides, and then to reference
-the file by its name, without any path. For instance, a program
-@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
-and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
-program, type this on VxWorks:
-
-@smallexample
--> cd "@var{vxpath}/vw/demo/rdb"
-@end smallexample
-
-@noindent
-Then, in @value{GDBN}, type:
-
-@smallexample
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
-(vxgdb) load prog.o
-@end smallexample
-
-@value{GDBN} displays a response similar to this:
-
-@smallexample
-Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
-@end smallexample
-
-You can also use the @code{load} command to reload an object module
-after editing and recompiling the corresponding source file. Note that
-this makes @value{GDBN} delete all currently-defined breakpoints,
-auto-displays, and convenience variables, and to clear the value
-history. (This is necessary in order to preserve the integrity of
-debugger's data structures that reference the target system's symbol
-table.)
-
-@node VxWorks Attach
-@subsubsection Running Tasks
-
-@cindex running VxWorks tasks
-You can also attach to an existing task using the @code{attach} command as
-follows:
-
-@smallexample
-(vxgdb) attach @var{task}
-@end smallexample
-
-@noindent
-where @var{task} is the VxWorks hexadecimal task ID. The task can be running
-or suspended when you attach to it. Running tasks are suspended at
-the time of attachment.
-
@node Embedded Processors
@section Embedded Processors
@table @code
@item --swi-support=@var{type}
-Tell the simulator which SWI interfaces to support.
+Tell the simulator which SWI interfaces to support. The argument
@var{type} may be a comma separated list of the following values.
The default value is @code{all}.
@table @code
@kindex break-range
@item break-range @var{start-location}, @var{end-location}
-Set a breakpoint for an address range.
-@var{start-location} and @var{end-location} can specify a function name,
+Set a breakpoint for an address range given by
+@var{start-location} and @var{end-location}, which can specify a function name,
a line number, an offset of lines from the current line or from the start
location, or an address of an instruction (see @ref{Specify Location},
for a list of all the possible ways to specify a @var{location}.)
@item remotetimeout @var{args}
@kindex remotetimeout
@value{GDBN} supports the option @code{remotetimeout}.
-This option is set by the user, and @var{args} represents the number of
+This option is set by the user, and @var{args} represents the number of
seconds @value{GDBN} waits for responses.
@end table
@node Screen Size
@section Screen Size
@cindex size of screen
+@cindex screen size
+@cindex pagination
+@cindex page size
@cindex pauses in output
Certain commands to @value{GDBN} may produce large amounts of
@kindex set input-radix
@item set input-radix @var{base}
Set the default base for numeric input. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+for @var{base} are decimal 8, 10, or 16. The base must itself be
specified either unambiguously or using the current input radix; for
example, any of
@kindex set output-radix
@item set output-radix @var{base}
Set the default base for numeric display. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+for @var{base} are decimal 8, 10, or 16. The base must itself be
specified either unambiguously or using the current input radix.
@kindex show input-radix
results or introduce security risks (e.g., if the file comes from untrusted
sources).
+@menu
+* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit}
+* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db}
+
+* Auto-loading safe path:: @samp{set/show/info auto-load safe-path}
+* Auto-loading verbose mode:: @samp{set/show debug auto-load}
+@end menu
+
+There are various kinds of files @value{GDBN} can automatically load.
+In addition to these files, @value{GDBN} supports auto-loading code written
+in various extension languages. @xref{Auto-loading extensions}.
+
Note that loading of these associated files (including the local @file{.gdbinit}
file) requires accordingly configured @code{auto-load safe-path}
(@pxref{Auto-loading safe path}).
@end smallexample
@end table
-These are various kinds of files @value{GDBN} can automatically load:
-
-@itemize @bullet
-@item
-@xref{objfile-gdb.py file}, controlled by @ref{set auto-load python-scripts}.
-@item
-@xref{objfile-gdb.gdb file}, controlled by @ref{set auto-load gdb-scripts}.
-@item
-@xref{dotdebug_gdb_scripts section},
-controlled by @ref{set auto-load python-scripts}.
-@item
-@xref{Init File in the Current Directory},
-controlled by @ref{set auto-load local-gdbinit}.
-@item
-@xref{libthread_db.so.1 file}, controlled by @ref{set auto-load libthread-db}.
-@end itemize
-
These are @value{GDBN} control commands for the auto-loading:
@multitable @columnfractions .5 .5
@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}.
@tab Show @value{GDBN} auto-loaded scripts location.
+@item @xref{add-auto-load-scripts-directory}.
+@tab Add directory for auto-loaded scripts location list.
@item @xref{set auto-load local-gdbinit}.
@tab Control for init file in the current directory.
@item @xref{show auto-load local-gdbinit}.
@tab Add directory trusted for automatic loading.
@end multitable
-@menu
-* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit}
-* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db}
-* objfile-gdb.gdb file:: @samp{set/show/info auto-load gdb-script}
-* Auto-loading safe path:: @samp{set/show/info auto-load safe-path}
-* Auto-loading verbose mode:: @samp{set/show debug auto-load}
-@xref{Python Auto-loading}.
-@end menu
-
@node Init File in the Current Directory
@subsection Automatically loading init file in the current directory
@cindex auto-loading init file in the current directory
for each such library print list of inferior @var{pid}s using it.
@end table
-@node objfile-gdb.gdb file
-@subsection The @file{@var{objfile}-gdb.gdb} file
-@cindex auto-loading @file{@var{objfile}-gdb.gdb}
-
-@value{GDBN} tries to load an @file{@var{objfile}-gdb.gdb} file containing
-canned sequences of commands (@pxref{Sequences}), as long as @samp{set
-auto-load gdb-scripts} is set to @samp{on}.
-
-Note that loading of this script file also requires accordingly configured
-@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-
-For more background refer to the similar Python scripts auto-loading
-description (@pxref{objfile-gdb.py file}).
-
-@table @code
-@anchor{set auto-load gdb-scripts}
-@kindex set auto-load gdb-scripts
-@item set auto-load gdb-scripts [on|off]
-Enable or disable the auto-loading of canned sequences of commands scripts.
-
-@anchor{show auto-load gdb-scripts}
-@kindex show auto-load gdb-scripts
-@item show auto-load gdb-scripts
-Show whether auto-loading of canned sequences of commands scripts is enabled or
-disabled.
-
-@anchor{info auto-load gdb-scripts}
-@kindex info auto-load gdb-scripts
-@cindex print list of auto-loaded canned sequences of commands scripts
-@item info auto-load gdb-scripts [@var{regexp}]
-Print the list of all canned sequences of commands scripts that @value{GDBN}
-auto-loaded.
-@end table
-
-If @var{regexp} is supplied only canned sequences of commands scripts with
-matching names are printed.
-
@node Auto-loading safe path
@subsection Security restriction for auto-loading
@cindex auto-loading safe-path
@anchor{add-auto-load-safe-path}
@kindex add-auto-load-safe-path
@item add-auto-load-safe-path
-Add an entry (or list of entries) the list of directories trusted for automatic
-loading and execution of scripts. Multiple entries may be delimited by the
-host platform path separator in use.
+Add an entry (or list of entries) to the list of directories trusted for
+automatic loading and execution of scripts. Multiple entries may be delimited
+by the host platform path separator in use.
@end table
This variable defaults to what @code{--with-auto-load-dir} has been configured
Turns on or off display of @value{GDBN} target debugging info. This info
includes what is going on at the target level of GDB, as it happens. The
default is 0. Set it to 1 to track events, and to 2 to also track the
-value of large memory transfers. Changes to this flag do not take effect
-until the next time you connect to a target or use the @code{run} command.
+value of large memory transfers.
@item show debug target
Displays the current state of displaying @value{GDBN} target debugging
info.
@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
@chapter Extending @value{GDBN}
@cindex extending GDB
-@value{GDBN} provides three mechanisms for extension. The first is based
-on composition of @value{GDBN} commands, the second is based on the
-Python scripting language, and the third is for defining new aliases of
-existing commands.
+@value{GDBN} provides several mechanisms for extension.
+@value{GDBN} also provides the ability to automatically load
+extensions when it reads a file for debugging. This allows the
+user to automatically customize @value{GDBN} for the program
+being debugged.
+
+@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
-To facilitate the use of the first two extensions, @value{GDBN} is capable
+To facilitate the use of extension languages, @value{GDBN} is capable
of evaluating the contents of a file. When doing so, @value{GDBN}
-can recognize which scripting language is being used by looking at
+can recognize which extension language is being used by looking at
the filename extension. Files with an unrecognized filename extension
are always treated as a @value{GDBN} Command Files.
@xref{Command Files,, Command files}.
@end table
-@menu
-* Sequences:: Canned Sequences of Commands
-* Python:: Scripting @value{GDBN} using Python
-* Aliases:: Creating new spellings of existing commands
-@end menu
-
@node Sequences
@section Canned Sequences of Commands
* Hooks:: Hooks for user-defined commands
* Command Files:: How to write scripts of commands to be stored in a file
* Output:: Commands for controlled output
+* Auto-loading sequences:: Controlling auto-loaded command files
@end menu
@node Define
@item define @var{commandname}
Define a command named @var{commandname}. If there is already a command
by that name, you are asked to confirm that you want to redefine it.
-@var{commandname} may be a bare command name consisting of letters,
+The argument @var{commandname} may be a bare command name consisting of letters,
numbers, dashes, and underscores. It may also start with any predefined
prefix command. For example, @samp{define target my-target} creates
a user-defined @samp{target my-target} command.
@end table
-@node Python
-@section Scripting @value{GDBN} using Python
-@cindex python scripting
-@cindex scripting with python
-
-You can script @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.
+@node Auto-loading sequences
+@subsection Controlling auto-loading native @value{GDBN} scripts
+@cindex native script auto-loading
-@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
+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 the command file @file{@var{objfile}-gdb.gdb}.
+@xref{Auto-loading extensions}.
-@value{GDBN} provides two commands for accessing the Python interpreter,
-and one related setting:
+Auto-loading can be enabled or disabled,
+and the list of auto-loaded scripts can be printed.
@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:
+@anchor{set auto-load gdb-scripts}
+@kindex set auto-load gdb-scripts
+@item set auto-load gdb-scripts [on|off]
+Enable or disable the auto-loading of canned sequences of commands scripts.
-@smallexample
-(@value{GDBP}) python
-Type python script
-End with a line saying just "end".
->print 23
->end
-23
-@end smallexample
+@anchor{show auto-load gdb-scripts}
+@kindex show auto-load gdb-scripts
+@item show auto-load gdb-scripts
+Show whether auto-loading of canned sequences of commands scripts is enabled or
+disabled.
-@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.
+@anchor{info auto-load gdb-scripts}
+@kindex info auto-load gdb-scripts
+@cindex print list of auto-loaded canned sequences of commands scripts
+@item info auto-load gdb-scripts [@var{regexp}]
+Print the list of all canned sequences of commands scripts that @value{GDBN}
+auto-loaded.
@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}.
+If @var{regexp} is supplied only canned sequences of commands scripts with
+matching names are printed.
-@item python execfile ("script-name")
-This method is based on the @code{execfile} Python built-in function,
-and thus is always available.
-@end table
+@c Python docs live in a separate file.
+@include python.texi
-@node Python API
-@subsection Python API
-@cindex python api
-@cindex programming in python
+@c Guile docs live in a separate file.
+@include guile.texi
-You can get quick online help for @value{GDBN}'s Python API by issuing
-the command @w{@kbd{python help (gdb)}}.
+@node Auto-loading extensions
+@section Auto-loading extensions
+@cindex auto-loading extensions
-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)}}.
+@value{GDBN} provides two mechanisms for automatically loading extensions
+when a new object file is read (for example, due to the @code{file}
+command, or because the inferior has loaded a shared library):
+@file{@var{objfile}-gdb.@var{ext}} and the @code{.debug_gdb_scripts}
+section of modern file formats like ELF.
@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.
+* objfile-gdb.ext file: objfile-gdbdotext file. The @file{@var{objfile}-gdb.@var{ext}} file
+* .debug_gdb_scripts section: dotdebug_gdb_scripts section. The @code{.debug_gdb_scripts} section
+* Which flavor to choose?::
@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}.
-
-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} (@pxref{objfile-gdb.py file})
-and @code{.debug_gdb_scripts} section
-(@pxref{dotdebug_gdb_scripts section}).
-
The auto-loading feature is useful for supplying application-specific
-debugging commands and scripts.
+debugging commands and features.
Auto-loading can be enabled or disabled,
and the list of auto-loaded scripts can be printed.
+See the @samp{auto-loading} section of each extension language
+for more information.
+For @value{GDBN} command files see @ref{Auto-loading sequences}.
+For Python files see @ref{Python Auto-loading}.
-@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.
+Note that loading of this script file also requires accordingly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-If @var{regexp} is supplied only Python scripts with matching names are printed.
+@node objfile-gdbdotext file
+@subsection The @file{@var{objfile}-gdb.@var{ext}} file
+@cindex @file{@var{objfile}-gdb.gdb}
+@cindex @file{@var{objfile}-gdb.py}
+@cindex @file{@var{objfile}-gdb.scm}
-Example:
+When a new object file is read, @value{GDBN} looks for a file named
+@file{@var{objfile}-gdb.@var{ext}} (we call it @var{script-name} below),
+where @var{objfile} is the object file's name and
+where @var{ext} is the file extension for the extension language:
-@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
+@table @code
+@item @file{@var{objfile}-gdb.gdb}
+GDB's own command language
+@item @file{@var{objfile}-gdb.py}
+Python
+@item @file{@var{objfile}-gdb.scm}
+Guile
@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.
-
-@menu
-* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
-* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
-* Which flavor to choose?::
-@end menu
-
-@node objfile-gdb.py file
-@subsubsection The @file{@var{objfile}-gdb.py} file
-@cindex @file{@var{objfile}-gdb.py}
-
-When a new object file is read, @value{GDBN} looks for
-a file named @file{@var{objfile}-gdb.py} (we call it @var{script-name} below),
-where @var{objfile} is the object file's real name, formed by ensuring
-that the file name is absolute, following all symlinks, and resolving
-@code{.} and @code{..} components. If this file exists and is
-readable, @value{GDBN} will evaluate it as a Python script.
+@var{script-name} is formed by ensuring that the file name of @var{objfile}
+is absolute, following all symlinks, and resolving @code{.} and @code{..}
+components, and appending the @file{-gdb.@var{ext}} suffix.
+If this file exists and is readable, @value{GDBN} will evaluate it as a
+script in the specified extension language.
If this file does not exist, then @value{GDBN} will look for
@var{script-name} file in all of the directories as specified below.
-Note that loading of this script file also requires accordingly configured
+Note that loading of these files requires an accordingly configured
@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
For object files using @file{.exe} suffix @value{GDBN} tries to load first the
@kindex show auto-load scripts-directory
@item show auto-load scripts-directory
Show @value{GDBN} auto-loaded scripts location.
+
+@anchor{add-auto-load-scripts-directory}
+@kindex add-auto-load-scripts-directory
+@item add-auto-load-scripts-directory @r{[}@var{directories}@dots{}@r{]}
+Add an entry (or list of entries) to the list of auto-loaded scripts locations.
+Multiple entries may be delimited by the host platform path separator in use.
@end table
@value{GDBN} does not track which files it has already auto-loaded this way.
@value{GDBN} will load the associated script every time the corresponding
@var{objfile} is opened.
-So your @file{-gdb.py} file should be careful to avoid errors if it
+So your @file{-gdb.@var{ext}} file should be careful to avoid errors if it
is evaluated more than once.
@node dotdebug_gdb_scripts section
-@subsubsection The @code{.debug_gdb_scripts} section
+@subsection The @code{.debug_gdb_scripts} section
@cindex @code{.debug_gdb_scripts} section
For systems using file formats like ELF and COFF,
when @value{GDBN} loads a new object file
-it will look for a special section named @samp{.debug_gdb_scripts}.
-If this section exists, its contents is a list of names of scripts to load.
+it will look for a special section named @code{.debug_gdb_scripts}.
+If this section exists, its contents is a list of NUL-terminated names
+of scripts to load. Each entry begins with a non-NULL prefix byte that
+specifies the kind of entry, typically the extension language.
@value{GDBN} will look for each specified script file first in the
current directory and then along the source search path
directory is not relevant to scripts.
Entries can be placed in section @code{.debug_gdb_scripts} with,
-for example, this GCC macro:
+for example, this GCC macro for Python scripts.
@example
/* Note: The "MS" section flags are to remove duplicates. */
-#define DEFINE_GDB_SCRIPT(script_name) \
+#define DEFINE_GDB_PY_SCRIPT(script_name) \
asm("\
.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
-.byte 1\n\
+.byte 1 /* Python */\n\
.asciz \"" script_name "\"\n\
.popsection \n\
");
@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
-DEFINE_GDB_SCRIPT ("my-app-scripts.py")
+DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py")
@end example
The script name may include directories if desired.
Note that loading of this script file also requires accordingly configured
@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-If the macro is put in a header, any application or library
-using this header will get a reference to the specified script.
+If the macro invocation is put in a header, any application or library
+using this header will get a reference to the specified script,
+and with the use of @code{"MS"} attributes on the section, the linker
+will remove duplicates.
@node Which flavor to choose?
-@subsubsection Which flavor to choose?
+@subsection Which flavor to choose?
-Given the multiple ways of auto-loading Python scripts, it might not always
+Given the multiple ways of auto-loading extensions, it might not always
be clear which one to choose. This section provides some guidance.
-Benefits of the @file{-gdb.py} way:
+@noindent
+Benefits of the @file{-gdb.@var{ext}} way:
@itemize @bullet
@item
Doesn't require source code additions.
@end itemize
+@noindent
Benefits of the @code{.debug_gdb_scripts} way:
@itemize @bullet
@item
Works with static linking.
-Scripts for libraries done the @file{-gdb.py} way require an objfile to
+Scripts for libraries done the @file{-gdb.@var{ext}} way require an objfile to
trigger their loading. When an application is statically linked the only
objfile available is the executable, and it is cumbersome to attach all the
-scripts from all the input libraries to the executable's @file{-gdb.py} script.
+scripts from all the input libraries to the executable's
+@file{-gdb.@var{ext}} script.
@item
Works with classes that are entirely inlined.
Some classes can be entirely inlined, and thus there may not be an associated
-shared library to attach a @file{-gdb.py} script to.
+shared library to attach a @file{-gdb.@var{ext}} script to.
@item
Scripts needn't be copied out of the source tree.
In some circumstances, apps can be built out of large collections of internal
libraries, and the build infrastructure necessary to install the
-@file{-gdb.py} scripts in a place where @value{GDBN} can find them is
+@file{-gdb.@var{ext}} scripts in a place where @value{GDBN} can find them is
cumbersome. It may be easier to specify the scripts in the
@code{.debug_gdb_scripts} section as relative paths, and add a path to the
top of the source tree to the source search path.
@end itemize
-@node Python modules
-@subsection Python modules
-@cindex python modules
+@node Multiple Extension Languages
+@section Multiple Extension Languages
-@value{GDBN} comes with several modules to assist writing Python code.
+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.
-@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}.
+@subsection Python comes first
-@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
+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
even while the target is running. This is called @dfn{asynchronous
command execution} (@pxref{Background Execution}). The frontend may
specify a preferrence for asynchronous execution using the
-@code{-gdb-set target-async 1} command, which should be emitted before
+@code{-gdb-set mi-async 1} command, which should be emitted before
either running the executable or attaching to the target. After the
frontend has started the executable or attached to the target, it can
find if asynchronous execution is enabled using the
@code{-list-target-features} command.
+@table @code
+@item -gdb-set mi-async on
+@item -gdb-set mi-async off
+Set whether MI is in asynchronous mode.
+
+When @code{off}, which is the default, MI execution commands (e.g.,
+@code{-exec-continue}) are foreground commands, and @value{GDBN} waits
+for the program to stop before processing further commands.
+
+When @code{on}, MI execution commands are background execution
+commands (e.g., @code{-exec-continue} becomes the equivalent of the
+@code{c&} CLI command), and so @value{GDBN} is capable of processing
+MI commands even while the target is running.
+
+@item -gdb-show mi-async
+Show whether MI asynchronous mode is enabled.
+@end table
+
+Note: In @value{GDBN} version 7.7 and earlier, this option was called
+@code{target-async} instead of @code{mi-async}, and it had the effect
+of both putting MI in asynchronous mode and making CLI background
+commands possible. CLI background commands are now always possible
+``out of the box'' if the target supports them. The old spelling is
+kept as a deprecated alias for backwards compatibility.
+
Even if @value{GDBN} can accept a command while target is running,
many commands that access the target do not work when the target is
running. Therefore, asynchronous command execution is most useful
@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}
A thread group is no longer associated with a running program,
either because the program has exited, or because it was detached
from. The @var{id} field contains the @value{GDBN} identifier of the
-thread group. @var{code} is the exit code of the inferior; it exists
+thread group. The @var{code} field is the exit code of the inferior; it exists
only when the inferior exited with some code.
@item =thread-created,id="@var{id}",group-id="@var{gid}"
[ @code{--skip-unavailable} ] @var{fmt} [ ( @var{regno} )*]
@end smallexample
-Display the registers' contents. @var{fmt} is the format according to
-which the registers' contents are to be returned, followed by an optional
-list of numbers specifying the registers to display. A missing list of
-numbers indicates that the contents of all the registers must be
-returned. The @code{--skip-unavailable} option indicates that only
-the available registers are to be returned.
+Display the registers' contents. The format according to which the
+registers' contents are to be returned is given by @var{fmt}, followed
+by an optional list of numbers specifying the registers to display. A
+missing list of numbers indicates that the contents of all the
+registers must be returned. The @code{--skip-unavailable} option
+indicates that only the available registers are to be returned.
Allowed formats for @var{fmt} are:
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
The target-specific process identifier. This field is only present
for thread groups of type @samp{process} and only if the process exists.
+@item exit-code
+The exit code of this group's last exited thread, formatted in octal.
+This field is only present for thread groups of type @samp{process} and
+only if the process is not running.
+
@item num_children
The number of children this thread group has. This field may be
absent for an available thread group.
@noindent
where @var{name} is the name of the signal, such as @code{SIGILL} or
@code{SIGSEGV}, and @var{string} is the explanation of the signal, such
-as @code{Illegal Instruction} or @code{Segmentation fault}.
+as @code{Illegal Instruction} or @code{Segmentation fault}. The arguments
@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
user's benefit and have no particular format.
@var{middle} is @samp{middle} if @var{addr} is in the middle of the
line, or @samp{beg} if @var{addr} is at the beginning of the line, and
@var{addr} is the address in the target program associated with the
-source which is being displayed. @var{addr} is in the form @samp{0x}
+source which is being displayed. The @var{addr} is in the form @samp{0x}
followed by one or more lowercase hex digits (note that this does not
depend on the language).
@table @code
@item jit-reader-load @var{reader}
-Load the JIT reader named @var{reader}. @var{reader} is a shared
+Load the JIT reader named @var{reader}, which is a shared
object specified as either an absolute or a relative file name. In
the latter case, @value{GDBN} will try to load the reader from a
pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX
@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head}
Installs a new fast tracepoint described by @var{tracepoint_object}
-(@pxref{tracepoint object}). @var{gdb_jump_pad_head}, 8-byte long, is the
+(@pxref{tracepoint object}). The @var{gdb_jump_pad_head}, 8-byte long, is the
head of @dfn{jumppad}, which is used to jump to data collection routine
in IPA finally.
@table @samp
@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump}
@var{target_address} is address of tracepoint in the inferior.
-@var{gdb_jump_pad_head} is updated head of jumppad. Both of
+The @var{gdb_jump_pad_head} is updated head of jumppad. Both of
@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long.
-@var{fjump} contains a sequence of instructions jump to jumppad entry.
-@var{fjump_size}, 4-byte long, is the size of @var{fjump}.
+The @var{fjump} contains a sequence of instructions jump to jumppad entry.
+The @var{fjump_size}, 4-byte long, is the size of @var{fjump}.
@item E @var{NN}
for an error
If @var{regexp} is specified, only expand symbol tables for file
names matching @var{regexp}.
+@kindex maint set catch-demangler-crashes
+@kindex maint show catch-demangler-crashes
+@cindex demangler crashes
+@item maint set catch-demangler-crashes [on|off]
+@itemx maint show catch-demangler-crashes
+Control whether @value{GDBN} should attempt to catch crashes in the
+symbol name demangler. The default is to attempt to catch crashes.
+If enabled, the first time a crash is caught, a core file is created,
+the offending symbol is displayed and the user is presented with the
+option to terminate the current session.
+
@kindex maint cplus first_component
@item maint cplus first_component @var{name}
Print the first C@t{++} class/namespace component of @var{name}.
@kindex maint internal-error
@kindex maint internal-warning
+@kindex maint demangler-warning
+@cindex demangler crashes
@item maint internal-error @r{[}@var{message-text}@r{]}
@itemx maint internal-warning @r{[}@var{message-text}@r{]}
-Cause @value{GDBN} to call the internal function @code{internal_error}
-or @code{internal_warning} and hence behave as though an internal error
-or internal warning has been detected. In addition to reporting the
-internal problem, these functions give the user the opportunity to
-either quit @value{GDBN} or create a core file of the current
+@itemx maint demangler-warning @r{[}@var{message-text}@r{]}
+
+Cause @value{GDBN} to call the internal function @code{internal_error},
+@code{internal_warning} or @code{demangler_warning} and hence behave
+as though an internal problam has been detected. In addition to
+reporting the internal problem, these functions give the user the
+opportunity to either quit @value{GDBN} or (for @code{internal_error}
+and @code{internal_warning}) create a core file of the current
@value{GDBN} session.
These commands take an optional parameter @var{message-text} that is
@cindex @value{GDBN} internal error
@cindex internal errors, control of @value{GDBN} behavior
+@cindex demangler crashes
@kindex maint set internal-error
@kindex maint show internal-error
@kindex maint set internal-warning
@kindex maint show internal-warning
+@kindex maint set demangler-warning
+@kindex maint show demangler-warning
@item maint set internal-error @var{action} [ask|yes|no]
@itemx maint show internal-error @var{action}
@itemx maint set internal-warning @var{action} [ask|yes|no]
@itemx maint show internal-warning @var{action}
+@itemx maint set demangler-warning @var{action} [ask|yes|no]
+@itemx maint show demangler-warning @var{action}
When @value{GDBN} reports an internal problem (error or warning) it
gives the user the opportunity to both quit @value{GDBN} and create a
core file of the current @value{GDBN} session. These commands let you
@item corefile
You can specify that @value{GDBN} should always (yes) or never (no)
-create a core file. The default is to ask the user what to do.
+create a core file. The default is to ask the user what to do. Note
+that there is no @code{corefile} option for @code{demangler-warning}:
+demangler warnings always create a core file and this cannot be
+disabled.
@end table
@kindex maint packet
The program being debugged stopped while in a function called from GDB.
@dots{}
(@value{GDBP}) @kbd{maint print dummy-frames}
-0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
- top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@}
- call_lo=0x01014000 call_hi=0x01014001
+0xa8206d8: id=@{stack=0xbfffe734,code=0xbfffe73f,!special@}, ptid=process 9353
(@value{GDBP})
@end smallexample
at thread local base, when using the @samp{info w32 thread-information-block}
command.
+@kindex maint set target-async
+@kindex maint show target-async
+@item maint set target-async
+@itemx maint show target-async
+This controls whether @value{GDBN} targets operate in synchronous or
+asynchronous mode (@pxref{Background Execution}). Normally the
+default is asynchronous, if it is available; but this can be changed
+to more easily debug problems occurring only in synchronous mode.
+
@kindex maint set per-command
@kindex maint show per-command
@item maint set per-command
@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}.
@item c @r{[}@var{addr}@r{]}
@cindex @samp{c} packet
-Continue. @var{addr} is address to resume. If @var{addr} is omitted,
-resume at current address.
+Continue at @var{addr}, which is the address to resume. If @var{addr}
+is omitted, resume at current address.
This packet is deprecated for multi-threading support. @xref{vCont
packet}.
@item H @var{op} @var{thread-id}
@cindex @samp{H} packet
Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
-@samp{G}, et.al.). @var{op} depends on the operation to be performed:
-it should be @samp{c} for step and continue operations (note that this
+@samp{G}, et.al.). Depending on the operation to be performed, @var{op}
+should be @samp{c} for step and continue operations (note that this
is deprecated, supporting the @samp{vCont} command is a better
-option), @samp{g} for other operations. The thread designator
+option), and @samp{g} for other operations. The thread designator
@var{thread-id} has the format and interpretation described in
@ref{thread-id syntax}.
@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 M @var{addr},@var{length}:@var{XX@dots{}}
@cindex @samp{M} packet
Write @var{length} bytes of memory starting at address @var{addr}.
-@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
+The data is given by @var{XX@dots{}}; each byte is transmitted as a two-digit
hexadecimal number.
Reply:
@item R @var{XX}
@cindex @samp{R} packet
-Restart the program being debugged. @var{XX}, while needed, is ignored.
+Restart the program being debugged. The @var{XX}, while needed, is ignored.
This packet is only available in extended mode (@pxref{extended mode}).
The @samp{R} packet has no reply.
@item s @r{[}@var{addr}@r{]}
@cindex @samp{s} packet
-Single step. @var{addr} is the address at which to resume. If
+Single step, resuming at @var{addr}. If
@var{addr} is omitted, resume at same address.
This packet is deprecated for multi-threading support. @xref{vCont
@item t @var{addr}:@var{PP},@var{MM}
@cindex @samp{t} packet
Search backwards starting at address @var{addr} for a match with pattern
-@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
-@var{addr} must be at least 3 digits.
+@var{PP} and mask @var{MM}, both of which are are 4 byte long.
+There must be at least 3 digits in @var{addr}.
@item T @var{thread-id}
@cindex @samp{T} packet
@item vKill;@var{pid}
@cindex @samp{vKill} packet
-Kill the process with the specified process ID. @var{pid} is a
+@anchor{vKill packet}
+Kill the process with the specified process ID @var{pid}, which is a
hexadecimal integer identifying the process. This packet is used in
preference to @samp{k} when multiprocess protocol extensions are
supported; see @ref{multiprocess extensions}.
@anchor{X packet}
@cindex @samp{X} packet
Write data to memory, where the data is transmitted in binary.
-@var{addr} is address, @var{length} is number of bytes,
+Memory is specified by its address @var{addr} and number of bytes @var{length};
@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
Reply:
address @var{addr}.
A hardware breakpoint is implemented using a mechanism that is not
-dependant on being able to modify the target's memory. @var{kind}
+dependant on being able to modify the target's memory. The @var{kind}
and @var{cond_list} have the same meaning as in @samp{Z0} packets.
@emph{Implementation note: A hardware breakpoint is not affected by code
@cindex @samp{z2} packet
@cindex @samp{Z2} packet
Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}.
-@var{kind} is interpreted as the number of bytes to watch.
+The number of bytes to watch is specified by @var{kind}.
Reply:
@table @samp
@cindex @samp{z3} packet
@cindex @samp{Z3} packet
Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}.
-@var{kind} is interpreted as the number of bytes to watch.
+The number of bytes to watch is specified by @var{kind}.
Reply:
@table @samp
@cindex @samp{z4} packet
@cindex @samp{Z4} packet
Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}.
-@var{kind} is interpreted as the number of bytes to watch.
+The number of bytes to watch is specified by @var{kind}.
Reply:
@table @samp
@itemize @bullet
@item
If @var{n} is a hexadecimal number, it is a register number, and the
-corresponding @var{r} gives that register's value. @var{r} is a
+corresponding @var{r} gives that register's value. The data @var{r} is a
series of bytes in target byte order, with each byte given by a
two-digit hex number.
@item
If @var{n} is a recognized @dfn{stop reason}, it describes a more
specific event that stopped the target. The currently defined stop
-reasons are listed below. @var{aa} should be @samp{05}, the trap
+reasons are listed below. The @var{aa} should be @samp{05}, the trap
signal. At most one stop reason should be present.
@item
@item library
The packet indicates that the loaded libraries have changed.
@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new
-list of loaded libraries. @var{r} is ignored.
+list of loaded libraries. The @var{r} part is ignored.
@cindex replay log events, remote reply
@item replaylog
@item qCRC:@var{addr},@var{length}
@cindex CRC of memory block, remote request
@cindex @samp{qCRC} packet
+@anchor{qCRC packet}
Compute the CRC checksum of a block of memory using CRC-32 defined in
IEEE 802.3. The CRC is computed byte at a time, taking the most
significant bit of each byte first. The initial pattern code
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QDisableRandomization} is not supported
Refer to @ref{thread-id syntax}, for the format of the @var{thread-id}
fields.
+@emph{Note: @value{GDBN} will send the @code{qfThreadInfo} query during the
+initial connection with the remote target, and the very first thread ID
+mentioned in the reply will be stopped by @value{GDBN} in a subsequent
+message. Therefore, the stub should ensure that the first thread ID in
+the @code{qfThreadInfo} reply is suitable for being stopped by @value{GDBN}.}
+
@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm}
@cindex get thread-local storage address, remote request
@cindex @samp{qGetTLSAddr} packet
local storage requested.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
returned; @var{done} (one hex digit) is zero to indicate more threads
and one indicates no further threads; @var{argthreadid} (eight hex
digits) is @var{nextthread} from the request packet; @var{thread}@dots{}
-is a sequence of thread IDs from the target. @var{threadid} (eight hex
-digits). See @code{remote.c:parse_threadlist_response()}.
+is a sequence of thread IDs, @var{threadid} (eight hex
+digits), from the target. See @code{remote.c:parse_threadlist_response()}.
@end table
@item qOffsets
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QNonStop} is not supported by
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QPassSignals} is not supported by
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QProgramSignals} is not supported
@cindex @samp{qSearch memory} packet
@anchor{qSearch memory}
Search @var{length} bytes at @var{address} for @var{search-pattern}.
-@var{address} and @var{length} are encoded in hex.
-@var{search-pattern} is a sequence of bytes, hex encoded.
+Both @var{address} and @var{length} are encoded in hex;
+@var{search-pattern} is a sequence of bytes, also hex encoded.
Reply:
@table @samp
@item qThreadExtraInfo,@var{thread-id}
@cindex thread attributes info, remote request
@cindex @samp{qThreadExtraInfo} packet
-Obtain a printable string description of a thread's attributes from
-the target OS. @var{thread-id} is a thread ID;
-see @ref{thread-id syntax}. This
+Obtain from the target OS a printable string description of thread
+attributes for the thread @var{thread-id}; see @ref{thread-id syntax},
+for the forms of @var{thread-id}. This
string may contain anything that the target OS thinks is interesting
for @value{GDBN} to tell the user about the thread. The string is
displayed in @value{GDBN}'s @code{info threads} display. Some
@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
@item qXfer:osdata:read::@var{offset},@var{length}
@anchor{qXfer osdata read}
-Access the target's @dfn{operating system information}.
+Access the target's @dfn{operating system information}.
@xref{Operating System Information}.
@end table
target. There may be more data at a higher address (although
it is permitted to return @samp{m} even for the last valid
block of data, as long as at least one byte of data was read).
-@var{data} may have fewer bytes than the @var{length} in the
+It is possible for @var{data} to have fewer bytes than the @var{length} in the
request.
@item l @var{data}
Data @var{data} (@pxref{Binary Data}) has been read from the target.
-There is no more data to be read. @var{data} may have fewer bytes
-than the @var{length} in the request.
+There is no more data to be read. It is possible for @var{data} to
+have fewer bytes than the @var{length} in the request.
@item l
The @var{offset} in the request is at the end of the data.
@item E @var{nn}
The offset was invalid, or there was an error encountered reading the data.
-@var{nn} is a hex-encoded @code{errno} value.
+The @var{nn} part is a hex-encoded @code{errno} value.
@item @w{}
An empty reply indicates the @var{object} string was not recognized by
@anchor{qXfer write}
Write uninterpreted bytes into the target's special data area
identified by the keyword @var{object}, starting at @var{offset} bytes
-into the data. @var{data}@dots{} is the binary-encoded data
-(@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
+into the data. The binary-encoded data (@pxref{Binary Data}) to be
+written is given by @var{data}@dots{}. The content and encoding of @var{annex}
is specific to @var{object}; it can supply additional details about what data
to access.
@item E @var{nn}
The offset was invalid, or there was an error encountered writing the data.
-@var{nn} is a hex-encoded @code{errno} value.
+The @var{nn} part is a hex-encoded @code{errno} value.
@item @w{}
An empty reply indicates the @var{object} string was not
@cindex @samp{QTDP} packet
Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
-the tracepoint is disabled. @var{step} is the tracepoint's step
-count, and @var{pass} is its pass count. If an @samp{F} is present,
+the tracepoint is disabled. The @var{step} gives the tracepoint's step
+count, and @var{pass} gives its pass count. If an @samp{F} is present,
then the tracepoint is to be a fast tracepoint, and the @var{flen} is
the number of bytes that the target should copy elsewhere to make room
for the tracepoint. If an @samp{X} is present, it introduces a
@end table
@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
-Define actions to be taken when a tracepoint is hit. @var{n} and
+Define actions to be taken when a tracepoint is hit. The @var{n} and
@var{addr} must be the same as in the initial @samp{QTDP} packet for
this tracepoint. This packet may only be sent immediately after
another @samp{QTDP} packet that ended with a @samp{-}. If the
@table @samp
@item R @var{mask}
-Collect the registers whose bits are set in @var{mask}. @var{mask} is
+Collect the registers whose bits are set in @var{mask},
a hexadecimal number whose @var{i}'th bit is set if register number
@var{i} should be collected. (The least significant bit is numbered
zero.) Note that @var{mask} may be any number of digits long; it may
@item X @var{len},@var{expr}
Evaluate @var{expr}, whose length is @var{len}, and collect memory as
-it directs. @var{expr} is an agent expression, as described in
+it directs. The agent expression @var{expr} is as described in
@ref{Agent Expressions}. Each byte of the expression is encoded as a
two-digit hex number in the packet; @var{len} is the number of bytes
in the expression (and thus one-half the number of hex digits in the
@cindex @samp{QTDPsrc} packet
Specify a source string of tracepoint @var{n} at address @var{addr}.
This is useful to get accurate reproduction of the tracepoints
-originally downloaded at the beginning of the trace run. @var{type}
+originally downloaded at the beginning of the trace run. The @var{type}
is the name of the tracepoint part, such as @samp{cond} for the
tracepoint's conditional expression (see below for a list of types), while
@var{bytes} is the string, encoded in hexadecimal.
@item 0
The minimum instruction length is currently unknown.
@item @var{length}
-The minimum instruction length is @var{length}, where @var{length} is greater
-or equal to 1. @var{length} is a hexadecimal number. A reply of 1 means
-that a fast tracepoint may be placed on any instruction regardless of size.
+The minimum instruction length is @var{length}, where @var{length}
+is a hexadecimal number greater or equal to 1. A reply
+of 1 means that a fast tracepoint may be placed on any instruction
+regardless of size.
@item E
An error has occurred.
@item @w{}
@item terror:@var{text}:@var{tpnum}
The trace stopped because tracepoint @var{tpnum} had an error. The
string @var{text} is available to describe the nature of the error
-(for instance, a divide by zero in the condition expression).
-@var{text} is hex encoded.
+(for instance, a divide by zero in the condition expression); it
+is hex encoded.
@item tunknown:0
The trace stopped for some other reason.
@item l
(lower case letter @samp{L}) denotes end of list.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that the request is not supported by the
stub.
@end table
-@var{address} is encoded in hex.
+The @var{address} is encoded in hex;
@var{id} and @var{extra} are strings encoded in hex.
In response to each query, the target will reply with a list of one or
@item QTSave:@var{filename}
@cindex @samp{QTSave} packet
This packet directs the target to save trace data to the file name
-@var{filename} in the target's filesystem. @var{filename} is encoded
+@var{filename} in the target's filesystem. The @var{filename} is encoded
as a hex string; the interpretation of the file name (relative vs
absolute, wild cards, etc) is up to the target.
Replies:
@table @samp
@item qRelocInsn:@var{adjusted_size}
-Informs the stub the relocation is complete. @var{adjusted_size} is
+Informs the stub the relocation is complete. The @var{adjusted_size} is
the length in bytes of resulting relocated instruction sequence.
@item E @var{NN}
A badly formed request was detected, or an error was encountered while
@item F @var{result} [, @var{errno}] [; @var{attachment}]
@var{result} is the integer value returned by this operation, usually
non-negative for success and -1 for errors. If an error has occured,
-@var{errno} will be included in the result. @var{errno} will have a
+@var{errno} will be included in the result specifying a
value defined by the File-I/O protocol (@pxref{Errno Values}). For
operations which return data, @var{attachment} supplies the data as a
binary buffer. Binary buffers in response packets are escaped in the
These are the supported Host I/O operations:
@table @samp
-@item vFile:open: @var{pathname}, @var{flags}, @var{mode}
-Open a file at @var{pathname} and return a file descriptor for it, or
-return -1 if an error occurs. @var{pathname} is a string,
+@item vFile:open: @var{filename}, @var{flags}, @var{mode}
+Open a file at @var{filename} and return a file descriptor for it, or
+return -1 if an error occurs. The @var{filename} is a string,
@var{flags} is an integer indicating a mask of open flags
(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask
of mode bits to use if the file is created (@pxref{mode_t Values}).
which may be shorter than the length of @var{data}, or -1 if an
error occurred.
-@item vFile:unlink: @var{pathname}
-Delete the file at @var{pathname} on the target. Return 0,
-or -1 if an error occurs. @var{pathname} is a string.
+@item vFile:unlink: @var{filename}
+Delete the file at @var{filename} on the target. Return 0,
+or -1 if an error occurs. The @var{filename} is a string.
@item vFile:readlink: @var{filename}
Read value of symbolic link @var{filename} on the target. Return
@item @var{name}:@var{event}
The notification packet is sent by the side that initiates the
exchange (currently, only the stub does that), with @var{event}
-carrying the specific information about the notification.
-@var{name} is the name of the notification.
+carrying the specific information about the notification, and
+@var{name} specifying the name of the notification.
@item @var{ack}
The acknowledge sent by the other side, usually @value{GDBN}, to
acknowledge the exchange and request the event.
ABI.
@item type
-The type of the register. @var{type} may be a predefined type, a type
+The type of the register. It may be a predefined type, a type
defined in the current feature, or one of the special types @code{int}
and @code{float}. @code{int} is an integer type of the correct size
for @var{bitsize}, and @code{float} is a floating point type (in the
@var{bitsize}. The default is @code{int}.
@item group
-The register group to which this register belongs. @var{group} must
+The register group to which this register belongs. It must
be either @code{general}, @code{float}, or @code{vector}. If no
@var{group} is specified, @value{GDBN} will not display the register
in @code{info registers}.
* AArch64 Features::
* ARM Features::
* i386 Features::
+* MicroBlaze Features::
* MIPS Features::
* M68K Features::
* Nios II Features::
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 MicroBlaze Features
+@subsection MicroBlaze Features
+@cindex target descriptions, MicroBlaze features
+
+The @samp{org.gnu.gdb.microblaze.core} feature is required for MicroBlaze
+targets. It should contain registers @samp{r0} through @samp{r31},
+@samp{rpc}, @samp{rmsr}, @samp{rear}, @samp{resr}, @samp{rfsr}, @samp{rbtr},
+@samp{rpvr}, @samp{rpvr1} through @samp{rpvr11}, @samp{redr}, @samp{rpid},
+@samp{rzpr}, @samp{rtlbx}, @samp{rtlbsx}, @samp{rtlblo}, and @samp{rtlbhi}.
+
+The @samp{org.gnu.gdb.microblaze.stack-protect} feature is optional.
+If present, it should contain registers @samp{rshr} and @samp{rslr}
+
@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