\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
@dircategory Software development
@direntry
* Gdb: (gdb). The GNU debugger.
+* gdbserver: (gdb) Server. The GNU debugging server.
@end direntry
@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
(such as wildcard expansion or variable substitution) in describing
the arguments.
In Unix systems, you can control which shell is used with the
-@code{SHELL} environment variable.
-@xref{Arguments, ,Your Program's Arguments}.
+@code{SHELL} environment variable. If you do not define @code{SHELL},
+@value{GDBN} uses the default shell (@file{/bin/sh}). You can disable
+use of any shell with the @code{set startup-with-shell} command (see
+below for details).
@item The @emph{environment.}
Your program normally inherits its environment from @value{GDBN}, but you can
This command is available when debugging locally on most targets, excluding
@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
+@kindex set startup-with-shell
+@item set startup-with-shell
+@itemx set startup-with-shell on
+@itemx set startup-with-shell off
+@itemx show set startup-with-shell
+On Unix systems, by default, if a shell is available on your target,
+@value{GDBN}) uses it to start your program. Arguments of the
+@code{run} command are passed to the shell, which does variable
+substitution, expands wildcard characters and performs redirection of
+I/O. In some circumstances, it may be useful to disable such use of a
+shell, for example, when debugging the shell itself or diagnosing
+startup failures such as:
+
+@smallexample
+(@value{GDBP}) run
+Starting program: ./a.out
+During startup program terminated with signal SIGSEGV, Segmentation fault.
+@end smallexample
+
+@noindent
+which indicates the shell or the wrapper specified with
+@samp{exec-wrapper} crashed, not your program. Most often, this is
+caused by something odd in your shell's non-interactive mode
+initialization file---such as @file{.cshrc} for C-shell,
+$@file{.zshenv} for the Z shell, or the file specified in the
+@samp{BASH_ENV} environment variable for BASH.
+
@kindex set disable-randomization
@item set disable-randomization
@itemx set disable-randomization on
@end table
@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
-the shell indicated
-by your @code{SHELL} environment variable if it exists (or
-@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
-that runs an initialization file---such as @file{.cshrc} for C-shell, or
-@file{.bashrc} for BASH---any variables you set in that file affect
-your program. You may wish to move setting of environment variables to
-files that are only run when you sign on, such as @file{.login} or
-@file{.profile}.
+the shell indicated by your @code{SHELL} environment variable if it
+exists (or @code{/bin/sh} if not). If your @code{SHELL} variable
+names a shell that runs an initialization file when started
+non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv}
+for the Z shell, or the file specified in the @samp{BASH_ENV}
+environment variable for BASH---any variables you set in that file
+affect your program. You may wish to move setting of environment
+variables to files that are only run when you sign on, such as
+@file{.login} or @file{.profile}.
@node Working Directory
@section Your Program's Working Directory
@kindex catch
@item catch @var{event}
Stop when @var{event} occurs. @var{event} can be any of the following:
+
@table @code
-@item throw
+@item throw @r{[}@var{regexp}@r{]}
+@itemx rethrow @r{[}@var{regexp}@r{]}
+@itemx catch @r{[}@var{regexp}@r{]}
+@kindex catch throw
+@kindex catch rethrow
+@kindex catch catch
@cindex stop on C@t{++} exceptions
-The throwing of a C@t{++} exception.
+The throwing, re-throwing, or catching of a C@t{++} exception.
+
+If @var{regexp} is given, then only exceptions whose type matches the
+regular expression will be caught.
+
+@vindex $_exception@r{, convenience variable}
+The convenience variable @code{$_exception} is available at an
+exception-related catchpoint, on some systems. This holds the
+exception being thrown.
+
+There are currently some limitations to C@t{++} exception handling in
+@value{GDBN}:
+
+@itemize @bullet
+@item
+The support for these commands is system-dependent. Currently, only
+systems using the @samp{gnu-v3} C@t{++} ABI (@pxref{ABI}) are
+supported.
+
+@item
+The regular expression feature and the @code{$_exception} convenience
+variable rely on the presence of some SDT probes in @code{libstdc++}.
+If these probes are not present, then these features cannot be used.
+These probes were first available in the GCC 4.8 release, but whether
+or not they are available in your GCC also depends on how it was
+built.
+
+@item
+The @code{$_exception} convenience variable is only valid at the
+instruction at which an exception-related catchpoint is set.
+
+@item
+When an exception-related catchpoint is hit, @value{GDBN} stops at a
+location in the system library which implements runtime exception
+support for C@t{++}, usually @code{libstdc++}. You can use @code{up}
+(@pxref{Selection}) to get to your code.
+
+@item
+If you call a function interactively, @value{GDBN} normally returns
+control to you when the function has finished executing. If the call
+raises an exception, however, the call may bypass the mechanism that
+returns control to you and cause your program either to abort or to
+simply continue running until it hits a breakpoint, catches a signal
+that @value{GDBN} is listening for, or exits. This is the case even if
+you set a catchpoint for the exception; catchpoints on exceptions are
+disabled within interactive calls. @xref{Calling}, for information on
+controlling this with @code{set unwind-on-terminating-exception}.
+
+@item
+You cannot raise an exception interactively.
-@item catch
-The catching of a C@t{++} exception.
+@item
+You cannot install an exception handler interactively.
+@end itemize
@item exception
+@kindex catch exception
@cindex Ada exception catching
@cindex catch Ada exceptions
An Ada exception being raised. If an exception name is specified
Pck.Constraint_Error}.
@item exception unhandled
+@kindex catch exception unhandled
An exception that was raised but is not handled by the program.
@item assert
+@kindex catch assert
A failed Ada assertion.
@item exec
+@kindex catch exec
@cindex break on fork/exec
A call to @code{exec}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
@item syscall
@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
+@kindex catch syscall
@cindex break on a system call.
A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
syscall is a mechanism for application programs to request a service
Again, in this case @value{GDBN} would not be able to display syscall's names.
@item fork
+@kindex catch fork
A call to @code{fork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
@item vfork
+@kindex catch vfork
A call to @code{vfork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
@item load @r{[}regexp@r{]}
@itemx unload @r{[}regexp@r{]}
+@kindex catch load
+@kindex catch unload
The loading or unloading of a shared library. If @var{regexp} is
given, then the catchpoint will stop only if the regular expression
matches one of the affected libraries.
@item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
+@kindex catch signal
The delivery of a signal.
With no arguments, this catchpoint will catch any signal that is not
@end table
@item tcatch @var{event}
+@kindex tcatch
Set a catchpoint that is enabled only for one stop. The catchpoint is
automatically deleted after the first time the event is caught.
Use the @code{info break} command to list the current catchpoints.
-There are currently some limitations to C@t{++} exception handling
-(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
-
-@itemize @bullet
-@item
-If you call a function interactively, @value{GDBN} normally returns
-control to you when the function has finished executing. If the call
-raises an exception, however, the call may bypass the mechanism that
-returns control to you and cause your program either to abort or to
-simply continue running until it hits a breakpoint, catches a signal
-that @value{GDBN} is listening for, or exits. This is the case even if
-you set a catchpoint for the exception; catchpoints on exceptions are
-disabled within interactive calls.
-
-@item
-You cannot raise an exception interactively.
-
-@item
-You cannot install an exception handler interactively.
-@end itemize
-
-@cindex raise exceptions
-Sometimes @code{catch} is not the best way to debug exception handling:
-if you need to know exactly where an exception is raised, it is better to
-stop @emph{before} the exception handler is called, since that way you
-can see the stack before any unwinding takes place. If you set a
-breakpoint in an exception handler instead, it may not be easy to find
-out where the exception was raised.
-
-To stop just before an exception handler is called, you need some
-knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are
-raised by calling a library function named @code{__raise_exception}
-which has the following ANSI C interface:
-
-@smallexample
- /* @var{addr} is where the exception identifier is stored.
- @var{id} is the exception identifier. */
- void __raise_exception (void **addr, void *id);
-@end smallexample
-
-@noindent
-To make the debugger catch all exceptions before any stack
-unwinding takes place, set a breakpoint on @code{__raise_exception}
-(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}).
-
-With a conditional breakpoint (@pxref{Conditions, ,Break Conditions})
-that depends on the value of @var{id}, you can stop your program when
-a specific exception is raised. You can use multiple conditional
-breakpoints to stop your program when any of a number of exceptions are
-raised.
-
@node Delete Breaks
@subsection Deleting Breakpoints
proceed until the function returns.
An argument is a repeat count, as in @code{next}.
+
+@end table
+
+@anchor{range stepping}
+@cindex range stepping
+@cindex target-assisted range stepping
+By default, and if available, @value{GDBN} makes use of
+target-assisted @dfn{range stepping}. In other words, whenever you
+use a stepping command (e.g., @code{step}, @code{next}), @value{GDBN}
+tells the target to step the corresponding range of instruction
+addresses instead of issuing multiple single-steps. This speeds up
+line stepping, particularly for remote targets. Ideally, there should
+be no reason you would want to turn range stepping off. However, it's
+possible that a bug in the debug info, a bug in the remote stub (for
+remote targets), or even a bug in @value{GDBN} could make line
+stepping behave incorrectly when target-assisted range stepping is
+enabled. You can use the following command to turn off range stepping
+if necessary:
+
+@table @code
+@kindex set range-stepping
+@kindex show range-stepping
+@item set range-stepping
+@itemx show range-stepping
+Control whether range stepping is enabled.
+
+If @code{on}, and the target supports it, @value{GDBN} tells the
+target to step a range of addresses itself, instead of issuing
+multiple single-steps. If @code{off}, @value{GDBN} always issues
+single-steps, even if range stepping is supported by the target. The
+default is @code{on}.
+
@end table
@node Skipping Over Functions and Files
@end table
+Thread-specific breakpoints are automatically deleted when
+@value{GDBN} detects the corresponding thread is no longer in the
+thread list. For example:
+
+@smallexample
+(@value{GDBP}) c
+Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list.
+@end smallexample
+
+There are several ways for a thread to disappear, such as a regular
+thread exit, but also when you detach from the process with the
+@code{detach} command (@pxref{Attach, ,Debugging an Already-running
+Process}), or if @value{GDBN} loses the remote connection
+(@pxref{Remote Debugging}), etc. Note that with some targets,
+@value{GDBN} is only able to detect a thread has exited when the user
+explictly asks for the thread list with the @code{info threads}
+command.
+
@node Interrupted System Calls
@subsection Interrupted System Calls
When the inferior process exits, or @value{GDBN} detaches from it,
process record and replay target will automatically stop itself.
+@kindex record goto
+@item record goto
+Go to a specific location in the execution log. There are several
+ways to specify the location to go to:
+
+@table @code
+@item record goto begin
+@itemx record goto start
+Go to the beginning of the execution log.
+
+@item record goto end
+Go to the end of the execution log.
+
+@item record goto @var{n}
+Go to instruction number @var{n} in the execution log.
+@end table
+
@kindex record save
@item record save @var{filename}
Save the execution log to a file @file{@var{filename}}.
@menu
* Frames:: Stack frames
* Backtrace:: Backtraces
+* Frame Filter Management:: Managing frame filters
* Selection:: Selecting a frame
* Frame Info:: Information on a frame
frame (frame zero), followed by its caller (frame one), and on up the
stack.
+@anchor{backtrace-command}
@table @code
@kindex backtrace
@kindex bt @r{(@code{backtrace})}
@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.
+
+@item backtrace no-filters
+@itemx bt no-filters
+@itemx bt no-filters @var{n}
+@itemx bt no-filters -@var{n}
+@itemx bt no-filters full
+@itemx bt no-filters full @var{n}
+@itemx bt no-filters full -@var{n}
+Do not run Python frame filters on this backtrace. @xref{Frame
+Filter API}, for more information. Additionally use @ref{disable
+frame-filter all} to turn off all frame filters. This is only
+relevant when @value{GDBN} has been configured with @code{Python}
+support.
@end table
@kindex where
Show the current way to display filenames.
@end table
+@node Frame Filter Management
+@section Management of Frame Filters.
+@cindex managing frame filters
+
+Frame filters are Python based utilities to manage and decorate the
+output of frames. @xref{Frame Filter API}, for further information.
+
+Managing frame filters is performed by several commands available
+within @value{GDBN}, detailed here.
+
+@table @code
+@kindex info frame-filter
+@item info frame-filter
+Print a list of installed frame filters from all dictionaries, showing
+their name, priority and enabled status.
+
+@kindex disable frame-filter
+@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} 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 disabled. @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} 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
+filter and is used when @code{all} is not the option for
+@var{filter-dictionary}.
+
+Example:
+
+@smallexample
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 No PrimaryFunctionFilter
+ 100 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 Yes BuildProgra Filter
+
+(gdb) disable frame-filter /build/test BuildProgramFilter
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 No PrimaryFunctionFilter
+ 100 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 No BuildProgramFilter
+
+(gdb) enable frame-filter global PrimaryFunctionFilter
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 Yes PrimaryFunctionFilter
+ 100 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 No BuildProgramFilter
+@end smallexample
+
+@kindex set frame-filter priority
+@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},
+@code{progspace} or the name of the object file where the frame filter
+dictionary resides. @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},
+@code{progspace} or the name of the object file where the frame filter
+dictionary resides.
+
+Example:
+
+@smallexample
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 Yes PrimaryFunctionFilter
+ 100 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 No BuildProgramFilter
+
+(gdb) set frame-filter priority global Reverse 50
+(gdb) info frame-filter
+
+global frame-filters:
+ Priority Enabled Name
+ 1000 Yes PrimaryFunctionFilter
+ 50 Yes Reverse
+
+progspace /build/test frame-filters:
+ Priority Enabled Name
+ 100 Yes ProgspaceFilter
+
+objfile /build/test frame-filters:
+ Priority Enabled Name
+ 999 No BuildProgramFilter
+@end smallexample
+@end table
+
@node Selection
@section Selecting a Frame
* Core File Generation:: Cause a program dump its core
* Character Sets:: Debugging programs that use a different
character set than GDB does
-* Caching Remote Data:: Data caching for remote targets
+* Caching Target Data:: Data caching for targets
* Searching Memory:: Searching memory for a sequence of bytes
@end menu
@end smallexample
@cindex C@t{++} scope resolution
-These uses of @samp{::} are very rarely in conflict with the very similar
-use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
-scope resolution operator in @value{GDBN} expressions.
-@c FIXME: Um, so what happens in one of those rare cases where it's in
-@c conflict?? --mew
+These uses of @samp{::} are very rarely in conflict with the very
+similar use of the same notation in C@t{++}. When they are in
+conflict, the C@t{++} meaning takes precedence; however, this can be
+overridden by quoting the file or function name with single quotes.
+
+For example, suppose the program is stopped in a method of a class
+that has a field named @code{includefile}, and there is also an
+include file named @file{includefile} that defines a variable,
+@code{some_global}.
+
+@smallexample
+(@value{GDBP}) p includefile
+$1 = 23
+(@value{GDBP}) p includefile::some_global
+A syntax error in expression, near `'.
+(@value{GDBP}) p 'includefile'::some_global
+$2 = 27
+@end smallexample
@cindex wrong values
@cindex variable values, wrong
strings. Single-byte members of a vector are displayed as an integer
array.
+@item z
+Like @samp{x} formatting, the value is treated as an integer and
+printed as hexadecimal, but leading zeros are printed to pad the value
+to the size of the integer type.
+
@item r
@cindex raw printing
Print using the @samp{raw} formatting. By default, @value{GDBN} will
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
+@item set print raw frame-arguments on
+Print frame arguments in raw, non pretty-printed, form.
+
+@item set print raw frame-arguments off
+Print frame arguments in pretty-printed form, if there is a pretty-printer
+for the value (@pxref{Pretty Printing}),
+otherwise print the value in raw form.
+This is the default.
+
+@item show print raw frame-arguments
+Show whether to print frame arguments in raw form.
+
@anchor{set print entry-values}
@item set print entry-values @var{value}
@kindex set print entry-values
@item $_exitcode
@vindex $_exitcode@r{, convenience variable}
-The variable @code{$_exitcode} is automatically set to the exit code when
-the program being debugged terminates.
+When the program being debugged terminates normally, @value{GDBN}
+automatically sets this variable to the exit code of the program, and
+resets @code{$_exitsignal} to @code{void}.
+
+@item $_exitsignal
+@vindex $_exitsignal@r{, convenience variable}
+When the program being debugged dies due to an uncaught signal,
+@value{GDBN} automatically sets this variable to that signal's number,
+and resets @code{$_exitcode} to @code{void}.
+
+To distinguish between whether the program being debugged has exited
+(i.e., @code{$_exitcode} is not @code{void}) or signalled (i.e.,
+@code{$_exitsignal} is not @code{void}), the convenience function
+@code{$_isvoid} can be used (@pxref{Convenience Funs,, Convenience
+Functions}). For example, considering the following source code:
+
+@smallexample
+#include <signal.h>
+
+int
+main (int argc, char *argv[])
+@{
+ raise (SIGALRM);
+ return 0;
+@}
+@end smallexample
+
+A valid way of telling whether the program being debugged has exited
+or signalled would be:
+
+@smallexample
+(@value{GDBP}) define has_exited_or_signalled
+Type commands for definition of ``has_exited_or_signalled''.
+End with a line saying just ``end''.
+>if $_isvoid ($_exitsignal)
+ >echo The program has exited\n
+ >else
+ >echo The program has signalled\n
+ >end
+>end
+(@value{GDBP}) run
+Starting program:
+
+Program terminated with signal SIGALRM, Alarm clock.
+The program no longer exists.
+(@value{GDBP}) has_exited_or_signalled
+The program has signalled
+@end smallexample
+
+As can be seen, @value{GDBN} correctly informs that the program being
+debugged has signalled, since it calls @code{raise} and raises a
+@code{SIGALRM} signal. If the program being debugged had not called
+@code{raise}, then @value{GDBN} would report a normal exit:
+
+@smallexample
+(@value{GDBP}) has_exited_or_signalled
+The program has exited
+@end smallexample
+
+@item $_exception
+The variable @code{$_exception} is set to the exception object being
+thrown at an exception-related catchpoint. @xref{Set Catchpoints}.
@item $_probe_argc
@itemx $_probe_arg0@dots{}$_probe_arg11
however, a convenience function is implemented internally to
@value{GDBN}.
+These functions do not require @value{GDBN} to be configured with
+@code{Python} support, which means that they are always available.
+
+@table @code
+
+@item $_isvoid (@var{expr})
+@findex $_isvoid@r{, convenience function}
+Return one if the expression @var{expr} is @code{void}. Otherwise it
+returns zero.
+
+A @code{void} expression is an expression where the type of the result
+is @code{void}. For example, you can examine a convenience variable
+(see @ref{Convenience Vars,, Convenience Variables}) to check whether
+it is @code{void}:
+
+@smallexample
+(@value{GDBP}) print $_exitcode
+$1 = void
+(@value{GDBP}) print $_isvoid ($_exitcode)
+$2 = 1
+(@value{GDBP}) run
+Starting program: ./a.out
+[Inferior 1 (process 29572) exited normally]
+(@value{GDBP}) print $_exitcode
+$3 = 0
+(@value{GDBP}) print $_isvoid ($_exitcode)
+$4 = 0
+@end smallexample
+
+In the example above, we used @code{$_isvoid} to check whether
+@code{$_exitcode} is @code{void} before and after the execution of the
+program being debugged. Before the execution there is no exit code to
+be examined, therefore @code{$_exitcode} is @code{void}. After the
+execution the program being debugged returned zero, therefore
+@code{$_exitcode} is zero, which means that it is not @code{void}
+anymore.
+
+The @code{void} expression can also be a call of a function from the
+program being debugged. For example, given the following function:
+
+@smallexample
+void
+foo (void)
+@{
+@}
+@end smallexample
+
+The result of calling it inside @value{GDBN} is @code{void}:
+
+@smallexample
+(@value{GDBP}) print foo ()
+$1 = void
+(@value{GDBP}) print $_isvoid (foo ())
+$2 = 1
+(@value{GDBP}) set $v = foo ()
+(@value{GDBP}) print $v
+$3 = void
+(@value{GDBP}) print $_isvoid ($v)
+$4 = 1
+@end smallexample
+
+@end table
+
These functions require @value{GDBN} to be configured with
@code{Python} support.
true contents of hardware registers, you must select the innermost
frame (with @samp{frame 0}).
-However, @value{GDBN} must deduce where registers are saved, from the machine
-code generated by your compiler. If some registers are not saved, or if
-@value{GDBN} is unable to locate the saved registers, the selected stack
-frame makes no difference.
+@cindex caller-saved registers
+@cindex call-clobbered registers
+@cindex volatile registers
+@cindex <not saved> values
+Usually ABIs reserve some registers as not needed to be saved by the
+callee (a.k.a.: ``caller-saved'', ``call-clobbered'' or ``volatile''
+registers). It may therefore not be possible for @value{GDBN} to know
+the value a register had before the call (in other words, in the outer
+frame), if the register value has since been changed by the callee.
+@value{GDBN} tries to deduce where the inner frame saved
+(``callee-saved'') registers, from the debug info, unwind info, or the
+machine code generated by your compiler. If some register is not
+saved, and @value{GDBN} knows the register is ``caller-saved'' (via
+its own knowledge of the ABI, or because the debug/unwind info
+explicitly says the register's value is undefined), @value{GDBN}
+displays @w{@samp{<not saved>}} as the register's value. With targets
+that @value{GDBN} has no knowledge of the register saving convention,
+if a register was not saved by the callee, then its value and location
+in the outer frame are assumed to be the same of the inner frame.
+This is usually harmless, because if the register is call-clobbered,
+the caller either does not care what is in the register after the
+call, or has code to restore the value that it does care about. Note,
+however, that if you change such a register in the outer frame, you
+may also be affecting the inner frame. Also, the more ``outer'' the
+frame is you're looking at, the more likely a call-clobbered
+register's value is to be wrong, in the sense that it doesn't actually
+represent the value the register had just before the call.
@node Floating Point Hardware
@section Floating Point Hardware
The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
character.
-@node Caching Remote Data
-@section Caching Data of Remote Targets
-@cindex caching data of remote targets
-
-@value{GDBN} caches data exchanged between the debugger and a
-remote target (@pxref{Remote Debugging}). Such caching generally improves
-performance, because it reduces the overhead of the remote protocol by
-bundling memory reads and writes into large chunks. Unfortunately, simply
-caching everything would lead to incorrect results, since @value{GDBN}
-does not necessarily know anything about volatile values, memory-mapped I/O
-addresses, etc. Furthermore, in non-stop mode (@pxref{Non-Stop Mode})
-memory can be changed @emph{while} a gdb command is executing.
+@node Caching Target Data
+@section Caching Data of Targets
+@cindex caching data of targets
+
+@value{GDBN} caches data exchanged between the debugger and a target.
+Each cache is associated with the address space of the inferior.
+@xref{Inferiors and Programs}, about inferior and address space.
+Such caching generally improves performance in remote debugging
+(@pxref{Remote Debugging}), because it reduces the overhead of the
+remote protocol by bundling memory reads and writes into large chunks.
+Unfortunately, simply caching everything would lead to incorrect results,
+since @value{GDBN} does not necessarily know anything about volatile
+values, memory-mapped I/O addresses, etc. Furthermore, in non-stop mode
+(@pxref{Non-Stop Mode}) memory can be changed @emph{while} a gdb command
+is executing.
Therefore, by default, @value{GDBN} only caches data
known to be on the stack@footnote{In non-stop mode, it is moderately
rare for a running thread to modify the stack of a stopped thread
in a way that would interfere with a backtrace, and caching of
-stack reads provides a significant speed up of remote backtraces.}.
+stack reads provides a significant speed up of remote backtraces.} or
+in the code segment.
Other regions of memory can be explicitly marked as
-cacheable; see @pxref{Memory Region Attributes}.
+cacheable; @pxref{Memory Region Attributes}.
@table @code
@kindex set remotecache
@kindex set stack-cache
@item set stack-cache on
@itemx set stack-cache off
-Enable or disable caching of stack accesses. When @code{ON}, use
-caching. By default, this option is @code{ON}.
+Enable or disable caching of stack accesses. When @code{on}, use
+caching. By default, this option is @code{on}.
@kindex show stack-cache
@item show stack-cache
Show the current state of data caching for memory accesses.
+@kindex set code-cache
+@item set code-cache on
+@itemx set code-cache off
+Enable or disable caching of code segment accesses. When @code{on},
+use caching. By default, this option is @code{on}. This improves
+performance of disassembly in remote debugging.
+
+@kindex show code-cache
+@item show code-cache
+Show the current state of target memory cache for code segment
+accesses.
+
@kindex info dcache
@item info dcache @r{[}line@r{]}
-Print the information about the data cache performance. The
-information displayed includes the dcache width and depth, and for
-each cache line, its number, address, and how many times it was
-referenced. This command is useful for debugging the data cache
-operation.
+Print the information about the performance of data cache of the
+current inferior's address space. The information displayed
+includes the dcache width and depth, and for each cache line, its
+number, address, and how many times it was referenced. This
+command is useful for debugging the data cache operation.
If a line number is specified, the contents of that line will be
printed in hex.
@item show dcache size
@kindex show dcache size
-Show maximum number of dcache entries. See also @ref{Caching Remote Data, info dcache}.
+Show maximum number of dcache entries. @xref{Caching Target Data, info dcache}.
@item show dcache line-size
@kindex show dcache line-size
-Show default size of dcache lines. See also @ref{Caching Remote Data, info dcache}.
+Show default size of dcache lines.
@end table
@table @code
@item show language
+@anchor{show language}
@kindex show language
Display the current working language. This is the
language you can use with commands such as @code{print} to
@cindex C@t{++} exception handling
@item catch throw
+@itemx catch rethrow
@itemx catch catch
Debug C@t{++} exception handling using these commands. @xref{Set
Catchpoints, , Setting Catchpoints}.
There are two encodings in use, depending on the architecture: BID (Binary
Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
-PowerPC. @value{GDBN} will use the appropriate encoding for the configured
-target.
+PowerPC and S/390. @value{GDBN} will use the appropriate encoding for the
+configured target.
Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
to manipulate decimal floating point numbers, it is not possible to convert
* Omissions from Ada:: Restrictions on the Ada expression syntax.
* Additions to Ada:: Extensions of the Ada expression syntax.
* Stopping Before Main Program:: Debugging the program during elaboration.
+* Ada Exceptions:: Ada Exceptions
* Ada Tasks:: Listing and setting breakpoints in tasks.
* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
* Ravenscar Profile:: Tasking Support when using the Ravenscar
elaboration, simply use the following two commands:
@code{tbreak adainit} and @code{run}.
+@node Ada Exceptions
+@subsubsection Ada Exceptions
+
+A command is provided to list all Ada exceptions:
+
+@table @code
+@kindex info exceptions
+@item info exceptions
+@itemx info exceptions @var{regexp}
+The @code{info exceptions} command allows you to list all Ada exceptions
+defined within the program being debugged, as well as their addresses.
+With a regular expression, @var{regexp}, as argument, only those exceptions
+whose names match @var{regexp} are listed.
+@end table
+
+Below is a small example, showing how the command can be used, first
+without argument, and next with a regular expression passed as an
+argument.
+
+@smallexample
+(@value{GDBP}) info exceptions
+All defined Ada exceptions:
+constraint_error: 0x613da0
+program_error: 0x613d20
+storage_error: 0x613ce0
+tasking_error: 0x613ca0
+const.aint_global_e: 0x613b00
+(@value{GDBP}) info exceptions const.aint
+All Ada exceptions matching regular expression "const.aint":
+constraint_error: 0x613da0
+const.aint_global_e: 0x613b00
+@end smallexample
+
+It is also possible to ask @value{GDBN} to stop your program's execution
+when an exception is raised. For more details, see @ref{Set Catchpoints}.
+
@node Ada Tasks
@subsubsection Extensions for Ada Tasks
@cindex Ada, tasking
@cindex symbol dump
@kindex maint print psymbols
@cindex partial symbol dump
+@kindex maint print msymbols
+@cindex minimal symbol dump
@item maint print symbols @var{filename}
@itemx maint print psymbols @var{filename}
@itemx maint print msymbols @var{filename}
The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command. You can use the
@code{add-symbol-file} command any number of times; the new symbol data
-thus read keeps adding to the old. To discard all old symbol data
-instead, use the @code{symbol-file} command without any arguments.
+thus read is kept in addition to the old.
+
+Changes can be reverted using the command @code{remove-symbol-file}.
@cindex relocatable object files, reading symbols from
@cindex object files, relocatable, reading symbols from
@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
+@kindex remove-symbol-file
+@item remove-symbol-file @var{filename}
+@item remove-symbol-file -a @var{address}
+Remove a symbol file added via the @code{add-symbol-file} command. The
+file to remove can be identified by its @var{filename} or by an @var{address}
+that lies within the boundaries of this symbol file in memory. Example:
+
+@smallexample
+(gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
+add symbol table from file "/home/user/gdb/mylib.so" at
+ .text_addr = 0x7ffff7ff9480
+(y or n) y
+Reading symbols from /home/user/gdb/mylib.so...done.
+(gdb) remove-symbol-file -a 0x7ffff7ff9480
+Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
+(gdb)
+@end smallexample
+
+
+@code{remove-symbol-file} does not repeat if you press @key{RET} after using it.
+
@kindex add-symbol-file-from-memory
@cindex @code{syscall DSO}
@cindex load symbols from memory
@smallexample
# Extract the dynamic symbols from the main binary, there is no need
-# to also have these in the normal symbol table
+# to also have these in the normal symbol table.
nm -D @var{binary} --format=posix --defined-only \
| awk '@{ print $1 @}' | sort > dynsyms
-# Extract all the text (i.e. function) symbols from the debuginfo .
+# Extract all the text (i.e. function) symbols from the debuginfo.
+# (Note that we actually also accept "D" symbols, for the benefit
+# of platforms like PowerPC64 that use function descriptors.)
nm @var{binary} --format=posix --defined-only \
- | awk '@{ if ($2 == "T" || $2 == "t") print $1 @}' \
+ | awk '@{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 @}' \
| sort > funcsyms
# Keep all the function symbols not already in the dynamic symbol
# table.
comm -13 dynsyms funcsyms > keep_symbols
+# Separate full debug info into debug binary.
+objcopy --only-keep-debug @var{binary} debug
+
# Copy the full debuginfo, keeping only a minimal set of symbols and
# removing some unnecessary sections.
objcopy -S --remove-section .gdb_index --remove-section .comment \
- --keep-symbols=keep_symbols @var{binary} mini_debuginfo
+ --keep-symbols=keep_symbols debug mini_debuginfo
+
+# Drop the full debug info from the original binary.
+strip --strip-all -R .comment @var{binary}
# Inject the compressed data into the .gnu_debugdata section of the
# original binary.
@end table
-Some configurations may include these targets as well:
-
-@table @code
-
-@item target nrom @var{dev}
-@cindex NetROM ROM emulator target
-NetROM ROM emulator. This target only supports downloading.
-
-@end table
-
Different targets are available on different configurations of @value{GDBN};
your configuration may have more or fewer targets.
@end smallexample
If you're using a serial line, you may want to give @value{GDBN} the
-@w{@samp{--baud}} option, or use the @code{set remotebaud} command
-(@pxref{Remote Configuration, set remotebaud}) before the
+@samp{--baud} option, or use the @code{set serial baud} command
+(@pxref{Remote Configuration, set serial baud}) before the
@code{target} command.
@item target remote @code{@var{host}:@var{port}}
@cindex @option{--once}, @code{gdbserver} option
By default, @code{gdbserver} keeps the listening TCP port open, so that
-additional connections are possible. However, if you start @code{gdbserver}
+subsequent connections are possible. However, if you start @code{gdbserver}
with the @option{--once} option, it will stop listening for any further
connection attempts after connecting to the first @value{GDBN} session. This
means no further connections to @code{gdbserver} will be possible after the
@item show remoteaddresssize
Show the current value of remote address size in bits.
-@item set remotebaud @var{n}
+@item set serial baud @var{n}
@cindex baud rate for remote targets
Set the baud rate for the remote serial I/O to @var{n} baud. The
value is used to set the speed of the serial port used for debugging
remote targets.
-@item show remotebaud
+@item show serial baud
Show the current speed of the remote connection.
@item set remotebreak
* HPPA:: HP PA architecture
* SPU:: Cell Broadband Engine SPU architecture
* PowerPC::
+* Nios II::
@end menu
@node AArch64
from functions.
@end table
+@subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX).
+@cindex Intel(R) Memory Protection Extensions (MPX).
+
+Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
+@footnote{The register named with capital letters represent the architecture
+registers.} through @samp{BND3}. Bound registers store a pair of 64-bit values
+which are the lower bound and upper bound. Bounds are effective addresses or
+memory locations. The upper bounds are architecturally represented in 1's
+complement form. A bound having lower bound = 0, and upper bound = 0
+(1's complement of all bits set) will allow access to the entire address space.
+
+@samp{BND0} through @samp{BND3} are represented in @value{GDBN} as @samp{bnd0raw}
+through @samp{bnd3raw}. Pseudo registers @samp{bnd0} through @samp{bnd3}
+display the upper bound performing the complement of one operation on the
+upper bound value, i.e.@ when upper bound in @samp{bnd0raw} is 0 in the
+@value{GDBN} @samp{bnd0} it will be @code{0xfff@dots{}}. In this sense it
+can also be noted that the upper bounds are inclusive.
+
+As an example, assume that the register BND0 holds bounds for a pointer having
+access allowed for the range between 0x32 and 0x71. The values present on
+bnd0raw and bnd registers are presented as follows:
+
+@smallexample
+ bnd0raw = @{0x32, 0xffffffff8e@}
+ bnd0 = @{lbound = 0x32, ubound = 0x71@} : size 64
+@end smallexample
+
+This way the raw value can be accessed via bnd0raw@dots{}bnd3raw. Any
+change on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its
+counterpart. When the bnd0@dots{}bnd3 registers are displayed via
+Python, the display includes the memory size, in bits, accessible to
+the pointer.
+
@node Alpha
@subsection Alpha
For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit
wide Extended Floating Point Registers (@samp{f32} through @samp{f63}).
+@node Nios II
+@subsection Nios II
+@cindex Nios II architecture
+
+When @value{GDBN} is debugging the Nios II architecture,
+it provides the following special commands:
+
+@table @code
+
+@item set debug nios2
+@kindex set debug nios2
+This command turns on and off debugging messages for the Nios II
+target code in @value{GDBN}.
+
+@item show debug nios2
+@kindex show debug nios2
+Show the current setting of Nios II debugging messages.
+@end table
@node Controlling GDB
@chapter Controlling @value{GDBN}
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 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
Turns on or off display of gdbarch debugging info. The default is off
@item show debug arch
Displays the current state of displaying gdbarch debugging info.
+@item set debug aix-solib
+@cindex AIX shared library debugging
+Control display of debugging messages from the AIX shared library
+support module. The default is off.
+@item show debug aix-thread
+Show the current state of displaying AIX shared library debugging messages.
@item set debug aix-thread
@cindex AIX threads
Display debugging messages about inner workings of the AIX thread
@item set debug dwarf2-read
@cindex DWARF2 Reading
Turns on or off display of debugging messages related to reading
-DWARF debug info. The default is off.
+DWARF debug info. The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
@item show debug dwarf2-read
Show the current state of DWARF2 reader debugging.
@item set debug displaced
@item show debug solib-frv
Display the current state of FR-V shared-library code debugging
messages.
+@item set debug symfile
+@cindex symbol file functions
+Turns on or off display of debugging messages related to symbol file functions.
+The default is off. @xref{Files}.
+@item show debug symfile
+Show the current state of symbol file debugging messages.
@item set debug symtab-create
@cindex symbol table creation
Turns on or off display of debugging messages related to symbol table creation.
-The default is off.
+The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
@item show debug symtab-create
Show the current state of symbol table creation debugging.
@item set debug target
@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.
-To facilitate the use of the first two extensions, @value{GDBN} is capable
+@menu
+* Sequences:: Canned Sequences of @value{GDBN} Commands
+* Python:: Extending @value{GDBN} using Python
+* Auto-loading extensions:: Automatically loading extensions
+* Aliases:: Creating new spellings of existing commands
+@end menu
+
+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
@end table
+@node Auto-loading sequences
+@subsection Controlling auto-loading native @value{GDBN} scripts
+@cindex native script 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 the command file @file{@var{objfile}-gdb.gdb}.
+@xref{Auto-loading extensions}.
+
+Auto-loading can be enabled or disabled,
+and the list of auto-loaded scripts can be printed.
+
+@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 Python
-@section Scripting @value{GDBN} using Python
+@section Extending @value{GDBN} using Python
@cindex python scripting
@cindex scripting with python
-You can script @value{GDBN} using the @uref{http://www.python.org/,
+You can extend @value{GDBN} using the @uref{http://www.python.org/,
Python programming language}. This feature is available only if
@value{GDBN} was configured using @option{--with-python}.
@cindex python api
@cindex programming in 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.
+You can get quick online help for @value{GDBN}'s Python API by issuing
+the command @w{@kbd{python help (gdb)}}.
+
+Functions and methods which have two or more optional arguments allow
+them to be specified using keyword syntax. This allows passing some
+optional arguments while skipping others. Example:
+@w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
@menu
* Basic Python:: Basic Python Functions.
* 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.
* Progspaces In Python:: Program spaces.
* Objfiles In Python:: Object files.
* Frames In Python:: Accessing inferior stack frames from Python.
-* Blocks In Python:: Accessing frame blocks 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.
@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
bar = some_val['foo']
@end smallexample
-Again, @code{bar} will also be a @code{gdb.Value} object.
+@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
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.
+This attribute is not available for @code{enum} or @code{static}
+(as in C@t{++} or Java) fields. The value is the position, counting
+in bits, from the start of the containing type.
+
+@item enumval
+This attribute is only available for @code{enum} fields, and its value
+is the enumeration member's integer representation.
@item name
The name of the field, or @code{None} for anonymous fields.
@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
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
@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
@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
@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 ()
No particular reason (older frames should be available).
@item gdb.FRAME_UNWIND_NULL_ID
-The previous frame's analyzer returns an invalid result.
+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.
@end defun
@node Blocks In Python
-@subsubsection Accessing frame blocks from Python.
+@subsubsection Accessing blocks from Python.
@cindex blocks in python
@tindex gdb.Block
-Within each frame, @value{GDBN} maintains information on each block
-stored in that frame. These blocks are organized hierarchically, and
-are represented individually in Python as a @code{gdb.Block}.
-Please see @ref{Frames In Python}, for a more in-depth discussion on
-frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more
-detailed technical information on @value{GDBN}'s book-keeping of the
-stack.
+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
@findex gdb.block_for_pc
@defun gdb.block_for_pc (pc)
-Return the @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}.
+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:
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
@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
Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
class.
-@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal@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{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.
+@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 as a sub-class of @code{gdb.Breakpoint},
+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
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:
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}).
+@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
+@xref{Auto-loading extensions}.
The auto-loading feature is useful for supplying application-specific
debugging commands and scripts.
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.
-
-@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.
-
-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
-@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
-
-For object files using @file{.exe} suffix @value{GDBN} tries to load first the
-scripts normally according to its @file{.exe} filename. But if no scripts are
-found @value{GDBN} also tries script filenames matching the object file without
-its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it
-is attempted on any platform. This makes the script filenames compatible
-between Unix and MS-Windows hosts.
-
-@table @code
-@anchor{set auto-load scripts-directory}
-@kindex set auto-load scripts-directory
-@item set auto-load scripts-directory @r{[}@var{directories}@r{]}
-Control @value{GDBN} auto-loaded scripts location. Multiple directory entries
-may be delimited by the host platform path separator in use
-(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS).
-
-Each entry here needs to be covered also by the security setting
-@code{set auto-load safe-path} (@pxref{set auto-load safe-path}).
-
-@anchor{with-auto-load-dir}
-This variable defaults to @file{$debugdir:$datadir/auto-load}. The default
-@code{set auto-load safe-path} value can be also overriden by @value{GDBN}
-configuration option @option{--with-auto-load-dir}.
-
-Any reference to @file{$debugdir} will get replaced by
-@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any
-reference to @file{$datadir} will get replaced by @var{data-directory} which is
-determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and
-@file{$datadir} must be placed as a directory component --- either alone or
-delimited by @file{/} or @file{\} directory separators, depending on the host
-platform.
-
-The list of directories uses path separator (@samp{:} on GNU and Unix
-systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
-to the @env{PATH} environment variable.
-
-@anchor{show auto-load scripts-directory}
-@kindex show auto-load scripts-directory
-@item show auto-load scripts-directory
-Show @value{GDBN} auto-loaded scripts location.
-@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
-is evaluated more than once.
-
-@node dotdebug_gdb_scripts section
-@subsubsection 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.
-
-@value{GDBN} will look for each specified script file first in the
-current directory and then along the source search path
-(@pxref{Source Path, ,Specifying Source Directories}),
-except that @file{$cdir} is not searched, since the compilation
-directory is not relevant to scripts.
-
-Entries can be placed in section @code{.debug_gdb_scripts} with,
-for example, this GCC macro:
-
-@example
-/* Note: The "MS" section flags are to remove duplicates. */
-#define DEFINE_GDB_SCRIPT(script_name) \
- asm("\
-.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
-.byte 1\n\
-.asciz \"" script_name "\"\n\
-.popsection \n\
-");
-@end example
-
-@noindent
-Then one can reference the macro in a header or source file like this:
-
-@example
-DEFINE_GDB_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.
-
-@node Which flavor to choose?
-@subsubsection Which flavor to choose?
-
-Given the multiple ways of auto-loading Python scripts, it might not always
-be clear which one to choose. This section provides some guidance.
-
-Benefits of the @file{-gdb.py} way:
-
-@itemize @bullet
-@item
-Can be used with file formats that don't support multiple sections.
-
-@item
-Ease of finding scripts for public libraries.
-
-Scripts specified in the @code{.debug_gdb_scripts} section are searched for
-in the source search path.
-For publicly installed libraries, e.g., @file{libstdc++}, there typically
-isn't a source directory in which to find the script.
-
-@item
-Doesn't require source code additions.
-@end itemize
-
-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
-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.
-
-@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.
-
-@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
-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
+registering objfile-specific pretty-printers and frame-filters.
@node Python modules
@subsection Python modules
@end smallexample
@end table
+@node Auto-loading extensions
+@section Auto-loading extensions
+@cindex auto-loading extensions
+
+@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
+* 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
+
+The auto-loading feature is useful for supplying application-specific
+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}.
+
+Note that loading of this script file also requires accordingly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+
+@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}
+
+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:
+
+@table @code
+@item @file{@var{objfile}-gdb.gdb}
+GDB's own command language
+@item @file{@var{objfile}-gdb.py}
+Python
+@end table
+
+@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 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
+scripts normally according to its @file{.exe} filename. But if no scripts are
+found @value{GDBN} also tries script filenames matching the object file without
+its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it
+is attempted on any platform. This makes the script filenames compatible
+between Unix and MS-Windows hosts.
+
+@table @code
+@anchor{set auto-load scripts-directory}
+@kindex set auto-load scripts-directory
+@item set auto-load scripts-directory @r{[}@var{directories}@r{]}
+Control @value{GDBN} auto-loaded scripts location. Multiple directory entries
+may be delimited by the host platform path separator in use
+(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS).
+
+Each entry here needs to be covered also by the security setting
+@code{set auto-load safe-path} (@pxref{set auto-load safe-path}).
+
+@anchor{with-auto-load-dir}
+This variable defaults to @file{$debugdir:$datadir/auto-load}. The default
+@code{set auto-load safe-path} value can be also overriden by @value{GDBN}
+configuration option @option{--with-auto-load-dir}.
+
+Any reference to @file{$debugdir} will get replaced by
+@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any
+reference to @file{$datadir} will get replaced by @var{data-directory} which is
+determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and
+@file{$datadir} must be placed as a directory component --- either alone or
+delimited by @file{/} or @file{\} directory separators, depending on the host
+platform.
+
+The list of directories uses path separator (@samp{:} on GNU and Unix
+systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
+to the @env{PATH} environment variable.
+
+@anchor{show auto-load scripts-directory}
+@kindex show auto-load scripts-directory
+@item show auto-load scripts-directory
+Show @value{GDBN} auto-loaded scripts location.
+@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.@var{ext}} file should be careful to avoid errors if it
+is evaluated more than once.
+
+@node dotdebug_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 @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
+(@pxref{Source Path, ,Specifying Source Directories}),
+except that @file{$cdir} is not searched, since the compilation
+directory is not relevant to scripts.
+
+Entries can be placed in section @code{.debug_gdb_scripts} with,
+for example, this GCC macro for Python scripts.
+
+@example
+/* Note: The "MS" section flags are to remove duplicates. */
+#define DEFINE_GDB_PY_SCRIPT(script_name) \
+ asm("\
+.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
+.byte 1 /* Python */\n\
+.asciz \"" script_name "\"\n\
+.popsection \n\
+");
+@end example
+
+@noindent
+Then one can reference the macro in a header or source file like this:
+
+@example
+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 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?
+@subsection Which flavor to choose?
+
+Given the multiple ways of auto-loading extensions, it might not always
+be clear which one to choose. This section provides some guidance.
+
+@noindent
+Benefits of the @file{-gdb.@var{ext}} way:
+
+@itemize @bullet
+@item
+Can be used with file formats that don't support multiple sections.
+
+@item
+Ease of finding scripts for public libraries.
+
+Scripts specified in the @code{.debug_gdb_scripts} section are searched for
+in the source search path.
+For publicly installed libraries, e.g., @file{libstdc++}, there typically
+isn't a source directory in which to find the script.
+
+@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.@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.@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.@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.@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 Aliases
@section Creating new spellings of existing commands
@cindex aliases for commands
@end ignore
* GDB/MI Target Manipulation::
* GDB/MI File Transfer Commands::
+* GDB/MI Ada Exceptions Commands::
+* GDB/MI Support Commands::
* GDB/MI Miscellaneous Commands::
@end menu
@node Context management
@subsection Context management
+@subsubsection Threads and Frames
+
In most cases when @value{GDBN} accesses the target, this access is
done in context of a specific thread and frame (@pxref{Frames}).
Often, even when accessing global data, the target requires that a thread
right, so it is suggested to just always pass the @samp{--thread} and
@samp{--frame} options.
+@subsubsection Language
+
+The execution of several commands depends on which language is selected.
+By default, the current language (@pxref{show language}) is used.
+But for commands known to be language-sensitive, it is recommended
+to use the @samp{--language} option. This option takes one argument,
+which is the name of the language to use while executing the command.
+For instance:
+
+@smallexample
+-data-evaluate-expression --language c "sizeof (void*)"
+^done,value="4"
+(gdb)
+@end smallexample
+
+The valid language names are the same names accepted by the
+@samp{set language} command (@pxref{Manually}), excluding @samp{auto},
+@samp{local} or @samp{unknown}.
+
@node Asynchronous and non-stop modes
@subsection Asynchronous command execution and non-stop mode
@findex ^connected
@value{GDBN} has connected to a remote target.
-@item "^error" "," @var{c-string}
+@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ]
@findex ^error
-The operation failed. The @code{@var{c-string}} contains the corresponding
-error message.
+The operation failed. The @code{msg=@var{c-string}} variable contains
+the corresponding error message.
+
+If present, the @code{code=@var{c-string}} variable provides an error
+code on which consumers can rely on to detect the corresponding
+error condition. At present, only one error code is defined:
+
+@table @samp
+@item "undefined-command"
+Indicates that the command causing the error does not exist.
+@end table
@item "^exit"
@findex ^exit
@c (gdb)
@end smallexample
+@subheading The @code{-dprintf-insert} Command
+@findex -dprintf-insert
+
+@subsubheading Synopsis
+
+@smallexample
+ -dprintf-insert [ -t ] [ -f ] [ -d ]
+ [ -c @var{condition} ] [ -i @var{ignore-count} ]
+ [ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ]
+ [ @var{argument} ]
+@end smallexample
+
+@noindent
+If specified, @var{location}, can be one of:
+
+@itemize @bullet
+@item @var{function}
+@c @item +offset
+@c @item -offset
+@c @item @var{linenum}
+@item @var{filename}:@var{linenum}
+@item @var{filename}:function
+@item *@var{address}
+@end itemize
+
+The possible optional parameters of this command are:
+
+@table @samp
+@item -t
+Insert a temporary breakpoint.
+@item -f
+If @var{location} cannot be parsed (for example, if it
+refers to unknown files or functions), create a pending
+breakpoint. Without this flag, @value{GDBN} will report
+an error, and won't create a breakpoint, if @var{location}
+cannot be parsed.
+@item -d
+Create a disabled breakpoint.
+@item -c @var{condition}
+Make the breakpoint conditional on @var{condition}.
+@item -i @var{ignore-count}
+Set the ignore count of the breakpoint (@pxref{Conditions, ignore count})
+to @var{ignore-count}.
+@item -p @var{thread-id}
+Restrict the breakpoint to the specified @var{thread-id}.
+@end table
+
+@subsubheading Result
+
+@xref{GDB/MI Breakpoint Information}, for details on the format of the
+resulting breakpoint.
+
+@c An out-of-band breakpoint instead of part of the result?
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{dprintf}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+4-dprintf-insert foo "At foo entry\n"
+4^done,bkpt=@{number="1",type="dprintf",disp="keep",enabled="y",
+addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
+fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
+times="0",script=@{"printf \"At foo entry\\n\"","continue"@},
+original-location="foo"@}
+(gdb)
+5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
+5^done,bkpt=@{number="2",type="dprintf",disp="keep",enabled="y",
+addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
+fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
+times="0",script=@{"printf \"arg=%d, g=%d\\n\", arg, g","continue"@},
+original-location="mi-dprintf.c:26"@}
+(gdb)
+@end smallexample
+
@subheading The @code{-break-list} Command
@findex -break-list
This section documents @sc{gdb/mi} commands for manipulating
catchpoints.
+@menu
+* Shared Library GDB/MI Catchpoint Commands::
+* Ada Exception GDB/MI Catchpoint Commands::
+@end menu
+
+@node Shared Library GDB/MI Catchpoint Commands
+@subsection Shared Library @sc{gdb/mi} Catchpoints
+
@subheading The @code{-catch-load} Command
@findex -catch-load
(gdb)
@end smallexample
+@node Ada Exception GDB/MI Catchpoint Commands
+@subsection Ada Exception @sc{gdb/mi} Catchpoints
+
+The following @sc{gdb/mi} commands can be used to create catchpoints
+that stop the execution when Ada exceptions are being raised.
+
+@subheading The @code{-catch-assert} Command
+@findex -catch-assert
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-assert [ -c @var{condition}] [ -d ] [ -t ]
+@end smallexample
+
+Add a catchpoint for failed Ada assertions.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -t
+Create a temporary catchpoint.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch assert}.
+
+@subsubheading Example
+
+@smallexample
+-catch-assert
+^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
+thread-groups=["i1"],times="0",
+original-location="__gnat_debug_raise_assert_failure"@}
+(gdb)
+@end smallexample
+
+@subheading The @code{-catch-exception} Command
+@findex -catch-exception
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
+ [ -t ] [ -u ]
+@end smallexample
+
+Add a catchpoint stopping when Ada exceptions are raised.
+By default, the command stops the program when any Ada exception
+gets raised. But it is also possible, by using some of the
+optional parameters described below, to create more selective
+catchpoints.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -e @var{exception-name}
+Only stop when @var{exception-name} is raised. This option cannot
+be used combined with @samp{-u}.
+@item -t
+Create a temporary catchpoint.
+@item -u
+Stop only when an unhandled exception gets raised. This option
+cannot be used combined with @samp{-e}.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch exception}
+and @samp{catch exception unhandled}.
+
+@subsubheading Example
+
+@smallexample
+-catch-exception -e Program_Error
+^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000404874",
+what="`Program_Error' Ada exception", thread-groups=["i1"],
+times="0",original-location="__gnat_debug_raise_exception"@}
+(gdb)
+@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Context
@subsubheading Synopsis
@smallexample
- -exec-run [--all | --thread-group N]
+ -exec-run [ --all | --thread-group N ] [ --start ]
@end smallexample
Starts execution of the inferior from the beginning. The inferior
exits. In the latter case the output will include an exit code, if
the program has exited exceptionally.
-When no option is specified, the current inferior is started. If the
+When neither the @samp{--all} nor the @samp{--thread-group} option
+is specified, the current inferior is started. If the
@samp{--thread-group} option is specified, it should refer to a thread
group of type @samp{process}, and that thread group will be started.
If the @samp{--all} option is specified, then all inferiors will be started.
+Using the @samp{--start} option instructs the debugger to stop
+the execution at the start of the inferior's main subprogram,
+following the same behavior as the @code{start} command
+(@pxref{Starting}).
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{run}.
@node GDB/MI Stack Manipulation
@section @sc{gdb/mi} Stack Manipulation Commands
+@subheading The @code{-enable-frame-filters} Command
+@findex -enable-frame-filters
+
+@smallexample
+-enable-frame-filters
+@end smallexample
+
+@value{GDBN} allows Python-based frame filters to affect the output of
+the MI commands relating to stack traces. As there is no way to
+implement this in a fully backward-compatible way, a front end must
+request that this functionality be enabled.
+
+Once enabled, this feature cannot be disabled.
+
+Note that if Python support has not been compiled into @value{GDBN},
+this command will still succeed (and do nothing).
@subheading The @code{-stack-info-frame} Command
@findex -stack-info-frame
(gdb)
@end smallexample
+@anchor{-stack-list-arguments}
@subheading The @code{-stack-list-arguments} Command
@findex -stack-list-arguments
@subsubheading Synopsis
@smallexample
- -stack-list-arguments @var{print-values}
+ -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
[ @var{low-frame} @var{high-frame} ]
@end smallexample
the variables; if it is 1 or @code{--all-values}, print also their
values; and if it is 2 or @code{--simple-values}, print the name,
type and value for simple data types, and the name and type for arrays,
-structures and unions.
+structures and unions. If the option @code{--no-frame-filters} is
+supplied, then Python frame filters will not be executed.
+
+If the @code{--skip-unavailable} option is specified, arguments that
+are not available are not listed. Partially available arguments
+are still displayed, however.
Use of this command to obtain arguments in a single frame is
deprecated in favor of the @samp{-stack-list-variables} command.
@c @subheading -stack-list-exception-handlers
+@anchor{-stack-list-frames}
@subheading The @code{-stack-list-frames} Command
@findex -stack-list-frames
@subsubheading Synopsis
@smallexample
- -stack-list-frames [ @var{low-frame} @var{high-frame} ]
+ -stack-list-frames [ --no-frame-filters @var{low-frame} @var{high-frame} ]
@end smallexample
List the frames currently on the stack. For each frame it displays the
are equal, it shows the single frame at the corresponding level. It is
an error if @var{low-frame} is larger than the actual number of
frames. On the other hand, @var{high-frame} may be larger than the
-actual number of frames, in which case only existing frames will be returned.
+actual number of frames, in which case only existing frames will be
+returned. If the option @code{--no-frame-filters} is supplied, then
+Python frame filters will not be executed.
@subsubheading @value{GDBN} Command
@subheading The @code{-stack-list-locals} Command
@findex -stack-list-locals
+@anchor{-stack-list-locals}
@subsubheading Synopsis
@smallexample
- -stack-list-locals @var{print-values}
+ -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
@end smallexample
Display the local variable names for the selected frame. If
structures and unions. In this last case, a frontend can immediately
display the value of simple data types and create variable objects for
other data types when the user wishes to explore their values in
-more detail.
+more detail. If the option @code{--no-frame-filters} is supplied, then
+Python frame filters will not be executed.
+
+If the @code{--skip-unavailable} option is specified, local variables
+that are not available are not listed. Partially available local
+variables are still displayed, however.
This command is deprecated in favor of the
@samp{-stack-list-variables} command.
(gdb)
@end smallexample
+@anchor{-stack-list-variables}
@subheading The @code{-stack-list-variables} Command
@findex -stack-list-variables
@subsubheading Synopsis
@smallexample
- -stack-list-variables @var{print-values}
+ -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
@end smallexample
Display the names of local variables and function arguments for the selected frame. If
the variables; if it is 1 or @code{--all-values}, print also their
values; and if it is 2 or @code{--simple-values}, print the name,
type and value for simple data types, and the name and type for arrays,
-structures and unions.
+structures and unions. If the option @code{--no-frame-filters} is
+supplied, then Python frame filters will not be executed.
+
+If the @code{--skip-unavailable} option is specified, local variables
+and arguments that are not available are not listed. Partially
+available arguments and local variables are still displayed, however.
@subsubheading Example
@item frozen
If the variable object is frozen, this variable will be present with a value of 1.
+
+@item displayhint
+A dynamic varobj can supply a display hint to the front end. The
+value comes directly from the Python pretty-printer object's
+@code{display_hint} method. @xref{Pretty Printing API}.
+
+@item dynamic
+This attribute will be present and have the value @samp{1} if the
+varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
+then this attribute will not be present.
+
@end table
The result may have its own attributes:
@end smallexample
@noindent
-Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}.
+Here, the value of @code{lang} is the language name, which can be
+found in @ref{Supported Languages}.
Note that the output of the @code{-var-list-children} command also
includes those expressions, so the @code{-var-info-expression} command
a varobj is created, and so ordinarily is not needed.
This feature is only available if Python support is enabled. The MI
-command @code{-list-features} (@pxref{GDB/MI Miscellaneous Commands})
+command @code{-list-features} (@pxref{GDB/MI Support Commands})
can be used to check this.
@subsubheading Example
@subsubheading Synopsis
@smallexample
- -data-list-register-values @var{fmt} [ ( @var{regno} )*]
+ -data-list-register-values
+ [ @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.
+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 corresponding @value{GDBN} command is @samp{tvariable}.
+@subheading The @code{-trace-frame-collected} Command
+@findex -trace-frame-collected
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-frame-collected
+ [--var-print-values @var{var_pval}]
+ [--comp-print-values @var{comp_pval}]
+ [--registers-format @var{regformat}]
+ [--memory-contents]
+@end smallexample
+
+This command returns the set of collected objects, register names,
+trace state variable names, memory ranges and computed expressions
+that have been collected at a particular trace frame. The optional
+parameters to the command affect the output format in different ways.
+See the output description table below for more details.
+
+The reported names can be used in the normal manner to create
+varobjs and inspect the objects themselves. The items returned by
+this command are categorized so that it is clear which is a variable,
+which is a register, which is a trace state variable, which is a
+memory range and which is a computed expression.
+
+For instance, if the actions were
+@smallexample
+collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2
+collect *(int*)0xaf02bef0@@40
+@end smallexample
+
+@noindent
+the object collected in its entirety would be @code{myVar}. The
+object @code{myArray} would be partially collected, because only the
+element at index @code{myIndex} would be collected. The remaining
+objects would be computed expressions.
+
+An example output would be:
+
+@smallexample
+(gdb)
+-trace-frame-collected
+^done,
+ explicit-variables=[@{name="myVar",value="1"@}],
+ computed-expressions=[@{name="myArray[myIndex]",value="0"@},
+ @{name="myObj.field",value="0"@},
+ @{name="myPtr->field",value="1"@},
+ @{name="myCount + 2",value="3"@},
+ @{name="$tvar1 + 1",value="43970027"@}],
+ registers=[@{number="0",value="0x7fe2c6e79ec8"@},
+ @{number="1",value="0x0"@},
+ @{number="2",value="0x4"@},
+ ...
+ @{number="125",value="0x0"@}],
+ tvars=[@{name="$tvar1",current="43970026"@}],
+ memory=[@{address="0x0000000000602264",length="4"@},
+ @{address="0x0000000000615bc0",length="4"@}]
+(gdb)
+@end smallexample
+
+Where:
+
+@table @code
+@item explicit-variables
+The set of objects that have been collected in their entirety (as
+opposed to collecting just a few elements of an array or a few struct
+members). For each object, its name and value are printed.
+The @code{--var-print-values} option affects how or whether the value
+field is output. If @var{var_pval} is 0, then print only the names;
+if it is 1, print also their values; and if it is 2, print the name,
+type and value for simple data types, and the name and type for
+arrays, structures and unions.
+
+@item computed-expressions
+The set of computed expressions that have been collected at the
+current trace frame. The @code{--comp-print-values} option affects
+this set like the @code{--var-print-values} option affects the
+@code{explicit-variables} set. See above.
+
+@item registers
+The registers that have been collected at the current trace frame.
+For each register collected, the name and current value are returned.
+The value is formatted according to the @code{--registers-format}
+option. See the @command{-data-list-register-values} command for a
+list of the allowed formats. The default is @samp{x}.
+
+@item tvars
+The trace state variables that have been collected at the current
+trace frame. For each trace state variable collected, the name and
+current value are returned.
+
+@item memory
+The set of memory ranges that have been collected at the current trace
+frame. Its content is a list of tuples. Each tuple represents a
+collected memory range and has the following fields:
+
+@table @code
+@item address
+The start address of the memory range, as hexadecimal literal.
+
+@item length
+The length of the memory range, as decimal literal.
+
+@item contents
+The contents of the memory block, in hex. This field is only present
+if the @code{--memory-contents} option is specified.
+
+@end table
+
+@end table
+
+@subsubheading @value{GDBN} Command
+
+There is no corresponding @value{GDBN} command.
+
+@subsubheading Example
+
@subheading -trace-list-variables
@findex -trace-list-variables
@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Ada Exceptions Commands
+@section Ada Exceptions @sc{gdb/mi} Commands
+
+@subheading The @code{-info-ada-exceptions} Command
+@findex -info-ada-exceptions
+
+@subsubheading Synopsis
+
+@smallexample
+ -info-ada-exceptions [ @var{regexp}]
+@end smallexample
+
+List all Ada exceptions defined within the program being debugged.
+With a regular expression @var{regexp}, only those exceptions whose
+names match @var{regexp} are listed.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info exceptions}.
+
+@subsubheading Result
+
+The result is a table of Ada exceptions. The following columns are
+defined for each exception:
+
+@table @samp
+@item name
+The name of the exception.
+
+@item address
+The address of the exception.
+
+@end table
+
+@subsubheading Example
+
+@smallexample
+-info-ada-exceptions aint
+^done,ada-exceptions=@{nr_rows="2",nr_cols="2",
+hdr=[@{width="1",alignment="-1",col_name="name",colhdr="Name"@},
+@{width="1",alignment="-1",col_name="address",colhdr="Address"@}],
+body=[@{name="constraint_error",address="0x0000000000613da0"@},
+@{name="const.aint_global_e",address="0x0000000000613b00"@}]@}
+@end smallexample
+
+@subheading Catching Ada Exceptions
+
+The commands describing how to ask @value{GDBN} to stop when a program
+raises an exception are described at @ref{Ada Exception GDB/MI
+Catchpoint Commands}.
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Support Commands
+@section @sc{gdb/mi} Support Commands
+
+Since new commands and features get regularly added to @sc{gdb/mi},
+some commands are available to help front-ends query the debugger
+about support for these capabilities. Similarly, it is also possible
+to query @value{GDBN} about target support of certain features.
+
+@subheading The @code{-info-gdb-mi-command} Command
+@cindex @code{-info-gdb-mi-command}
+@findex -info-gdb-mi-command
+
+@subsubheading Synopsis
+
+@smallexample
+ -info-gdb-mi-command @var{cmd_name}
+@end smallexample
+
+Query support for the @sc{gdb/mi} command named @var{cmd_name}.
+
+Note that the dash (@code{-}) starting all @sc{gdb/mi} commands
+is technically not part of the command name (@pxref{GDB/MI Input
+Syntax}), and thus should be omitted in @var{cmd_name}. However,
+for ease of use, this command also accepts the form with the leading
+dash.
+
+@subsubheading @value{GDBN} Command
+
+There is no corresponding @value{GDBN} command.
+
+@subsubheading Result
+
+The result is a tuple. There is currently only one field:
+
+@table @samp
+@item exists
+This field is equal to @code{"true"} if the @sc{gdb/mi} command exists,
+@code{"false"} otherwise.
+
+@end table
+
+@subsubheading Example
+
+Here is an example where the @sc{gdb/mi} command does not exist:
+
+@smallexample
+-info-gdb-mi-command unsupported-command
+^done,command=@{exists="false"@}
+@end smallexample
+
+@noindent
+And here is an example where the @sc{gdb/mi} command is known
+to the debugger:
+
+@smallexample
+-info-gdb-mi-command symbol-list-lines
+^done,command=@{exists="true"@}
+@end smallexample
+
+@subheading The @code{-list-features} Command
+@findex -list-features
+@cindex supported @sc{gdb/mi} features, list
+
+Returns a list of particular features of the MI protocol that
+this version of gdb implements. A feature can be a command,
+or a new field in an output of some command, or even an
+important bugfix. While a frontend can sometimes detect presence
+of a feature at runtime, it is easier to perform detection at debugger
+startup.
+
+The command returns a list of strings, with each string naming an
+available feature. Each returned string is just a name, it does not
+have any internal structure. The list of possible feature names
+is given below.
+
+Example output:
+
+@smallexample
+(gdb) -list-features
+^done,result=["feature1","feature2"]
+@end smallexample
+
+The current list of features is:
+
+@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
+of @code{-varobj-create}.
+@item pending-breakpoints
+Indicates support for the @option{-f} option to the @code{-break-insert}
+command.
+@item python
+Indicates Python scripting support, Python-based
+pretty-printing commands, and possible presence of the
+@samp{display_hint} field in the output of @code{-var-list-children}
+@item thread-info
+Indicates support for the @code{-thread-info} command.
+@item data-read-memory-bytes
+Indicates support for the @code{-data-read-memory-bytes} and the
+@code{-data-write-memory-bytes} commands.
+@item breakpoint-notifications
+Indicates that changes to breakpoints and breakpoints created via the
+CLI will be announced via async records.
+@item ada-task-info
+Indicates support for the @code{-ada-task-info} command.
+@item language-option
+Indicates that all @sc{gdb/mi} commands accept the @option{--language}
+option (@pxref{Context management}).
+@item info-gdb-mi-command
+Indicates support for the @code{-info-gdb-mi-command} command.
+@item undefined-command-error-code
+Indicates support for the "undefined-command" error code in error result
+records, produced when trying to execute an undefined @sc{gdb/mi} command
+(@pxref{GDB/MI Result Records}).
+@item exec-run-start-option
+Indicates that the @code{-exec-run} command supports the @option{--start}
+option (@pxref{GDB/MI Program Execution}).
+@end ftable
+
+@subheading The @code{-list-target-features} Command
+@findex -list-target-features
+
+Returns a list of particular features that are supported by the
+target. Those features affect the permitted MI commands, but
+unlike the features reported by the @code{-list-features} command, the
+features depend on which target GDB is using at the moment. Whenever
+a target can change, due to commands such as @code{-target-select},
+@code{-target-attach} or @code{-exec-run}, the list of target features
+may change, and the frontend should obtain it again.
+Example output:
+
+@smallexample
+(gdb) -list-target-features
+^done,result=["async"]
+@end smallexample
+
+The current list of features is:
+
+@table @samp
+@item async
+Indicates that the target is capable of asynchronous command
+execution, which means that @value{GDBN} will accept further commands
+while the target is running.
+
+@item reverse
+Indicates that the target is capable of reverse execution.
+@xref{Reverse Execution}, for more information.
+
+@end table
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Miscellaneous Commands
@section Miscellaneous @sc{gdb/mi} Commands
(gdb)
@end smallexample
-@subheading The @code{-list-features} Command
-@findex -list-features
-
-Returns a list of particular features of the MI protocol that
-this version of gdb implements. A feature can be a command,
-or a new field in an output of some command, or even an
-important bugfix. While a frontend can sometimes detect presence
-of a feature at runtime, it is easier to perform detection at debugger
-startup.
-
-The command returns a list of strings, with each string naming an
-available feature. Each returned string is just a name, it does not
-have any internal structure. The list of possible feature names
-is given below.
-
-Example output:
-
-@smallexample
-(gdb) -list-features
-^done,result=["feature1","feature2"]
-@end smallexample
-
-The current list of features is:
-
-@table @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
-of @code{-varobj-create}.
-@item pending-breakpoints
-Indicates support for the @option{-f} option to the @code{-break-insert}
-command.
-@item python
-Indicates Python scripting support, Python-based
-pretty-printing commands, and possible presence of the
-@samp{display_hint} field in the output of @code{-var-list-children}
-@item thread-info
-Indicates support for the @code{-thread-info} command.
-@item data-read-memory-bytes
-Indicates support for the @code{-data-read-memory-bytes} and the
-@code{-data-write-memory-bytes} commands.
-@item breakpoint-notifications
-Indicates that changes to breakpoints and breakpoints created via the
-CLI will be announced via async records.
-@item ada-task-info
-Indicates support for the @code{-ada-task-info} command.
-@end table
-
-@subheading The @code{-list-target-features} Command
-@findex -list-target-features
-
-Returns a list of particular features that are supported by the
-target. Those features affect the permitted MI commands, but
-unlike the features reported by the @code{-list-features} command, the
-features depend on which target GDB is using at the moment. Whenever
-a target can change, due to commands such as @code{-target-select},
-@code{-target-attach} or @code{-exec-run}, the list of target features
-may change, and the frontend should obtain it again.
-Example output:
-
-@smallexample
-(gdb) -list-features
-^done,result=["async"]
-@end smallexample
-
-The current list of features is:
-
-@table @samp
-@item async
-Indicates that the target is capable of asynchronous command
-execution, which means that @value{GDBN} will accept further commands
-while the target is running.
-
-@item reverse
-Indicates that the target is capable of reverse execution.
-@xref{Reverse Execution}, for more information.
-
-@end table
-
@subheading The @code{-list-thread-groups} Command
@findex -list-thread-groups
inferior is not associated with any executable. Such association may
be established with the @samp{-file-exec-and-symbols} command
(@pxref{GDB/MI File Commands}). The command response has a single
-field, @samp{thread-group}, whose value is the identifier of the
+field, @samp{inferior}, whose value is the identifier of the
thread group corresponding to the new inferior.
@subheading Example
@smallexample
@value{GDBP}
-add-inferior
-^done,thread-group="i3"
+^done,inferior="i3"
@end smallexample
@subheading The @code{-interpreter-exec} Command
started with the @code{set data-directory} command, the file will not be
reread.
+@menu
+* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
+@end menu
+
+@node System-wide Configuration Scripts
+@subsection Installed System-wide Configuration Scripts
+@cindex system-wide configuration scripts
+
+The @file{system-gdbinit} directory, located inside the data-directory
+(as specified by @option{--with-gdb-datadir} at configure time) contains
+a number of scripts which can be used as system-wide init files. To
+automatically source those scripts at startup, @value{GDBN} should be
+configured with @option{--with-system-gdbinit}. Otherwise, any user
+should be able to source them by hand as needed.
+
+The following scripts are currently available:
+@itemize @bullet
+
+@item @file{elinos.py}
+@pindex elinos.py
+@cindex ELinOS system-wide configuration script
+This script is useful when debugging a program on an ELinOS target.
+It takes advantage of the environment variables defined in a standard
+ELinOS environment in order to determine the location of the system
+shared libraries, and then sets the @samp{solib-absolute-prefix}
+and @samp{solib-search-path} variables appropriately.
+
+@item @file{wrs-linux.py}
+@pindex wrs-linux.py
+@cindex Wind River Linux system-wide configuration script
+This script is useful when debugging a program on a target running
+Wind River Linux. It expects the @env{ENV_PREFIX} to be set to
+the host-side sysroot used by the target system.
+
+@end itemize
+
@node Maintenance Commands
@appendix Maintenance Commands
@cindex maintenance commands
architecture supports displaced stepping.
@end table
+@kindex maint check-psymtabs
+@item maint check-psymtabs
+Check the consistency of currently expanded psymtabs versus symtabs.
+Use this to check, for example, whether a symbol is in one but not the other.
+
@kindex maint check-symtabs
@item maint check-symtabs
-Check the consistency of psymtabs and symtabs.
+Check the consistency of currently expanded symtabs.
+
+@kindex maint expand-symtabs
+@item maint expand-symtabs [@var{regexp}]
+Expand symbol tables.
+If @var{regexp} is specified, only expand symbol tables for file
+names matching @var{regexp}.
@kindex maint cplus first_component
@item maint cplus first_component @var{name}
to user; the command @code{maint print register-groups} includes the
groups that each register is a member of; and the command @code{maint
print remote-registers} includes the remote target's register numbers
-and offsets in the `G' packets. @xref{Registers,, Registers, gdbint,
-@value{GDBN} Internals}.
+and offsets in the `G' packets.
These commands take an optional parameter, a file name to which to
write the information.
@kindex maint print objfiles
@cindex info for known object files
-@item maint print objfiles
-Print a dump of all known object files. For each object file, this
-command prints its name, address in memory, and all of its psymtabs
-and symtabs.
+@item maint print objfiles @r{[}@var{regexp}@r{]}
+Print a dump of all known object files.
+If @var{regexp} is specified, only print object files whose names
+match @var{regexp}. For each object file, this command prints its name,
+address in memory, and all of its psymtabs and symtabs.
@kindex maint print section-scripts
@cindex info for known .debug_gdb_scripts-loaded scripts
@item maint set show-debug-regs
@itemx maint show show-debug-regs
Control whether to show variables that mirror the hardware debug
-registers. Use @code{ON} to enable, @code{OFF} to disable. If
+registers. Use @code{on} to enable, @code{off} to disable. If
enabled, the debug registers values are shown when @value{GDBN} inserts or
removes a hardware breakpoint or watchpoint, and when the inferior
triggers a hardware-assisted breakpoint or watchpoint.
Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
@item t
Stop.
+@item r @var{start},@var{end}
+Step once, and then keep stepping as long as the thread stops at
+addresses between @var{start} (inclusive) and @var{end} (exclusive).
+The remote stub reports a stop reply when either the thread goes out
+of the range or is stopped due to an unrelated reason, such as hitting
+a breakpoint. @xref{range stepping}.
+
+If the range is empty (@var{start} == @var{end}), then the action
+becomes equivalent to the @samp{s} action. In other words,
+single-step once, and report the stop (even if the stepped instruction
+jumps to @var{start}).
+
+(A stop reply may be sent at any point even if the PC is still within
+the stepping range; for example, it is valid to implement this packet
+in a degenerate way as a single instruction step operation.)
+
@end table
The optional argument @var{addr} normally associated with the
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:libraries-svr4:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+@item @samp{augmented-libraries-svr4-read}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{qXfer:memory-map:read}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:libraries-svr4:read} packet
(@pxref{qXfer svr4 library list read}).
+@item augmented-libraries-svr4-read
+The remote stub understands the augmented form of the
+@samp{qXfer:libraries-svr4:read} packet
+(@pxref{qXfer svr4 library list read}).
+
@item qXfer:memory-map:read
The remote stub understands the @samp{qXfer:memory-map:read} packet
(@pxref{qXfer memory map read}).
@anchor{qXfer svr4 library list read}
Access the target's list of loaded libraries when the target is an SVR4
platform. @xref{Library List Format for SVR4 Targets}. The annex part
-of the generic @samp{qXfer} packet must be empty (@pxref{qXfer read}).
+of the generic @samp{qXfer} packet must be empty unless the remote
+stub indicated it supports the augmented form of this packet
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qXfer read}, @ref{qSupported}).
This packet is optional for better performance on SVR4 targets.
@value{GDBN} uses memory read packets to read the SVR4 library list otherwise.
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+If the remote stub indicates it supports the augmented form of this
+packet then the annex part of the generic @samp{qXfer} packet may
+contain a semicolon-separated list of @samp{@var{name}=@var{value}}
+arguments. The currently supported arguments are:
+
+@table @code
+@item start=@var{address}
+A hexadecimal number specifying the address of the @samp{struct
+link_map} to start reading the library list from. If unset or zero
+then the first @samp{struct link_map} in the library list will be
+chosen as the starting point.
+
+@item prev=@var{address}
+A hexadecimal number specifying the address of the @samp{struct
+link_map} immediately preceding the @samp{struct link_map}
+specified by the @samp{start} argument. If unset or zero then
+the remote stub will expect that no @samp{struct link_map}
+exists prior to the starting point.
+
+@end table
+
+Arguments that are not understood by the remote stub will be silently
+ignored.
+
@item qXfer:memory-map:read::@var{offset},@var{length}
@anchor{qXfer memory map read}
Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The
<memory start="@var{addr}" length="@var{length}"/>
@end smallexample
+@item
+A block indicating trace state variable numbered @var{number} has been
+collected:
+
+@smallexample
+<tvar id="@var{number}"/>
+@end smallexample
+
@end itemize
The formal DTD for the traceframe info format is given below:
@smallexample
-<!ELEMENT traceframe-info (memory)* >
+<!ELEMENT traceframe-info (memory | tvar)* >
<!ATTLIST traceframe-info version CDATA #FIXED "1.0">
<!ELEMENT memory EMPTY>
<!ATTLIST memory start CDATA #REQUIRED
length CDATA #REQUIRED>
+<!ELEMENT tvar>
+<!ATTLIST tvar id CDATA #REQUIRED>
@end smallexample
@node Branch Trace Format
* i386 Features::
* MIPS Features::
* M68K Features::
+* Nios II Features::
* PowerPC Features::
+* S/390 and System z Features::
* TIC6x Features::
@end menu
@samp{ymm0h} through @samp{ymm15h} for amd64
@end itemize
+The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel(R)
+Memory Protection Extension (MPX). It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{bnd0raw} through @samp{bnd3raw} for i386 and amd64.
+@item
+@samp{bndcfgu} and @samp{bndstatus} for i386 and amd64.
+@end itemize
+
The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
describe a single register, @samp{orig_eax}.
@samp{fpiaddr}.
@end table
+@node Nios II Features
+@subsection Nios II Features
+@cindex target descriptions, Nios II features
+
+The @samp{org.gnu.gdb.nios2.cpu} feature is required for Nios II
+targets. It should contain the 32 core registers (@samp{zero},
+@samp{at}, @samp{r2} through @samp{r23}, @samp{et} through @samp{ra}),
+@samp{pc}, and the 16 control registers (@samp{status} through
+@samp{mpuacc}).
+
@node PowerPC Features
@subsection PowerPC Features
@cindex target descriptions, PowerPC features
these to present registers @samp{ev0} through @samp{ev31} to the
user.
+@node S/390 and System z Features
+@subsection S/390 and System z Features
+@cindex target descriptions, S/390 features
+@cindex target descriptions, System z features
+
+The @samp{org.gnu.gdb.s390.core} feature is required for S/390 and
+System z targets. It should contain the PSW and the 16 general
+registers. In particular, System z targets should provide the 64-bit
+registers @samp{pswm}, @samp{pswa}, and @samp{r0} through @samp{r15}.
+S/390 targets should provide the 32-bit versions of these registers.
+A System z target that runs in 31-bit addressing mode should provide
+32-bit versions of @samp{pswm} and @samp{pswa}, as well as the general
+register's upper halves @samp{r0h} through @samp{r15h}, and their
+lower halves @samp{r0l} through @samp{r15l}.
+
+The @samp{org.gnu.gdb.s390.fpr} feature is required. It should
+contain the 64-bit registers @samp{f0} through @samp{f15}, and
+@samp{fpc}.
+
+The @samp{org.gnu.gdb.s390.acr} feature is required. It should
+contain the 32-bit registers @samp{acr0} through @samp{acr15}.
+
+The @samp{org.gnu.gdb.s390.linux} feature is optional. It should
+contain the register @samp{orig_r2}, which is 64-bit wide on System z
+targets and 32-bit otherwise. In addition, the feature may contain
+the @samp{last_break} register, whose width depends on the addressing
+mode, as well as the @samp{system_call} register, which is always
+32-bit wide.
+
+The @samp{org.gnu.gdb.s390.tdb} feature is optional. It should
+contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct},
+@samp{atia}, and @samp{tr0} through @samp{tr15}.
+
@node TIC6x Features
@subsection TMS320C6x Features
@cindex target descriptions, TIC6x features
projects / thirdparty / binutils-gdb.git / blobdiff