@c of @set vars. However, you can override filename with makeinfo -o.
@setfilename gdb.info
@c
+@c man begin INCLUDE
@include gdb-cfg.texi
+@c man end
@c
@settitle Debugging with @value{GDBN}
@setchapternewpage odd
@c readline appendices use @vindex, @findex and @ftable,
@c annotate.texi and gdbmi use @findex.
@syncodeindex vr fn
-@syncodeindex fn fn
@c !!set GDB manual's edition---not the same as GDB version!
@c This is updated by GNU Press.
@end direntry
@copying
+@c man begin COPYRIGHT
Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
+@c man end
@end copying
@ifnottex
the operating system
* Trace File Format:: GDB trace file format
* Index Section Format:: .gdb_index section format
+* Man Pages:: Manual pages
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
This option causes @value{GDBN} to print its version number and
no-warranty blurb, and exit.
+@item -configuration
+@cindex @code{--configuration}
+This option causes @value{GDBN} to print details about its build-time
+configuration parameters, and then exit. These details can be
+important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}).
+
@end table
@node Startup
@end table
@c @end group
-Here are three miscellaneous @code{show} subcommands, all of which are
+Here are several miscellaneous @code{show} subcommands, all of which are
exceptional in lacking corresponding @code{set} commands:
@table @code
Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
if your version of @value{GDBN} comes with one.
+@kindex show configuration
+@item show configuration
+Display detailed information about the way @value{GDBN} was configured
+when it was built. This displays the optional arguments passed to the
+@file{configure} script and also configuration parameters detected
+automatically by @command{configure}. When reporting a @value{GDBN}
+bug (@pxref{GDB Bugs}), it is important to include this information in
+your report.
+
@end table
@node Running
@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{]}
@cindex stop on C@t{++} exceptions
-The throwing of a C@t{++} exception.
+The throwing, re-throwing, or catching of a C@t{++} exception.
-@item catch
-The 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
+You cannot install an exception handler interactively.
+@end itemize
@item exception
@cindex Ada exception catching
given, then the catchpoint will stop only if the regular expression
matches one of the affected libraries.
-@end table
+@item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
+The delivery of a signal.
-@item tcatch @var{event}
-Set a catchpoint that is enabled only for one stop. The catchpoint is
-automatically deleted after the first time the event is caught.
-
-@end table
-
-Use the @code{info break} command to list the current catchpoints.
+With no arguments, this catchpoint will catch any signal that is not
+used internally by @value{GDBN}, specifically, all signals except
+@samp{SIGTRAP} and @samp{SIGINT}.
-There are currently some limitations to C@t{++} exception handling
-(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
+With the argument @samp{all}, all signals, including those used by
+@value{GDBN}, will be caught. This argument cannot be used with other
+signal names.
-@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.
+Otherwise, the arguments are a list of signal names as given to
+@code{handle} (@pxref{Signals}). Only signals specified in this list
+will be caught.
-@item
-You cannot raise an exception interactively.
+One reason that @code{catch signal} can be more useful than
+@code{handle} is that you can attach commands and conditions to the
+catchpoint.
-@item
-You cannot install an exception handler interactively.
-@end itemize
+When a signal is caught by a catchpoint, the signal's @code{stop} and
+@code{print} settings, as specified by @code{handle}, are ignored.
+However, whether the signal is still delivered to the inferior depends
+on the @code{pass} setting; this can be changed in the catchpoint's
+commands.
-@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.
+@end table
-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:
+@item tcatch @var{event}
+Set a catchpoint that is enabled only for one stop. The catchpoint is
+automatically deleted after the first time the event is caught.
-@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
+@end table
-@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.
+Use the @code{info break} command to list the current catchpoints.
@node Delete Breaks
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
@code{info handle} is an alias for @code{info signals}.
+@item catch signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
+Set a catchpoint for the indicated signals. @xref{Set Catchpoints},
+for details about this command.
+
@kindex handle
@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
@table @code
@kindex target record
+@kindex target record-full
+@kindex target record-btrace
@kindex record
+@kindex record full
+@kindex record btrace
@kindex rec
-@item target record
-This command starts the process record and replay target. The process
-record and replay target can only debug a process that is already
-running. Therefore, you need first to start the process with the
-@kbd{run} or @kbd{start} commands, and then start the recording with
-the @kbd{target record} command.
+@kindex rec full
+@kindex rec btrace
+@item record @var{method}
+This command starts the process record and replay target. The
+recording method can be specified as parameter. Without a parameter
+the command uses the @code{full} recording method. The following
+recording methods are available:
+
+@table @code
+@item full
+Full record/replay recording using @value{GDBN}'s software record and
+replay implementation. This method allows replaying and reverse
+execution.
+
+@item btrace
+Hardware-supported instruction recording. This method does not allow
+replaying and reverse execution.
+
+This recording method may not be available on all processors.
+@end table
+
+The process record and replay target can only debug a process that is
+already running. Therefore, you need first to start the process with
+the @kbd{run} or @kbd{start} commands, and then start the recording
+with the @kbd{record @var{method}} command.
-Both @code{record} and @code{rec} are aliases of @code{target record}.
+Both @code{record @var{method}} and @code{rec @var{method}} are
+aliases of @code{target record-@var{method}}.
@cindex displaced stepping, and process record and replay
Displaced stepping (@pxref{Maintenance Commands,, displaced stepping})
@cindex non-stop mode, and process record and replay
@cindex asynchronous execution, and process record and replay
If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in
-the asynchronous execution mode (@pxref{Background Execution}), the
-process record and replay target cannot be started because it doesn't
-support these two modes.
+the asynchronous execution mode (@pxref{Background Execution}), not
+all recording methods are available. The @code{full} recording method
+does not support these two modes.
@kindex record stop
@kindex rec s
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}}.
Default filename is @file{gdb_record.@var{process_id}}, where
@var{process_id} is the process ID of the inferior.
+This command may not be available for all recording methods.
+
@kindex record restore
@item record restore @var{filename}
Restore the execution log from a file @file{@var{filename}}.
File must have been created with @code{record save}.
-@kindex set record insn-number-max
-@item set record insn-number-max @var{limit}
-Set the limit of instructions to be recorded. Default value is 200000.
+@kindex set record full
+@item set record full insn-number-max @var{limit}
+@itemx set record full insn-number-max unlimited
+Set the limit of instructions to be recorded for the @code{full}
+recording method. Default value is 200000.
If @var{limit} is a positive number, then @value{GDBN} will start
deleting instructions from the log once the number of the record
lets you control what happens when the limit is reached, by means of
the @code{stop-at-limit} option, described below.)
-If @var{limit} is zero, @value{GDBN} will never delete recorded
-instructions from the execution log. The number of recorded
-instructions is unlimited in this case.
+If @var{limit} is @code{unlimited} or zero, @value{GDBN} will never
+delete recorded instructions from the execution log. The number of
+recorded instructions is limited only by the available memory.
-@kindex show record insn-number-max
-@item show record insn-number-max
-Show the limit of instructions to be recorded.
+@kindex show record full
+@item show record full insn-number-max
+Show the limit of instructions to be recorded with the @code{full}
+recording method.
-@kindex set record stop-at-limit
-@item set record stop-at-limit
-Control the behavior when the number of recorded instructions reaches
-the limit. If ON (the default), @value{GDBN} will stop when the limit
-is reached for the first time and ask you whether you want to stop the
-inferior or continue running it and recording the execution log. If
-you decide to continue recording, each new recorded instruction will
-cause the oldest one to be deleted.
+@item set record full stop-at-limit
+Control the behavior of the @code{full} recording method when the
+number of recorded instructions reaches the limit. If ON (the
+default), @value{GDBN} will stop when the limit is reached for the
+first time and ask you whether you want to stop the inferior or
+continue running it and recording the execution log. If you decide
+to continue recording, each new recorded instruction will cause the
+oldest one to be deleted.
If this option is OFF, @value{GDBN} will automatically delete the
oldest record to make room for each new one, without asking.
-@kindex show record stop-at-limit
-@item show record stop-at-limit
+@item show record full stop-at-limit
Show the current setting of @code{stop-at-limit}.
-@kindex set record memory-query
-@item set record memory-query
+@item set record full memory-query
Control the behavior when @value{GDBN} is unable to record memory
-changes caused by an instruction. If ON, @value{GDBN} will query
-whether to stop the inferior in that case.
+changes caused by an instruction for the @code{full} recording method.
+If ON, @value{GDBN} will query whether to stop the inferior in that
+case.
If this option is OFF (the default), @value{GDBN} will automatically
ignore the effect of such instructions on memory. Later, when
instruction as not accessible, and it will not affect the replay
results.
-@kindex show record memory-query
-@item show record memory-query
+@item show record full memory-query
Show the current setting of @code{memory-query}.
@kindex info record
@item info record
-Show various statistics about the state of process record and its
-in-memory execution log buffer, including:
+Show various statistics about the recording depending on the recording
+method:
+
+@table @code
+@item full
+For the @code{full} recording method, it shows the state of process
+record and its in-memory execution log buffer, including:
@itemize @bullet
@item
Maximum number of instructions that may be contained in the execution log.
@end itemize
+@item btrace
+For the @code{btrace} recording method, it shows the number of
+instructions that have been recorded and the number of blocks of
+sequential control-flow that is formed by the recorded instructions.
+@end table
+
@kindex record delete
@kindex rec del
@item record delete
subsequent execution log and begin to record a new execution log starting
from the current address. This means you will abandon the previously
recorded ``future'' and begin recording a new ``future''.
+
+@kindex record instruction-history
+@kindex rec instruction-history
+@item record instruction-history
+Disassembles instructions from the recorded execution log. By
+default, ten instructions are disassembled. This can be changed using
+the @code{set record instruction-history-size} command. Instructions
+are printed in execution order. There are several ways to specify
+what part of the execution log to disassemble:
+
+@table @code
+@item record instruction-history @var{insn}
+Disassembles ten instructions starting from instruction number
+@var{insn}.
+
+@item record instruction-history @var{insn}, +/-@var{n}
+Disassembles @var{n} instructions around instruction number
+@var{insn}. If @var{n} is preceded with @code{+}, disassembles
+@var{n} instructions after instruction number @var{insn}. If
+@var{n} is preceded with @code{-}, disassembles @var{n}
+instructions before instruction number @var{insn}.
+
+@item record instruction-history
+Disassembles ten more instructions after the last disassembly.
+
+@item record instruction-history -
+Disassembles ten more instructions before the last disassembly.
+
+@item record instruction-history @var{begin} @var{end}
+Disassembles instructions beginning with instruction number
+@var{begin} until instruction number @var{end}. The instruction
+number @var{end} is not included.
+@end table
+
+This command may not be available for all recording methods.
+
+@kindex set record
+@item set record instruction-history-size @var{size}
+@itemx set record instruction-history-size unlimited
+Define how many instructions to disassemble in the @code{record
+instruction-history} command. The default value is 10.
+A @var{size} of @code{unlimited} means unlimited instructions.
+
+@kindex show record
+@item show record instruction-history-size
+Show how many instructions to disassemble in the @code{record
+instruction-history} command.
+
+@kindex record function-call-history
+@kindex rec function-call-history
+@item record function-call-history
+Prints the execution history at function granularity. It prints one
+line for each sequence of instructions that belong to the same
+function giving the name of that function, the source lines
+for this instruction sequence (if the @code{/l} modifier is
+specified), and the instructions numbers that form the sequence (if
+the @code{/i} modifier is specified).
+
+@smallexample
+(@value{GDBP}) @b{list 1, 10}
+1 void foo (void)
+2 @{
+3 @}
+4
+5 void bar (void)
+6 @{
+7 ...
+8 foo ();
+9 ...
+10 @}
+(@value{GDBP}) @b{record function-call-history /l}
+1 foo.c:6-8 bar
+2 foo.c:2-3 foo
+3 foo.c:9-10 bar
+@end smallexample
+
+By default, ten lines are printed. This can be changed using the
+@code{set record function-call-history-size} command. Functions are
+printed in execution order. There are several ways to specify what
+to print:
+
+@table @code
+@item record function-call-history @var{func}
+Prints ten functions starting from function number @var{func}.
+
+@item record function-call-history @var{func}, +/-@var{n}
+Prints @var{n} functions around function number @var{func}. If
+@var{n} is preceded with @code{+}, prints @var{n} functions after
+function number @var{func}. If @var{n} is preceded with @code{-},
+prints @var{n} functions before function number @var{func}.
+
+@item record function-call-history
+Prints ten more functions after the last ten-line print.
+
+@item record function-call-history -
+Prints ten more functions before the last ten-line print.
+
+@item record function-call-history @var{begin} @var{end}
+Prints functions beginning with function number @var{begin} until
+function number @var{end}. The function number @var{end} is not
+included.
+@end table
+
+This command may not be available for all recording methods.
+
+@item set record function-call-history-size @var{size}
+@itemx set record function-call-history-size unlimited
+Define how many lines to print in the
+@code{record function-call-history} command. The default value is 10.
+A size of @code{unlimited} means unlimited lines.
+
+@item show record function-call-history-size
+Show how many lines to print in the
+@code{record function-call-history} command.
@end table
@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
@item set backtrace limit @var{n}
@itemx set backtrace limit 0
+@itemx set backtrace limit unlimited
@cindex backtrace limit
-Limit the backtrace to @var{n} levels. A value of zero means
-unlimited.
+Limit the backtrace to @var{n} levels. A value of @code{unlimited}
+or zero means unlimited levels.
@item show backtrace limit
Display the current limit on backtrace levels.
@end table
+You can control how file names are displayed.
+
+@table @code
+@item set filename-display
+@itemx set filename-display relative
+@cindex filename-display
+Display file names relative to the compilation directory. This is the default.
+
+@item set filename-display basename
+Display only basename of a filename.
+
+@item set filename-display absolute
+Display an absolute filename.
+
+@item show filename-display
+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
@table @code
@kindex set listsize
@item set listsize @var{count}
+@itemx set listsize unlimited
Make the @code{list} command display @var{count} source lines (unless
the @code{list} argument explicitly specifies some other number).
-Setting @var{count} to -1 means there's no limit and 0 means suppress
-display of source lines.
+Setting @var{count} to @code{unlimited} or 0 means there's no limit.
@kindex show listsize
@item show listsize
End of assembler dump.
@end smallexample
+Addresses cannot be specified as a linespec (@pxref{Specify Location}).
+So, for example, if you want to disassemble function @code{bar}
+in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar}
+and not @samp{disassemble foo.c:bar}.
+
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
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
@table @code
@item set print max-symbolic-offset @var{max-offset}
+@itemx set print max-symbolic-offset unlimited
@cindex maximum value for offset of closest symbol
Tell @value{GDBN} to only display the symbolic form of an address if the
offset between the closest earlier symbol and the address is less than
-@var{max-offset}. The default is 0, which tells @value{GDBN}
-to always print the symbolic form of an address if any symbol precedes it.
+@var{max-offset}. The default is @code{unlimited}, which tells @value{GDBN}
+to always print the symbolic form of an address if any symbol precedes
+it. Zero is equivalent to @code{unlimited}.
@item show print max-symbolic-offset
Ask how large the maximum offset is that @value{GDBN} prints in a
arrays.
@item set print elements @var{number-of-elements}
+@itemx set print elements unlimited
@cindex number of array elements to print
@cindex limit on number of printed array elements
Set a limit on how many elements of an array @value{GDBN} will print.
printed the number of elements set by the @code{set print elements} command.
This limit also applies to the display of strings.
When @value{GDBN} starts, this limit is set to 200.
-Setting @var{number-of-elements} to zero means that the printing is unlimited.
+Setting @var{number-of-elements} to @code{unlimited} or zero means
+that the number of elements to print is unlimited.
@item show print elements
Display the number of elements of a large array that @value{GDBN} will print.
@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
Show the method being used for printing of frame argument values at function
entry.
-@item set print repeats
+@item set print repeats @var{number-of-repeats}
+@itemx set print repeats unlimited
@cindex repeated array elements
Set the threshold for suppressing display of repeated array
elements. When the number of consecutive identical elements of an
array exceeds the threshold, @value{GDBN} prints the string
@code{"<repeats @var{n} times>"}, where @var{n} is the number of
identical repetitions, instead of displaying the identical elements
-themselves. Setting the threshold to zero will cause all elements to
-be individually printed. The default threshold is 10.
+themselves. Setting the threshold to @code{unlimited} or zero will
+cause all elements to be individually printed. The default threshold
+is 10.
@item show print repeats
Display the current threshold for printing repeated identical
The variable @code{$_exitcode} is automatically set to the exit code when
the program being debugged terminates.
+@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
Arguments to a static probe. @xref{Static Probe Points}.
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
@end table
+@table @code
+@item set trace-buffer-size @var{n}
+@itemx set trace-buffer-size unlimited
+@kindex set trace-buffer-size
+Request that the target use a trace buffer of @var{n} bytes. Not all
+targets will honor the request; they may have a compiled-in size for
+the trace buffer, or some other limitation. Set to a value of
+@code{unlimited} or @code{-1} to let the target use whatever size it
+likes. This is also the default.
+
+@item show trace-buffer-size
+@kindex show trace-buffer-size
+Show the current requested size for the trace buffer. Note that this
+will only match the actual size if the target supports size-setting,
+and was able to handle the requested size. For instance, if the
+target can only change buffer size between runs, this variable will
+not reflect the change until the next run starts. Use @code{tstatus}
+to get a report of the actual buffer size.
+@end table
+
@table @code
@item set trace-user @var{text}
@kindex set trace-user
@kindex tsave
@item tsave [ -r ] @var{filename}
+@itemx tsave [-ctf] @var{dirname}
Save the trace data to @var{filename}. By default, this command
assumes that @var{filename} refers to the host filesystem, so if
necessary @value{GDBN} will copy raw trace data up from the target and
the data directly into @var{filename} in its own filesystem, which may be
more efficient if the trace buffer is very large. (Note, however, that
@code{target tfile} can only read from files accessible to the host.)
+By default, this command will save trace frame in tfile format.
+You can supply the optional argument @code{-ctf} to save date in CTF
+format. The @dfn{Common Trace Format} (CTF) is proposed as a trace format
+that can be shared by multiple debugging and tracing tools. Please go to
+@indicateurl{http://www.efficios.com/ctf} to get more information.
@kindex target tfile
@kindex tfile
+@kindex target ctf
+@kindex ctf
@item target tfile @var{filename}
-Use the file named @var{filename} as a source of trace data. Commands
-that examine data work as they do with a live target, but it is not
-possible to run any new trace experiments. @code{tstatus} will report
-the state of the trace run at the moment the data was saved, as well
-as the current trace frame you are examining. @var{filename} must be
-on a filesystem accessible to the host.
+@itemx target ctf @var{dirname}
+Use the file named @var{filename} or directory named @var{dirname} as
+a source of trace data. Commands that examine data work as they do with
+a live target, but it is not possible to run any new trace experiments.
+@code{tstatus} will report the state of the trace run at the moment
+the data was saved, as well as the current trace frame you are examining.
+@var{filename} or @var{dirname} must be on a filesystem accessible to
+the host.
+
+@smallexample
+(@value{GDBP}) target ctf ctf.ctf
+(@value{GDBP}) tfind
+Found trace frame 0, tracepoint 2
+39 ++a; /* set tracepoint 1 here */
+(@value{GDBP}) tdump
+Data collected at tracepoint 2, trace frame 0:
+i = 0
+a = 0
+b = 1 '\001'
+c = @{"123", "456", "789", "123", "456", "789"@}
+d = @{@{@{a = 1, b = 2@}, @{a = 3, b = 4@}@}, @{@{a = 5, b = 6@}, @{a = 7, b = 8@}@}@}
+(@value{GDBP}) p b
+$1 = 1
+@end smallexample
@end table
@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
@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}
@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.
Use the @code{show gnutarget} command to display what file format
@code{gnutarget} is set to read. If you have not set @code{gnutarget},
@value{GDBN} will determine the file format for each file automatically,
-and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
+and @code{show gnutarget} displays @samp{The current BFD target is "auto"}.
@end table
@cindex common targets
@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.
@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
Show the current auto-retry setting.
@item set tcp connect-timeout @var{seconds}
+@itemx set tcp connect-timeout unlimited
@cindex connection timeout, for remote TCP target
@cindex timeout, for remote target connection
Set the timeout for establishing a TCP connection to the remote target to
@var{seconds}. The timeout affects both polling to retry failed connections
(enabled by @code{set tcp auto-retry on}) and waiting for connections
that are merely slow to complete, and represents an approximate cumulative
-value.
+value. If @var{seconds} is @code{unlimited}, there is no timeout and
+@value{GDBN} will keep attempting to establish a connection forever,
+unless interrupted with @kbd{Ctrl-c}. The default is 15 seconds.
@item show tcp connect-timeout
Show the current connection timeout setting.
@tab @code{qAttached}
@tab Querying remote process attach state.
+@item @code{trace-buffer-size}
+@tab @code{QTBuffer:size}
+@tab @code{set trace-buffer-size}
+
+@item @code{trace-status}
+@tab @code{qTStatus}
+@tab @code{tstatus}
+
@item @code{traceframe-info}
@tab @code{qXfer:traceframe-info:read}
@tab Traceframe info
* M68K:: Motorola M68K
* MicroBlaze:: Xilinx MicroBlaze
* MIPS Embedded:: MIPS Embedded
-* OpenRISC 1000:: OpenRisc 1000
* PowerPC Embedded:: PowerPC Embedded
* PA:: HP PA Embedded
* Sparclet:: Tsqware Sparclet
monitor. The monitor must be in debug mode for this to work.
@end table
-@node OpenRISC 1000
-@subsection OpenRISC 1000
-@cindex OpenRISC 1000
-
-@cindex or1k boards
-See OR1k Architecture document (@uref{www.opencores.org}) for more information
-about platform and commands.
-
-@table @code
-
-@kindex target jtag
-@item target jtag jtag://@var{host}:@var{port}
-
-Connects to remote JTAG server.
-JTAG remote server can be either an or1ksim or JTAG server,
-connected via parallel port to the board.
-
-Example: @code{target jtag jtag://localhost:9999}
-
-@kindex or1ksim
-@item or1ksim @var{command}
-If connected to @code{or1ksim} OpenRISC 1000 Architectural
-Simulator, proprietary commands can be executed.
-
-@kindex info or1k spr
-@item info or1k spr
-Displays spr groups.
-
-@item info or1k spr @var{group}
-@itemx info or1k spr @var{groupno}
-Displays register names in selected group.
-
-@item info or1k spr @var{group} @var{register}
-@itemx info or1k spr @var{register}
-@itemx info or1k spr @var{groupno} @var{registerno}
-@itemx info or1k spr @var{registerno}
-Shows information about specified spr register.
-
-@kindex spr
-@item spr @var{group} @var{register} @var{value}
-@itemx spr @var{register @var{value}}
-@itemx spr @var{groupno} @var{registerno @var{value}}
-@itemx spr @var{registerno @var{value}}
-Writes @var{value} to specified spr register.
-@end table
-
-Some implementations of OpenRISC 1000 Architecture also have hardware trace.
-It is very similar to @value{GDBN} trace, except it does not interfere with normal
-program execution and is thus much faster. Hardware breakpoints/watchpoint
-triggers can be set using:
-@table @code
-@item $LEA/$LDATA
-Load effective address/data
-@item $SEA/$SDATA
-Store effective address/data
-@item $AEA/$ADATA
-Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA)
-@item $FETCH
-Fetch data
-@end table
-
-When triggered, it can capture low level data, like: @code{PC}, @code{LSEA},
-@code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}.
-
-@code{htrace} commands:
-@cindex OpenRISC 1000 htrace
-@table @code
-@kindex hwatch
-@item hwatch @var{conditional}
-Set hardware watchpoint on combination of Load/Store Effective Address(es)
-or Data. For example:
-
-@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
-
-@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
-
-@kindex htrace
-@item htrace info
-Display information about current HW trace configuration.
-
-@item htrace trigger @var{conditional}
-Set starting criteria for HW trace.
-
-@item htrace qualifier @var{conditional}
-Set acquisition qualifier for HW trace.
-
-@item htrace stop @var{conditional}
-Set HW trace stopping criteria.
-
-@item htrace record [@var{data}]*
-Selects the data to be recorded, when qualifier is met and HW trace was
-triggered.
-
-@item htrace enable
-@itemx htrace disable
-Enables/disables the HW trace.
-
-@item htrace rewind [@var{filename}]
-Clears currently recorded trace data.
-
-If filename is specified, new trace file is made and any newly collected data
-will be written there.
-
-@item htrace print [@var{start} [@var{len}]]
-Prints trace buffer, using current record configuration.
-
-@item htrace mode continuous
-Set continuous trace mode.
-
-@item htrace mode suspend
-Set suspend trace mode.
-
-@end table
-
@node PowerPC Embedded
@subsection PowerPC Embedded
all uses of @value{GDBN} with the architecture, both native and cross.
@menu
+* AArch64::
* i386::
* Alpha::
* MIPS::
* HPPA:: HP PA architecture
* SPU:: Cell Broadband Engine SPU architecture
* PowerPC::
+* Nios II::
@end menu
+@node AArch64
+@subsection AArch64
+@cindex AArch64 support
+
+When @value{GDBN} is debugging the AArch64 architecture, it provides the
+following special commands:
+
+@table @code
+@item set debug aarch64
+@kindex set debug aarch64
+This command determines whether AArch64 architecture-specific debugging
+messages are to be displayed.
+
+@item show debug aarch64
+Show whether AArch64 debugging messages are displayed.
+
+@end table
+
@node i386
@subsection x86 Architecture-specific Issues
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}
@kindex set history size
@cindex @env{HISTSIZE}, environment variable
@item set history size @var{size}
+@itemx set history size unlimited
Set the number of commands which @value{GDBN} keeps in its history list.
This defaults to the value of the environment variable
-@code{HISTSIZE}, or to 256 if this variable is not set.
+@code{HISTSIZE}, or to 256 if this variable is not set. If @var{size}
+is @code{unlimited}, the number of commands @value{GDBN} keeps in the
+history list is unlimited.
@end table
History expansion assigns special meaning to the character @kbd{!}.
@kindex show width
@kindex show height
@item set height @var{lpp}
+@itemx set height unlimited
@itemx show height
@itemx set width @var{cpl}
+@itemx set width unlimited
@itemx show width
These @code{set} commands specify a screen height of @var{lpp} lines and
a screen width of @var{cpl} characters. The associated @code{show}
commands display the current settings.
-If you specify a height of zero lines, @value{GDBN} does not pause during
-output no matter how long the output is. This is useful if output is to a
-file or to an editor buffer.
+If you specify a height of either @code{unlimited} or zero lines,
+@value{GDBN} does not pause during output no matter how long the
+output is. This is useful if output is to a file or to an editor
+buffer.
-Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
-from wrapping its output.
+Likewise, you can specify @samp{set width unlimited} or @samp{set
+width 0} to prevent @value{GDBN} from wrapping its output.
@item set pagination on
@itemx set pagination off
@kindex set pagination
Turn the output pagination on or off; the default is on. Turning
-pagination off is the alternative to @code{set height 0}. Note that
+pagination off is the alternative to @code{set height unlimited}. Note that
running @value{GDBN} with the @option{--batch} option (@pxref{Mode
Options, -batch}) also automatically disables pagination.
@cindex OS ABI
@kindex set osabi
@kindex show osabi
+@cindex Newlib OS ABI and its influence on the longjmp handling
One @value{GDBN} configuration can debug binaries for multiple operating
system targets, either via remote debugging or native emulation.
not have the same identifying marks that the standard C library for your
platform provides.
+When @value{GDBN} is debugging the AArch64 architecture, it provides a
+``Newlib'' OS ABI. This is useful for handling @code{setjmp} and
+@code{longjmp} when debugging binaries that use the @sc{newlib} C library.
+The ``Newlib'' OS ABI can be selected by @code{set osabi Newlib}.
+
@table @code
@item show osabi
Show the OS ABI currently in use.
to "$debugdir:$datadir/auto-load".
@end smallexample
+@noindent
+To instruct @value{GDBN} to go ahead and use the init files anyway,
+invoke @value{GDBN} like this:
+
+@smallexample
+$ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb
+@end smallexample
+
The list of trusted directories is controlled by the following commands:
@table @code
Displays the current setting of asynchronous command completion
notification.
@kindex set debug
+@cindex ARM AArch64
+@item set debug aarch64
+Turns on or off display of debugging messages related to ARM AArch64.
+The default is off.
+@kindex show debug
+@item show debug aarch64
+Displays the current state of displaying debugging messages related to
+ARM AArch64.
@cindex gdbarch debugging info
@cindex architecture debugging info
@item set debug arch
Turns on or off display of gdbarch debugging info. The default is off
-@kindex show debug
@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
both ways and display any discrepancies.
@item show debug check-physname
Show the current state of ``physname'' checking.
+@item set debug coff-pe-read
+@cindex COFF/PE exported symbols
+Control display of debugging messages related to reading of COFF/PE
+exported symbols. The default is off.
+@item show debug coff-pe-read
+Displays the current state of displaying debugging messages related to
+reading of COFF/PE exported symbols.
@item set debug dwarf2-die
@cindex DWARF2 DIEs
Dump DWARF2 DIEs after they are read in.
Turns on or off debugging messages from the Linux LWP debug support.
@item show debug lin-lwp
Show the current state of Linux LWP debugging messages.
+@item set debug mach-o
+@cindex Mach-O symbols processing
+Control display of debugging messages related to Mach-O symbols
+processing. The default is off.
+@item show debug mach-o
+Displays the current state of displaying debugging messages related to
+reading of COFF/PE exported symbols.
@item set debug notification
@cindex remote async notification debugging info
Turns on or off debugging messages about remote async notification.
@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.
@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.
* Breakpoints In Python:: Manipulating breakpoints using Python.
* Finish Breakpoints in Python:: Setting Breakpoints on function return
using Python.
* Lazy Strings In Python:: Python representation of lazy strings.
+* Architectures In Python:: Python representation of architectures.
@end menu
@node Basic Python
@subsubsection Basic Python
+@cindex python stdout
+@cindex python pagination
+At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
+@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
+A Python program which outputs to one of these streams may have its
+output interrupted by the user (@pxref{Screen Size}). In this
+situation, a Python @code{KeyboardInterrupt} exception is thrown.
+
+Some care must be taken when writing Python code to run in
+@value{GDBN}. Two things worth noting in particular:
+
+@itemize @bullet
+@item
+@value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
+Python code must not override these, or even change the options using
+@code{sigaction}. If your program changes the handling of these
+signals, @value{GDBN} will most likely stop working correctly. Note
+that it is unfortunately common for GUI toolkits to install a
+@code{SIGCHLD} handler.
+
+@item
+@value{GDBN} takes care to mark its internal file descriptors as
+close-on-exec. However, this cannot be done in a thread-safe way on
+all platforms. Your Python programs should be aware of this and
+should both create new file descriptors with the close-on-exec flag
+set and arrange to close unneeded file descriptors before starting a
+child process.
+@end itemize
+
@cindex python functions
@cindex python module
@cindex gdb module
The following attributes are provided:
-@table @code
@defvar Value.address
If this object is addressable, this read-only attribute holds a
@code{gdb.Value} object representing the address. Otherwise,
fetched when the value is needed, or when the @code{fetch_lazy}
method is invoked.
@end defvar
-@end table
The following methods are provided:
-@table @code
@defun Value.__init__ (@var{val})
Many Python values can be converted directly to a @code{gdb.Value} via
this object initializer. Specifically:
This method does not return a value.
@end defun
-@end table
@node Types In Python
@subsubsection Types In Python
An instance of @code{Type} has the following attributes:
-@table @code
@defvar Type.code
The type code for this type. The type code will be one of the
@code{TYPE_CODE_} constants defined below.
languages have this concept. If this type has no tag name, then
@code{None} is returned.
@end defvar
-@end table
The following methods are provided:
-@table @code
@defun Type.fields ()
For structure and union types, this method returns the fields. Range
types have two fields, the minimum and maximum values. Enum types
If @var{block} is given, then @var{name} is looked up in that scope.
Otherwise, it is searched for globally.
@end defun
-@end table
Each type has a code, which indicates what category this type falls
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
A @code{gdb.Inferior} object has the following attributes:
-@table @code
@defvar Inferior.num
ID of inferior, as assigned by GDB.
@end defvar
Boolean signaling whether the inferior was created using `attach', or
started by @value{GDBN} itself.
@end defvar
-@end table
A @code{gdb.Inferior} object has the following methods:
-@table @code
@defun Inferior.is_valid ()
Returns @code{True} if the @code{gdb.Inferior} object is valid,
@code{False} if not. A @code{gdb.Inferior} object will become invalid
containing the address where the pattern was found, or @code{None} if
the pattern could not be found.
@end defun
-@end table
@node Events In Python
@subsubsection Events In Python
@code{gdb.events} module which dispatches particular events. A registry
provides methods to register and unregister event handlers:
-@table @code
@defun EventRegistry.connect (object)
Add the given callable @var{object} to the registry. This object will be
called when an event corresponding to this registry occurs.
Remove the given @var{object} from the registry. Once removed, the object
will no longer receive notifications of events.
@end defun
-@end table
Here is an example:
Examples of these events are @code{gdb.BreakpointEvent} and
@code{gdb.ContinueEvent}.
-@table @code
@defvar ThreadEvent.inferior_thread
In non-stop mode this attribute will be set to the specific thread which was
involved in the emitted event. Otherwise, it will be set to @code{None}.
@end defvar
-@end table
Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
@item events.exited
Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
@code{events.ExitedEvent} has two attributes:
-@table @code
@defvar ExitedEvent.exit_code
An integer representing the exit code, if available, which the inferior
has returned. (The exit code could be unavailable if, for example,
@defvar ExitedEvent inferior
A reference to the inferior which triggered the @code{exited} event.
@end defvar
-@end table
@item events.stop
Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
This event indicates that the inferior or one of its threads has received as
signal. @code{gdb.SignalEvent} has the following attributes:
-@table @code
@defvar SignalEvent.stop_signal
A string representing the signal received by the inferior. A list of possible
signal values can be obtained by running the command @code{info signals} in
the @value{GDBN} command prompt.
@end defvar
-@end table
Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
@code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
been hit, and has the following attributes:
-@table @code
@defvar BreakpointEvent.breakpoints
A sequence containing references to all the breakpoints (type
@code{gdb.Breakpoint}) that were hit.
This function is maintained for backward compatibility and is now deprecated
in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
@end defvar
-@end table
@item events.new_objfile
Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
-@table @code
@defvar NewObjFileEvent.new_objfile
A reference to the object file (@code{gdb.Objfile}) which has been loaded.
@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
@end defvar
-@end table
@end table
A @code{gdb.InferiorThread} object has the following attributes:
-@table @code
@defvar InferiorThread.name
The name of the thread. If the user specified a name using
@code{thread name}, then this returns that name. Otherwise, if an
Either the LWPID or TID may be 0, which indicates that the operating system
does not use that identifier.
@end defvar
-@end table
A @code{gdb.InferiorThread} object has the following methods:
-@table @code
@defun InferiorThread.is_valid ()
Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
@code{False} if not. A @code{gdb.InferiorThread} object will become
@defun InferiorThread.is_exited ()
Return a Boolean indicating whether the thread is exited.
@end defun
-@end table
@node Commands In Python
@subsubsection Commands In Python
@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 ()
A @code{gdb.Frame} object has the following methods:
-@table @code
@defun Frame.is_valid ()
Returns true if the @code{gdb.Frame} object is valid, false if not.
A frame object can become invalid if the frame it refers to doesn't
obtained.
@end defun
+@defun Frame.architecture ()
+Returns the @code{gdb.Architecture} object corresponding to the frame's
+architecture. @xref{Architectures In Python}.
+@end defun
+
@defun Frame.type ()
Returns the type of the frame. The value can be one of:
@table @code
Set this frame to be the selected frame. @xref{Stack, ,Examining the
Stack}.
@end defun
-@end table
@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:
-@table @code
@defun Block.is_valid ()
Returns @code{True} if the @code{gdb.Block} object is valid,
@code{False} if not. A block object can become invalid if the block it
the time the method is called. The block's validity is also checked
during iteration over symbols of the block.
@end defun
-@end table
A @code{gdb.Block} object has the following attributes:
-@table @code
@defvar Block.start
The start address of the block. This attribute is not writable.
@end defvar
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
@code{True} if the @code{gdb.Block} object is a static block,
@code{False} if not. This attribute is not writable.
@end defvar
-@end table
@node Symbols In Python
@subsubsection Python representation of Symbols.
A @code{gdb.Symbol} object has the following attributes:
-@table @code
@defvar Symbol.type
The type of the symbol or @code{None} if no type is recorded.
This attribute is represented as a @code{gdb.Type} object.
@defvar Symbol.is_variable
@code{True} if the symbol is a variable.
@end defvar
-@end table
A @code{gdb.Symbol} object has the following methods:
-@table @code
@defun Symbol.is_valid ()
Returns @code{True} if the @code{gdb.Symbol} object is valid,
@code{False} if not. A @code{gdb.Symbol} object can become invalid if
given, or if @var{frame} is invalid, then this method will throw an
exception.
@end defun
-@end table
The available domain categories in @code{gdb.Symbol} are represented
as constants in the @code{gdb} module:
A @code{gdb.Symtab_and_line} object has the following attributes:
-@table @code
@defvar Symtab_and_line.symtab
The symbol table object (@code{gdb.Symtab}) for this frame.
This attribute is not writable.
Indicates the current line number for this object. This
attribute is not writable.
@end defvar
-@end table
A @code{gdb.Symtab_and_line} object has the following methods:
-@table @code
@defun Symtab_and_line.is_valid ()
Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
@code{False} if not. A @code{gdb.Symtab_and_line} object can become
@code{gdb.Symtab_and_line} methods will throw an exception if it is
invalid at the time the method is called.
@end defun
-@end table
A @code{gdb.Symtab} object has the following attributes:
-@table @code
@defvar Symtab.filename
The symbol table's source filename. This attribute is not writable.
@end defvar
The symbol table's backing object file. @xref{Objfiles In Python}.
This attribute is not writable.
@end defvar
-@end table
A @code{gdb.Symtab} object has the following methods:
-@table @code
@defun Symtab.is_valid ()
Returns @code{True} if the @code{gdb.Symtab} object is valid,
@code{False} if not. A @code{gdb.Symtab} object can become invalid if
Return the static block of the underlying symbol table.
@xref{Blocks In Python}.
@end defun
-@end table
@node Breakpoints In Python
@subsubsection Manipulating breakpoints using Python
writable.
@end defvar
+@node Architectures In Python
+@subsubsection Python representation of architectures
+@cindex Python architectures
+
+@value{GDBN} uses architecture specific parameters and artifacts in a
+number of its various computations. An architecture is represented
+by an instance of the @code{gdb.Architecture} class.
+
+A @code{gdb.Architecture} class has the following methods:
+
+@defun Architecture.name ()
+Return the name (string value) of the architecture.
+@end defun
+
+@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
+Return a list of disassembled instructions starting from the memory
+address @var{start_pc}. The optional arguments @var{end_pc} and
+@var{count} determine the number of instructions in the returned list.
+If both the optional arguments @var{end_pc} and @var{count} are
+specified, then a list of at most @var{count} disassembled instructions
+whose start address falls in the closed memory address interval from
+@var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
+specified, but @var{count} is specified, then @var{count} number of
+instructions starting from the address @var{start_pc} are returned. If
+@var{count} is not specified but @var{end_pc} is specified, then all
+instructions whose start address falls in the closed memory address
+interval from @var{start_pc} to @var{end_pc} are returned. If neither
+@var{end_pc} nor @var{count} are specified, then a single instruction at
+@var{start_pc} is returned. For all of these cases, each element of the
+returned list is a Python @code{dict} with the following string keys:
+
+@table @code
+
+@item addr
+The value corresponding to this key is a Python long integer capturing
+the memory address of the instruction.
+
+@item asm
+The value corresponding to this key is a string value which represents
+the instruction with assembly language mnemonics. The assembly
+language flavor used is the same as that specified by the current CLI
+variable @code{disassembly-flavor}. @xref{Machine Code}.
+
+@item length
+The value corresponding to this key is the length (integer value) of the
+instruction in bytes.
+
+@end table
+@end defun
+
@node Python Auto-loading
@subsection Python Auto-loading
@cindex Python auto-loading
When 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.
+registering objfile-specific pretty-printers and frame-filters.
@menu
* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
@var{tfnum}. The number of the tracepoint associated with this trace
frame is @var{tpnum}.
-@item =tsv-created,name=@var{name},value=@var{value}
+@item =tsv-created,name=@var{name},initial=@var{initial}
Reports that the new trace state variable @var{name} is created with
-value @var{value}.
+initial value @var{initial}.
@item =tsv-deleted,name=@var{name}
@itemx =tsv-deleted
Reports that the trace state variable @var{name} is deleted or all
trace state variables are deleted.
+@item =tsv-modified,name=@var{name},initial=@var{initial}[,current=@var{current}]
+Reports that the trace state variable @var{name} is modified with
+the initial value @var{initial}. The current value @var{current} of
+trace state variable is optional and is reported if the current
+value of trace state variable is known.
+
@item =breakpoint-created,bkpt=@{...@}
@itemx =breakpoint-modified,bkpt=@{...@}
@itemx =breakpoint-deleted,id=@var{number}
-> -break-insert main
<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
enabled="y",addr="0x08048564",func="main",file="myprog.c",
- fullname="/home/nickrob/myprog.c",line="68",times="0"@}
+ fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
+ times="0"@}
<- (gdb)
@end smallexample
-> -break-insert main
<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
enabled="y",addr="0x08048564",func="main",file="myprog.c",
- fullname="/home/nickrob/myprog.c",line="68",times="0"@}
+ fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
+ times="0"@}
<- (gdb)
@end smallexample
-break-insert main
^done,bkpt=@{number="1",type="breakpoint",disp="keep",
enabled="y",addr="0x000100d0",func="main",file="hello.c",
-fullname="/home/foo/hello.c",line="5",times="0"@}
+fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
+times="0"@}
(gdb)
-break-after 1 3
~
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
-line="5",times="0",ignore="3"@}]@}
+line="5",thread-groups=["i1"],times="0",ignore="3"@}]@}
(gdb)
@end smallexample
-break-insert main
^done,bkpt=@{number="1",type="breakpoint",disp="keep",
enabled="y",addr="0x000100d0",func="main",file="hello.c",
-fullname="/home/foo/hello.c",line="5",times="0"@}
+fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
+times="0"@}
(gdb)
-break-commands 1 "print v" "continue"
^done
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
-line="5",cond="1",times="0",ignore="3"@}]@}
+line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"@}]@}
(gdb)
@end smallexample
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
-line="5",times="0"@}]@}
+line="5",thread-groups=["i1"],times="0"@}]@}
(gdb)
@end smallexample
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
-line="5",times="0"@}]@}
+line="5",thread-groups=["i1"],times="0"@}]@}
(gdb)
@end smallexample
(gdb)
-break-insert main
^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
-fullname="/home/foo/recursive2.c,line="4",times="0"@}
+fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"],
+times="0"@}
(gdb)
-break-insert -t foo
^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
-fullname="/home/foo/recursive2.c,line="11",times="0"@}
+fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"],
+times="0"@}
(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x0001072c", func="main",file="recursive2.c",
-fullname="/home/foo/recursive2.c,"line="4",times="0"@},
+fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"],
+times="0"@},
bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
addr="0x00010774",func="foo",file="recursive2.c",
-fullname="/home/foo/recursive2.c",line="11",times="0"@}]@}
+fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
+times="0"@}]@}
(gdb)
@c -break-insert -r foo.*
@c ~int foo(int, int);
@c ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
-@c "fullname="/home/foo/recursive2.c",line="11",times="0"@}
+@c "fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
+@c times="0"@}
@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
@item What
logical location of the breakpoint, expressed by function name, file
name, line number
+@item Thread-groups
+list of thread groups to which this breakpoint applies
@item Times
number of times the breakpoint has been hit
@end table
@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
@{width="40",alignment="2",col_name="what",colhdr="What"@}],
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
-addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
+addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"],
+times="0"@},
bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
-line="13",times="0"@}]@}
+line="13",thread-groups=["i1"],times="0"@}]@}
(gdb)
@end smallexample
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"@},
+fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"],
+times="1"@},
bkpt=@{number="2",type="watchpoint",disp="keep",
-enabled="y",addr="",what="C",times="0"@}]@}
+enabled="y",addr="",what="C",thread-groups=["i1"],times="0"@}]@}
(gdb)
-exec-continue
^running
body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
+fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"],
+times="1"@},
bkpt=@{number="2",type="watchpoint",disp="keep",
-enabled="y",addr="",what="C",times="-5"@}]@}
+enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"@}]@}
(gdb)
-exec-continue
^running
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
-times="1"@}]@}
+thread-groups=["i1"],times="1"@}]@}
(gdb)
@end smallexample
@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
@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
tracing will continue after @value{GDBN} disconnects, @code{0} means
that the trace run will stop.
+@item trace-file
+The filename of the trace file being examined. This field is
+optional, and only present when examining a trace file.
+
@end table
@subsubheading @value{GDBN} Command
Example output:
@smallexample
-(gdb) -list-features
+(gdb) -list-target-features
^done,result=["async"]
@end smallexample
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
-break-insert main
^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x080484ed",func="main",file="myprog.c",
-fullname="/home/nickrob/myprog.c",line="73",times="0"@},
+fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"],
+times="0"@},
time=@{wallclock="0.05185",user="0.00800",system="0.00000"@}
(gdb)
-enable-timings no
and @code{jit-reader-unload} commands.
@table @code
-@item jit-reader-load @var{reader-name}
-Load the JIT reader named @var{reader-name}. On a UNIX system, this
-will usually load @file{@var{libdir}/gdb/@var{reader-name}}, where
-@var{libdir} is the system library directory, usually
-@file{/usr/local/lib}. Only one reader can be active at a time;
-trying to load a second reader when one is already loaded will result
-in @value{GDBN} reporting an error. A new JIT reader can be loaded by
-first unloading the current one using @code{jit-reader-load} and then
-invoking @code{jit-reader-load}.
+@item jit-reader-load @var{reader}
+Load the JIT reader named @var{reader}. @var{reader} is a shared
+object specified as either an absolute or a relative file name. In
+the latter case, @value{GDBN} will try to load the reader from a
+pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX
+system (here @var{libdir} is the system library directory, often
+@file{/usr/local/lib}).
+
+Only one reader can be active at a time; trying to load a second
+reader when one is already loaded will result in @value{GDBN}
+reporting an error. A new JIT reader can be loaded by first unloading
+the current one using @code{jit-reader-unload} and then invoking
+@code{jit-reader-load}.
@item jit-reader-unload
Unload the currently loaded JIT reader.
The type of machine you are using, and the operating system name and
version number.
+@item
+The details of the @value{GDBN} build-time configuration.
+@value{GDBN} shows these details if you invoke it with the
+@option{--configuration} command-line option, or if you type
+@code{show configuration} at @value{GDBN}'s prompt.
+
@item
What compiler (and its version) was used to compile @value{GDBN}---e.g.@:
``@value{GCC}--2.8.1''.
MS-Windows shared libraries (@pxref{Shared Libraries})
@item
Traceframe info (@pxref{Traceframe Info Format})
+@item
+Branch trace (@pxref{Branch Trace Format})
@end itemize
@item zlib
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
Translate the given format string and list of argument expressions
into remote agent bytecodes and display them as a disassembled list.
This command is useful for debugging the agent version of dynamic
-printf (@pxref{Dynamic Printf}.
+printf (@pxref{Dynamic Printf}).
@kindex maint info breakpoints
@item @anchor{maint info breakpoints}maint info breakpoints
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
at thread local base, when using the @samp{info w32 thread-information-block}
command.
-@kindex maint space
-@cindex memory used by commands
-@item maint space
-Control whether to display memory usage for each command. If set to a
-nonzero value, @value{GDBN} will display how much memory each command
-took, following the command's own output. This can also be requested
-by invoking @value{GDBN} with the @option{--statistics} command-line
-switch (@pxref{Mode Options}).
+@kindex maint set per-command
+@kindex maint show per-command
+@item maint set per-command
+@itemx maint show per-command
+@cindex resources used by commands
-@kindex maint time
-@cindex time of command execution
-@item maint time
-Control whether to display the execution time of @value{GDBN} for each command.
-If set to a nonzero value, @value{GDBN} will display how much time it
+@value{GDBN} can display the resources used by each command.
+This is useful in debugging performance problems.
+
+@table @code
+@item maint set per-command space [on|off]
+@itemx maint show per-command space
+Enable or disable the printing of the memory used by GDB for each command.
+If enabled, @value{GDBN} will display how much memory each command
+took, following the command's own output.
+This can also be requested by invoking @value{GDBN} with the
+@option{--statistics} command-line switch (@pxref{Mode Options}).
+
+@item maint set per-command time [on|off]
+@itemx maint show per-command time
+Enable or disable the printing of the execution time of @value{GDBN}
+for each command.
+If enabled, @value{GDBN} will display how much time it
took to execute each command, following the command's own output.
Both CPU time and wallclock time are printed.
Printing both is useful when trying to determine whether the cost is
-CPU or, e.g., disk/network, latency.
+CPU or, e.g., disk/network latency.
Note that the CPU time printed is for @value{GDBN} only, it does not include
the execution time of the inferior because there's no mechanism currently
to compute how much time was spent by @value{GDBN} and how much time was
This can also be requested by invoking @value{GDBN} with the
@option{--statistics} command-line switch (@pxref{Mode Options}).
+@item maint set per-command symtab [on|off]
+@itemx maint show per-command symtab
+Enable or disable the printing of basic symbol table statistics
+for each command.
+If enabled, @value{GDBN} will display the following information:
+
+@enumerate a
+@item
+number of symbol tables
+@item
+number of primary symbol tables
+@item
+number of blocks in the blockvector
+@end enumerate
+@end table
+
+@kindex maint space
+@cindex memory used by commands
+@item maint space @var{value}
+An alias for @code{maint set per-command space}.
+A non-zero value enables it, zero disables it.
+
+@kindex maint time
+@cindex time of command execution
+@item maint time @var{value}
+An alias for @code{maint set per-command time}.
+A non-zero value enables it, zero disables it.
+
@kindex maint translate-address
@item maint translate-address @r{[}@var{section}@r{]} @var{addr}
Find the symbol stored at the location specified by the address
* Memory Map Format::
* Thread List Format::
* Traceframe Info Format::
+* Branch Trace Format::
@end menu
@node Overview
the register's value
@item E @var{NN}
for an error
-@item
+@item @w{}
Indicating an unrecognized @var{query}.
@end table
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
@item vCont@r{[};@var{action}@dots{}@r{]}
The @samp{vCont} packet is supported. Each @var{action} is a supported
command in the @samp{vCont} packet.
-@item
+@item @w{}
The @samp{vCont} packet is not supported.
@end table
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{QDisableRandomization} is not supported
by the stub.
@end table
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
@end table
An error occured. This means that either the thread was not found, or the
address could not be retrieved.
-@item
+@item @w{}
An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub.
@end table
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{QNonStop} is not supported by
the stub.
@end table
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{QPassSignals} is not supported by
the stub.
@end table
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{QProgramSignals} is not supported
by the stub.
@end table
A command response with the hex encoded output string @var{OUTPUT}.
@item E @var{NN}
Indicate a badly formed request.
-@item
+@item @w{}
An empty reply indicates that @samp{qRcmd} is not recognized.
@end table
@item qSearch:memory:@var{address};@var{length};@var{search-pattern}
@cindex searching memory, in remote debugging
+@ifnotinfo
@cindex @samp{qSearch:memory} packet
+@end ifnotinfo
+@cindex @samp{qSearch memory} packet
@anchor{qSearch memory}
Search @var{length} bytes at @var{address} for @var{search-pattern}.
@var{address} and @var{length} are encoded in hex.
The pattern was found at @var{address}.
@item E @var{NN}
A badly formed request or an error was encountered while searching memory.
-@item
+@item @w{}
An empty reply indicates that @samp{qSearch:memory} is not recognized.
@end table
@value{GDBN} acknowledges this reponse,
but neither the stub nor @value{GDBN} shall send or expect further
@samp{+}/@samp{-} acknowledgments in the current connection.
-@item
+@item @w{}
An empty reply indicates that the stub does not support no-acknowledgment mode.
@end table
The stub supports or does not support each returned @var{stubfeature},
depending on the form of each @var{stubfeature} (see below for the
possible forms).
-@item
+@item @w{}
An empty reply indicates that @samp{qSupported} is not recognized,
or that no features needed to be reported to @value{GDBN}.
@end table
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:btrace:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:features:read}
@tab No
@tab @samp{-}
@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{-}
@tab @samp{-}
@tab Yes
+@item @samp{Qbtrace:off}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
+@item @samp{Qbtrace:bts}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
@item @samp{QNonStop}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{QTBuffer:size}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{tracenz}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:auxv:read} packet
(@pxref{qXfer auxiliary vector read}).
+@item qXfer:btrace:read
+The remote stub understands the @samp{qXfer:btrace:read}
+packet (@pxref{qXfer btrace read}).
+
@item qXfer:features:read
The remote stub understands the @samp{qXfer:features:read} packet
(@pxref{qXfer target description read}).
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}).
@samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints
to be enabled and disabled while a trace experiment is running.
+@item QTBuffer:size
+The remote stub supports the @samp{QTBuffer:size} (@pxref{QTBuffer-size})
+packet that allows to change the size of the trace buffer.
+
@item tracenz
@cindex string tracing, in remote protocol
The remote stub supports the @samp{tracenz} bytecode for collecting strings.
The remote stub supports running a breakpoint's command list itself,
rather than reporting the hit to @value{GDBN}.
+@item Qbtrace:off
+The remote stub understands the @samp{Qbtrace:off} packet.
+
+@item Qbtrace:bts
+The remote stub understands the @samp{Qbtrace:bts} packet.
+
@end table
@item qSymbol::
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:btrace:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer btrace read}
+
+Return a description of the current branch trace.
+@xref{Branch Trace Format}. The annex part of the generic @samp{qXfer}
+packet may have one of the following values:
+
+@table @code
+@item all
+Returns all available branch trace.
+
+@item new
+Returns all available branch trace if the branch trace changed since
+the last read request.
+@end table
+
+This packet is not probed by default; the remote stub must request it
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:features:read:@var{annex}:@var{offset},@var{length}
@anchor{qXfer target description read}
Access the @dfn{target description}. @xref{Target Descriptions}. The
@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
The offset was invalid, or there was an error encountered reading the data.
@var{nn} is a hex-encoded @code{errno} value.
-@item
+@item @w{}
An empty reply indicates the @var{object} string was not recognized by
the stub, or that the object does not support reading.
@end table
The offset was invalid, or there was an error encountered writing the data.
@var{nn} is a hex-encoded @code{errno} value.
-@item
+@item @w{}
An empty reply indicates the @var{object} string was not
recognized by the stub, or that the object does not support writing.
@end table
A badly formed request or an error was encountered.
@end table
+@item Qbtrace:bts
+Enable branch tracing for the current thread using bts tracing.
+
+Reply:
+@table @samp
+@item OK
+Branch tracing has been enabled.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
+@item Qbtrace:off
+Disable branch tracing for the current thread.
+
+Reply:
+@table @samp
+@item OK
+Branch tracing has been disabled.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
@end table
@node Architecture-Specific Protocol Details
The packet was understood and carried out.
@item qRelocInsn
@xref{Tracepoint Packets,,Relocate instruction reply packet}.
-@item
+@item @w{}
The packet was not recognized.
@end table
The packet was understood and carried out.
@item qRelocInsn
@xref{Tracepoint Packets,,Relocate instruction reply packet}.
-@item
+@item @w{}
The packet was not recognized.
@end table
that a fast tracepoint may be placed on any instruction regardless of size.
@item E
An error has occurred.
-@item
+@item @w{}
An empty reply indicates that the request is not supported by the stub.
@end table
(lower case letter @samp{L}) denotes end of list.
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that the request is not supported by the
stub.
@end table
This packet directs the target to use a circular trace buffer if
@var{value} is 1, or a linear buffer if the value is 0.
+@item QTBuffer:size:@var{size}
+@anchor{QTBuffer-size}
+@cindex @samp{QTBuffer size} packet
+This packet directs the target to make the trace buffer be of size
+@var{size} if possible. A value of @code{-1} tells the target to
+use whatever size it prefers.
+
@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{}
@cindex @samp{QTNotes} packet
This packet adds optional textual notes to the trace run. Allowable
documentation for the interpretation of @var{result} and
@var{attachment}.
-@item
+@item @w{}
An empty response indicates that this operation is not recognized.
@end table
<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
+@section Branch Trace Format
+@cindex branch trace format
+
+In order to display the branch trace of an inferior thread,
+@value{GDBN} needs to obtain the list of branches. This list is
+represented as list of sequential code blocks that are connected via
+branches. The code in each block has been executed sequentially.
+
+This list is obtained using the @samp{qXfer:btrace:read}
+(@pxref{qXfer btrace read}) packet and is an XML document.
+
+@value{GDBN} must be linked with the Expat library to support XML
+traceframe info discovery. @xref{Expat}.
+
+The top-level structure of the document is shown below:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE btrace
+ PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
+ "http://sourceware.org/gdb/gdb-btrace.dtd">
+<btrace>
+ block...
+</btrace>
+@end smallexample
+
+@itemize
+
+@item
+A block of sequentially executed instructions starting at @var{begin}
+and ending at @var{end}:
+
+@smallexample
+<block begin="@var{begin}" end="@var{end}"/>
+@end smallexample
+
+@end itemize
+
+The formal DTD for the branch trace format is given below:
+
+@smallexample
+<!ELEMENT btrace (block)* >
+<!ATTLIST btrace version CDATA #FIXED "1.0">
+
+<!ELEMENT block EMPTY>
+<!ATTLIST block begin CDATA #REQUIRED
+ end CDATA #REQUIRED>
@end smallexample
@include agentexpr.texi
registers using the capitalization used in the description.
@menu
+* AArch64 Features::
* ARM Features::
* i386 Features::
* MIPS Features::
* M68K Features::
+* Nios II Features::
* PowerPC Features::
+* S/390 and System z Features::
* TIC6x Features::
@end menu
+@node AArch64 Features
+@subsection AArch64 Features
+@cindex target descriptions, AArch64 features
+
+The @samp{org.gnu.gdb.aarch64.core} feature is required for AArch64
+targets. It should contain registers @samp{x0} through @samp{x30},
+@samp{sp}, @samp{pc}, and @samp{cpsr}.
+
+The @samp{org.gnu.gdb.aarch64.fpu} feature is optional. If present,
+it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr},
+and @samp{fpcr}.
+
@node ARM Features
@subsection ARM Features
@cindex target descriptions, ARM features
@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
@enumerate
@item
-The version number, currently 7. Versions 1, 2 and 3 are obsolete.
+The version number, currently 8. Versions 1, 2 and 3 are obsolete.
Version 4 uses a different hashing function from versions 5 and 6.
Version 6 includes symbols for inlined functions, whereas versions 4
and 5 do not. Version 7 adds attributes to the CU indices in the
-symbol table. @value{GDBN} will only read version 4, 5, or 6 indices
+symbol table. Version 8 specifies that symbols from DWARF type units
+(@samp{DW_TAG_type_unit}) refer to the type unit's symbol table and not the
+compilation unit (@samp{DW_TAG_comp_unit}) using the type.
+
+@value{GDBN} will only read version 4, 5, or 6 indices
by specifying @code{set use-deprecated-index-sections on}.
+GDB has a workaround for potentially broken version 7 indices so it is
+currently not flagged as deprecated.
@item
The offset, from the start of the file, of the CU list.
@}
@end smallexample
+@node Man Pages
+@appendix Manual pages
+@cindex Man pages
+
+@menu
+* gdb man:: The GNU Debugger man page
+* gdbserver man:: Remote Server for the GNU Debugger man page
+* gcore man:: Generate a core file of a running program
+* gdbinit man:: gdbinit scripts
+@end menu
+
+@node gdb man
+@heading gdb man
+
+@c man title gdb The GNU Debugger
+
+@c man begin SYNOPSIS gdb
+gdb [@option{-help}] [@option{-nh}] [@option{-nx}] [@option{-q}]
+[@option{-batch}] [@option{-cd=}@var{dir}] [@option{-f}]
+[@option{-b}@w{ }@var{bps}]
+ [@option{-tty=}@var{dev}] [@option{-s} @var{symfile}]
+[@option{-e}@w{ }@var{prog}] [@option{-se}@w{ }@var{prog}]
+[@option{-c}@w{ }@var{core}] [@option{-p}@w{ }@var{procID}]
+ [@option{-x}@w{ }@var{cmds}] [@option{-d}@w{ }@var{dir}]
+[@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}]
+@c man end
+
+@c man begin DESCRIPTION gdb
+The purpose of a debugger such as @value{GDBN} is to allow you to see what is
+going on ``inside'' another program while it executes -- or what another
+program was doing at the moment it crashed.
+
+@value{GDBN} can do four main kinds of things (plus other things in support of
+these) to help you catch bugs in the act:
+
+@itemize @bullet
+@item
+Start your program, specifying anything that might affect its behavior.
+
+@item
+Make your program stop on specified conditions.
+
+@item
+Examine what has happened, when your program has stopped.
+
+@item
+Change things in your program, so you can experiment with correcting the
+effects of one bug and go on to learn about another.
+@end itemize
+
+You can use @value{GDBN} to debug programs written in C, C@t{++}, Fortran and
+Modula-2.
+
+@value{GDBN} is invoked with the shell command @code{gdb}. Once started, it reads
+commands from the terminal until you tell it to exit with the @value{GDBN}
+command @code{quit}. You can get online help from @value{GDBN} itself
+by using the command @code{help}.
+
+You can run @code{gdb} with no arguments or options; but the most
+usual way to start @value{GDBN} is with one argument or two, specifying an
+executable program as the argument:
+
+@smallexample
+gdb program
+@end smallexample
+
+You can also start with both an executable program and a core file specified:
+
+@smallexample
+gdb program core
+@end smallexample
+
+You can, instead, specify a process ID as a second argument, if you want
+to debug a running process:
+
+@smallexample
+gdb program 1234
+gdb -p 1234
+@end smallexample
+
+@noindent
+would attach @value{GDBN} to process @code{1234} (unless you also have a file
+named @file{1234}; @value{GDBN} does check for a core file first).
+With option @option{-p} you can omit the @var{program} filename.
+
+Here are some of the most frequently needed @value{GDBN} commands:
+
+@c pod2man highlights the right hand side of the @item lines.
+@table @env
+@item break [@var{file}:]@var{functiop}
+Set a breakpoint at @var{function} (in @var{file}).
+
+@item run [@var{arglist}]
+Start your program (with @var{arglist}, if specified).
+
+@item bt
+Backtrace: display the program stack.
+
+@item print @var{expr}
+Display the value of an expression.
+
+@item c
+Continue running your program (after stopping, e.g. at a breakpoint).
+
+@item next
+Execute next program line (after stopping); step @emph{over} any
+function calls in the line.
+
+@item edit [@var{file}:]@var{function}
+look at the program line where it is presently stopped.
+
+@item list [@var{file}:]@var{function}
+type the text of the program in the vicinity of where it is presently stopped.
+
+@item step
+Execute next program line (after stopping); step @emph{into} any
+function calls in the line.
+
+@item help [@var{name}]
+Show information about @value{GDBN} command @var{name}, or general information
+about using @value{GDBN}.
+
+@item quit
+Exit from @value{GDBN}.
+@end table
+
+@ifset man
+For full details on @value{GDBN},
+see @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+by Richard M. Stallman and Roland H. Pesch. The same text is available online
+as the @code{gdb} entry in the @code{info} program.
+@end ifset
+@c man end
+
+@c man begin OPTIONS gdb
+Any arguments other than options specify an executable
+file and core file (or process ID); that is, the first argument
+encountered with no
+associated option flag is equivalent to a @option{-se} option, and the second,
+if any, is equivalent to a @option{-c} option if it's the name of a file.
+Many options have
+both long and short forms; both are shown here. The long forms are also
+recognized if you truncate them, so long as enough of the option is
+present to be unambiguous. (If you prefer, you can flag option
+arguments with @option{+} rather than @option{-}, though we illustrate the
+more usual convention.)
+
+All the options and command line arguments you give are processed
+in sequential order. The order makes a difference when the @option{-x}
+option is used.
+
+@table @env
+@item -help
+@itemx -h
+List all options, with brief explanations.
+
+@item -symbols=@var{file}
+@itemx -s @var{file}
+Read symbol table from file @var{file}.
+
+@item -write
+Enable writing into executable and core files.
+
+@item -exec=@var{file}
+@itemx -e @var{file}
+Use file @var{file} as the executable file to execute when
+appropriate, and for examining pure data in conjunction with a core
+dump.
+
+@item -se=@var{file}
+Read symbol table from file @var{file} and use it as the executable
+file.
+
+@item -core=@var{file}
+@itemx -c @var{file}
+Use file @var{file} as a core dump to examine.
+
+@item -command=@var{file}
+@itemx -x @var{file}
+Execute @value{GDBN} commands from file @var{file}.
+
+@item -ex @var{command}
+Execute given @value{GDBN} @var{command}.
+
+@item -directory=@var{directory}
+@itemx -d @var{directory}
+Add @var{directory} to the path to search for source files.
+
+@item -nh
+Do not execute commands from @file{~/.gdbinit}.
+
+@item -nx
+@itemx -n
+Do not execute commands from any @file{.gdbinit} initialization files.
+
+@item -quiet
+@itemx -q
+``Quiet''. Do not print the introductory and copyright messages. These
+messages are also suppressed in batch mode.
+
+@item -batch
+Run in batch mode. Exit with status @code{0} after processing all the command
+files specified with @option{-x} (and @file{.gdbinit}, if not inhibited).
+Exit with nonzero status if an error occurs in executing the @value{GDBN}
+commands in the command files.
+
+Batch mode may be useful for running @value{GDBN} as a filter, for example to
+download and run a program on another computer; in order to make this
+more useful, the message
+
+@smallexample
+Program exited normally.
+@end smallexample
+
+@noindent
+(which is ordinarily issued whenever a program running under @value{GDBN} control
+terminates) is not issued when running in batch mode.
+
+@item -cd=@var{directory}
+Run @value{GDBN} using @var{directory} as its working directory,
+instead of the current directory.
+
+@item -fullname
+@itemx -f
+Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells
+@value{GDBN} to output the full file name and line number in a standard,
+recognizable fashion each time a stack frame is displayed (which
+includes each time the program stops). This recognizable format looks
+like two @samp{\032} characters, followed by the file name, line number
+and character position separated by colons, and a newline. The
+Emacs-to-@value{GDBN} interface program uses the two @samp{\032}
+characters as a signal to display the source code for the frame.
+
+@item -b @var{bps}
+Set the line speed (baud rate or bits per second) of any serial
+interface used by @value{GDBN} for remote debugging.
+
+@item -tty=@var{device}
+Run using @var{device} for your program's standard input and output.
+@end table
+@c man end
+
+@c man begin SEEALSO gdb
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+@noindent
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
+@node gdbserver man
+@heading gdbserver man
+
+@c man title gdbserver Remote Server for the GNU Debugger
+@format
+@c man begin SYNOPSIS gdbserver
+gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
+
+gdbserver --attach @var{comm} @var{pid}
+
+gdbserver --multi @var{comm}
+@c man end
+@end format
+
+@c man begin DESCRIPTION gdbserver
+@command{gdbserver} is a program that allows you to run @value{GDBN} on a different machine
+than the one which is running the program being debugged.
+
+@ifclear man
+@subheading Usage (server (target) side)
+@end ifclear
+@ifset man
+Usage (server (target) side):
+@end ifset
+
+First, you need to have a copy of the program you want to debug put onto
+the target system. The program can be stripped to save space if needed, as
+@command{gdbserver} doesn't care about symbols. All symbol handling is taken care of by
+the @value{GDBN} running on the host system.
+
+To use the server, you log on to the target system, and run the @command{gdbserver}
+program. You must tell it (a) how to communicate with @value{GDBN}, (b) the name of
+your program, and (c) its arguments. The general syntax is:
+
+@smallexample
+target> gdbserver @var{comm} @var{program} [@var{args} ...]
+@end smallexample
+
+For example, using a serial port, you might say:
+
+@smallexample
+@ifset man
+@c @file would wrap it as F</dev/com1>.
+target> gdbserver /dev/com1 emacs foo.txt
+@end ifset
+@ifclear man
+target> gdbserver @file{/dev/com1} emacs foo.txt
+@end ifclear
+@end smallexample
+
+This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and
+to communicate with @value{GDBN} via @file{/dev/com1}. @command{gdbserver} now
+waits patiently for the host @value{GDBN} to communicate with it.
+
+To use a TCP connection, you could say:
+
+@smallexample
+target> gdbserver host:2345 emacs foo.txt
+@end smallexample
+
+This says pretty much the same thing as the last example, except that we are
+going to communicate with the @code{host} @value{GDBN} via TCP. The @code{host:2345} argument means
+that we are expecting to see a TCP connection from @code{host} to local TCP port
+2345. (Currently, the @code{host} part is ignored.) You can choose any number you
+want for the port number as long as it does not conflict with any existing TCP
+ports on the target system. This same port number must be used in the host
+@value{GDBN}s @code{target remote} command, which will be described shortly. Note that if
+you chose a port number that conflicts with another service, @command{gdbserver} will
+print an error message and exit.
+
+@command{gdbserver} can also attach to running programs.
+This is accomplished via the @option{--attach} argument. The syntax is:
+
+@smallexample
+target> gdbserver --attach @var{comm} @var{pid}
+@end smallexample
+
+@var{pid} is the process ID of a currently running process. It isn't
+necessary to point @command{gdbserver} at a binary for the running process.
+
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use the @option{--multi} command line option.
+In such case you should connect using @kbd{target extended-remote} to start
+the program you want to debug.
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
+@ifclear man
+@subheading Usage (host side)
+@end ifclear
+@ifset man
+Usage (host side):
+@end ifset
+
+You need an unstripped copy of the target program on your host system, since
+@value{GDBN} needs to examine it's symbol tables and such. Start up @value{GDBN} as you normally
+would, with the target program as the first argument. (You may need to use the
+@option{--baud} option if the serial line is running at anything except 9600 baud.)
+That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only
+new command you need to know about is @code{target remote}
+(or @code{target extended-remote}). Its argument is either
+a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT}
+descriptor. For example:
+
+@smallexample
+@ifset man
+@c @file would wrap it as F</dev/ttyb>.
+(gdb) target remote /dev/ttyb
+@end ifset
+@ifclear man
+(gdb) target remote @file{/dev/ttyb}
+@end ifclear
+@end smallexample
+
+@noindent
+communicates with the server via serial line @file{/dev/ttyb}, and:
+
+@smallexample
+(gdb) target remote the-target:2345
+@end smallexample
+
+@noindent
+communicates via a TCP connection to port 2345 on host `the-target', where
+you previously started up @command{gdbserver} with the same port number. Note that for
+TCP connections, you must start up @command{gdbserver} prior to using the `target remote'
+command, otherwise you may get an error that looks something like
+`Connection refused'.
+
+@command{gdbserver} can also debug multiple inferiors at once,
+described in
+@ifset man
+the @value{GDBN} manual in node @code{Inferiors and Programs}
+-- shell command @code{info -f gdb -n 'Inferiors and Programs'}.
+@end ifset
+@ifclear man
+@ref{Inferiors and Programs}.
+@end ifclear
+In such case use the @code{extended-remote} @value{GDBN} command variant:
+
+@smallexample
+(gdb) target extended-remote the-target:2345
+@end smallexample
+
+The @command{gdbserver} option @option{--multi} may or may not be used in such
+case.
+@c man end
+
+@c man begin OPTIONS gdbserver
+There are three different modes for invoking @command{gdbserver}:
+
+@itemize @bullet
+
+@item
+Debug a specific program specified by its program name:
+
+@smallexample
+gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
+@end smallexample
+
+The @var{comm} parameter specifies how should the server communicate
+with @value{GDBN}; it is either a device name (to use a serial line),
+a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use
+stdin/stdout of @code{gdbserver}. Specify the name of the program to
+debug in @var{prog}. Any remaining arguments will be passed to the
+program verbatim. When the program exits, @value{GDBN} will close the
+connection, and @code{gdbserver} will exit.
+
+@item
+Debug a specific program by specifying the process ID of a running
+program:
+
+@smallexample
+gdbserver --attach @var{comm} @var{pid}
+@end smallexample
+
+The @var{comm} parameter is as described above. Supply the process ID
+of a running program in @var{pid}; @value{GDBN} will do everything
+else. Like with the previous mode, when the process @var{pid} exits,
+@value{GDBN} will close the connection, and @code{gdbserver} will exit.
+
+@item
+Multi-process mode -- debug more than one program/process:
+
+@smallexample
+gdbserver --multi @var{comm}
+@end smallexample
+
+In this mode, @value{GDBN} can instruct @command{gdbserver} which
+command(s) to run. Unlike the other 2 modes, @value{GDBN} will not
+close the connection when a process being debugged exits, so you can
+debug several processes in the same session.
+@end itemize
+
+In each of the modes you may specify these options:
+
+@table @env
+
+@item --help
+List all options, with brief explanations.
+
+@item --version
+This option causes @command{gdbserver} to print its version number and exit.
+
+@item --attach
+@command{gdbserver} will attach to a running program. The syntax is:
+
+@smallexample
+target> gdbserver --attach @var{comm} @var{pid}
+@end smallexample
+
+@var{pid} is the process ID of a currently running process. It isn't
+necessary to point @command{gdbserver} at a binary for the running process.
+
+@item --multi
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use this command line option.
+Then you can connect using @kbd{target extended-remote} and start
+the program you want to debug. The syntax is:
+
+@smallexample
+target> gdbserver --multi @var{comm}
+@end smallexample
+
+@item --debug
+Instruct @code{gdbserver} to display extra status information about the debugging
+process.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --remote-debug
+Instruct @code{gdbserver} to display remote protocol debug output.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
+@item --wrapper
+Specify a wrapper to launch programs
+for debugging. The option should be followed by the name of the
+wrapper, then any command-line arguments to pass to the wrapper, then
+@kbd{--} indicating the end of the wrapper arguments.
+
+@item --once
+By default, @command{gdbserver} keeps the listening TCP port open, so that
+additional 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.
+
+@c --disable-packet is not documented for users.
+
+@c --disable-randomization and --no-disable-randomization are superseded by
+@c QDisableRandomization.
+
+@end table
+@c man end
+
+@c man begin SEEALSO gdbserver
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
+@node gcore man
+@heading gcore
+
+@c man title gcore Generate a core file of a running program
+
+@format
+@c man begin SYNOPSIS gcore
+gcore [-o @var{filename}] @var{pid}
+@c man end
+@end format
+
+@c man begin DESCRIPTION gcore
+Generate a core dump of a running program with process ID @var{pid}.
+Produced file is equivalent to a kernel produced core file as if the process
+crashed (and if @kbd{ulimit -c} were used to set up an appropriate core dump
+limit). Unlike after a crash, after @command{gcore} the program remains
+running without any change.
+@c man end
+
+@c man begin OPTIONS gcore
+@table @env
+@item -o @var{filename}
+The optional argument
+@var{filename} specifies the file name where to put the core dump.
+If not specified, the file name defaults to @file{core.@var{pid}},
+where @var{pid} is the running program process ID.
+@end table
+@c man end
+
+@c man begin SEEALSO gcore
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+@noindent
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
+@node gdbinit man
+@heading gdbinit
+
+@c man title gdbinit GDB initialization scripts
+
+@format
+@c man begin SYNOPSIS gdbinit
+@ifset SYSTEM_GDBINIT
+@value{SYSTEM_GDBINIT}
+@end ifset
+
+~/.gdbinit
+
+./.gdbinit
+@c man end
+@end format
+
+@c man begin DESCRIPTION gdbinit
+These files contain @value{GDBN} commands to automatically execute during
+@value{GDBN} startup. The lines of contents are canned sequences of commands,
+described in
+@ifset man
+the @value{GDBN} manual in node @code{Sequences}
+-- shell command @code{info -f gdb -n Sequences}.
+@end ifset
+@ifclear man
+@ref{Sequences}.
+@end ifclear
+
+Please read more in
+@ifset man
+the @value{GDBN} manual in node @code{Startup}
+-- shell command @code{info -f gdb -n Startup}.
+@end ifset
+@ifclear man
+@ref{Startup}.
+@end ifclear
+
+@table @env
+@ifset SYSTEM_GDBINIT
+@item @value{SYSTEM_GDBINIT}
+@end ifset
+@ifclear SYSTEM_GDBINIT
+@item (not enabled with @code{--with-system-gdbinit} during compilation)
+@end ifclear
+System-wide initialization file. It is executed unless user specified
+@value{GDBN} option @code{-nx} or @code{-n}.
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{System-wide configuration}
+-- shell command @code{info -f gdb -n 'System-wide configuration'}.
+@end ifset
+@ifclear man
+@ref{System-wide configuration}.
+@end ifclear
+
+@item ~/.gdbinit
+User initialization file. It is executed unless user specified
+@value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}.
+
+@item ./.gdbinit
+Initialization file for current directory. It may need to be enabled with
+@value{GDBN} security command @code{set auto-load local-gdbinit}.
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{Init File in the Current Directory}
+-- shell command @code{info -f gdb -n 'Init File in the Current Directory'}.
+@end ifset
+@ifclear man
+@ref{Init File in the Current Directory}.
+@end ifclear
+@end table
+@c man end
+
+@c man begin SEEALSO gdbinit
+@ifset man
+gdb(1), @code{info -f gdb -n Startup}
+
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
@include gpl.texi
@node GNU Free Documentation License
projects / deliverable / binutils-gdb.git / blobdiff