\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-1996, 1998-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2013 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@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
-Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
-1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
-2011, 2012
-Free Software Foundation, Inc.
+@c man begin COPYRIGHT
+Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
(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
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2012 Free Software Foundation, Inc.
+Copyright (C) 1988-2013 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
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
@samp{\032} characters as a signal to display the source code for the
frame.
-@item -epoch
-@cindex @code{--epoch}
-The Epoch Emacs-@value{GDBN} interface sets this option when it runs
-@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print
-routines so as to allow Epoch to display values of expressions in a
-separate window.
-
@item -annotate @var{level}
@cindex @code{--annotate}
This option sets the @dfn{annotation level} inside @value{GDBN}. Its
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
+@itemx rethrow
+@itemx catch
@cindex stop on C@t{++} exceptions
-The throwing of a C@t{++} exception.
+The throwing, re-throwing, or catching of a C@t{++} exception.
-@item catch
-The catching of a C@t{++} exception.
+@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 @code{$_exception} convenience variable relies on the presence of
+some SDT probes in @code{libstdc++}. If these probes are not present,
+then this variable cannot be used.
+
+@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
@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
-Both @code{record} and @code{rec} are aliases of @code{target record}.
+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 @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
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
@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 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.
@cindex examining data
@kindex print
@kindex inspect
-@c "inspect" is not quite a synonym if you are using Epoch, which we do not
-@c document because it is nonstandard... Under Epoch it displays in a
-@c different window or something like that.
The usual way to examine data in your program is with the @code{print}
command (abbreviated @code{p}), or its synonym @code{inspect}. It
evaluates and prints the value of an expression of the language your
@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.
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
@table @code
@item auto
Allow @value{GDBN} to choose a decoding style by inspecting your program.
+This is the default.
@item gnu
Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
-This is the default.
@item hp
Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
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}.
@var{pid} is the inferior process ID.
Note that this command is implemented only for some systems (as of
-this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
+this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390).
@end table
@node Character Sets
@itemize @bullet
@item
its passcount as given by the @code{passcount @var{n}} command
+
+@item
+the state about installed on target of each location
@end itemize
@smallexample
collect globfoo2
end
pass count 1200
+2 tracepoint keep y <MULTIPLE>
+ collect $eip
+2.1 y 0x0804859c in func4 at change-loc.h:35
+ installed on target
+2.2 y 0xb7ffc480 in func4 at change-loc.h:35
+ installed on target
+2.3 y <PENDING> set_tracepoint
+3 tracepoint keep y 0x080485b1 in foo at change-loc.c:29
+ not installed on target
(@value{GDBP})
@end smallexample
@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}.
@menu
* Files:: Commands to specify files
* Separate Debug Files:: Debugging information in separate files
+* MiniDebugInfo:: Debugging information in a special section
* Index Files:: Index files speed up GDB
* Symbol Errors:: Errors reading symbol files
* Data Files:: GDB data files
@noindent
This computation does not apply to the ``build ID'' method.
+@node MiniDebugInfo
+@section Debugging information in a special section
+@cindex separate debug sections
+@cindex @samp{.gnu_debugdata} section
+
+Some systems ship pre-built executables and libraries that have a
+special @samp{.gnu_debugdata} section. This feature is called
+@dfn{MiniDebugInfo}. This section holds an LZMA-compressed object and
+is used to supply extra symbols for backtraces.
+
+The intent of this section is to provide extra minimal debugging
+information for use in simple backtraces. It is not intended to be a
+replacement for full separate debugging information (@pxref{Separate
+Debug Files}). The example below shows the intended use; however,
+@value{GDBN} does not currently put restrictions on what sort of
+debugging information might be included in the section.
+
+@value{GDBN} has support for this extension. If the section exists,
+then it is used provided that no other source of debugging information
+can be found, and that @value{GDBN} was configured with LZMA support.
+
+This section can be easily created using @command{objcopy} and other
+standard utilities:
+
+@smallexample
+# Extract the dynamic symbols from the main binary, there is no need
+# 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 .
+nm @var{binary} --format=posix --defined-only \
+ | awk '@{ if ($2 == "T" || $2 == "t") print $1 @}' \
+ | sort > funcsyms
+
+# Keep all the function symbols not already in the dynamic symbol
+# table.
+comm -13 dynsyms funcsyms > keep_symbols
+
+# 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
+
+# Inject the compressed data into the .gnu_debugdata section of the
+# original binary.
+xz mini_debuginfo
+objcopy --add-section .gnu_debugdata=mini_debuginfo.xz @var{binary}
+@end smallexample
@node Index Files
@section Index Files Speed Up @value{GDBN}
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
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
Many versions of SVR4 and compatible systems provide a facility called
@samp{/proc} that can be used to examine the image of a running
-process using file-system subroutines. If @value{GDBN} is configured
-for an operating system with this facility, the command @code{info
-proc} is available to report information about the process running
-your program, or about any process running on your system. @code{info
-proc} works only on SVR4 systems that include the @code{procfs} code.
-This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital
-Unix), Solaris, Irix, and Unixware, but not HP-UX, for example.
+process using file-system subroutines.
+
+If @value{GDBN} is configured for an operating system with this
+facility, the command @code{info proc} is available to report
+information about the process running your program, or about any
+process running on your system. This includes, as of this writing,
+@sc{gnu}/Linux, OSF/1 (Digital Unix), Solaris, and Irix, but
+not HP-UX, for example.
+
+This command may also work on core files that were created on a system
+that has the @samp{/proc} facility.
@table @code
@kindex info proc
needs to be present, or else @value{GDBN} will interpret the number as
a process ID rather than a thread ID).
+@item info proc cmdline
+@cindex info proc cmdline
+Show the original command line of the process. This command is
+specific to @sc{gnu}/Linux.
+
+@item info proc cwd
+@cindex info proc cwd
+Show the current working directory of the process. This command is
+specific to @sc{gnu}/Linux.
+
+@item info proc exe
+@cindex info proc exe
+Show the name of executable of the process. This command is specific
+to @sc{gnu}/Linux.
+
@item info proc mappings
@cindex memory address space mappings
Report the memory address space ranges accessible in the program, with
* 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::
* PowerPC::
@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
@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-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.
+The default is off.
+@item show debug notification
+Displays the current state of remote async notification debugging messages.
@item set debug observer
@cindex observer debugging info
Turns on or off display of @value{GDBN} observer debugging. This
* 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
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
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
Read @var{length} bytes of memory from the inferior, starting at
@var{address}. Returns a buffer object, which behaves much like an array
or a string. It can be modified and given to the
-@code{Inferior.write_memory} function.
+@code{Inferior.write_memory} function. In @code{Python} 3, the return
+value is a @code{memoryview} object.
@end defun
@findex Inferior.write_memory
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
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.
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
@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
given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu}
Emacs Manual}).
-@c The following dropped because Epoch is nonstandard. Reactivate
-@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
-@ignore
-@kindex Emacs Epoch environment
-@kindex Epoch
-@kindex inspect
-
-Version 18 of @sc{gnu} Emacs has a built-in window system
-called the @code{epoch}
-environment. Users of this environment can use a new command,
-@code{inspect} which performs identically to @code{print} except that
-each value is printed in its own window.
-@end ignore
-
-
@node GDB/MI
@chapter The @sc{gdb/mi} Interface
* GDB/MI Simple Examples::
* GDB/MI Command Description Format::
* GDB/MI Breakpoint Commands::
+* GDB/MI Catchpoint Commands::
* GDB/MI Program Context::
* GDB/MI Thread Commands::
* GDB/MI Ada Tasking Commands::
* GDB/MI Result Records::
* GDB/MI Stream Records::
* GDB/MI Async Records::
+* GDB/MI Breakpoint Information::
* GDB/MI Frame Information::
* GDB/MI Thread Information::
* GDB/MI Ada Exception Information::
@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}
executable code.
@end table
+@node GDB/MI Breakpoint Information
+@subsection @sc{gdb/mi} Breakpoint Information
+
+When @value{GDBN} reports information about a breakpoint, a
+tracepoint, a watchpoint, or a catchpoint, it uses a tuple with the
+following fields:
+
+@table @code
+@item number
+The breakpoint number. For a breakpoint that represents one location
+of a multi-location breakpoint, this will be a dotted pair, like
+@samp{1.2}.
+
+@item type
+The type of the breakpoint. For ordinary breakpoints this will be
+@samp{breakpoint}, but many values are possible.
+
+@item catch-type
+If the type of the breakpoint is @samp{catchpoint}, then this
+indicates the exact type of catchpoint.
+
+@item disp
+This is the breakpoint disposition---either @samp{del}, meaning that
+the breakpoint will be deleted at the next stop, or @samp{keep},
+meaning that the breakpoint will not be deleted.
+
+@item enabled
+This indicates whether the breakpoint is enabled, in which case the
+value is @samp{y}, or disabled, in which case the value is @samp{n}.
+Note that this is not the same as the field @code{enable}.
+
+@item addr
+The address of the breakpoint. This may be a hexidecimal number,
+giving the address; or the string @samp{<PENDING>}, for a pending
+breakpoint; or the string @samp{<MULTIPLE>}, for a breakpoint with
+multiple locations. This field will not be present if no address can
+be determined. For example, a watchpoint does not have an address.
+
+@item func
+If known, the function in which the breakpoint appears.
+If not known, this field is not present.
+
+@item filename
+The name of the source file which contains this function, if known.
+If not known, this field is not present.
+
+@item fullname
+The full file name of the source file which contains this function, if
+known. If not known, this field is not present.
+
+@item line
+The line number at which this breakpoint appears, if known.
+If not known, this field is not present.
+
+@item at
+If the source file is not known, this field may be provided. If
+provided, this holds the address of the breakpoint, possibly followed
+by a symbol name.
+
+@item pending
+If this breakpoint is pending, this field is present and holds the
+text used to set the breakpoint, as entered by the user.
+
+@item evaluated-by
+Where this breakpoint's condition is evaluated, either @samp{host} or
+@samp{target}.
+
+@item thread
+If this is a thread-specific breakpoint, then this identifies the
+thread in which the breakpoint can trigger.
+
+@item task
+If this breakpoint is restricted to a particular Ada task, then this
+field will hold the task identifier.
+
+@item cond
+If the breakpoint is conditional, this is the condition expression.
+
+@item ignore
+The ignore count of the breakpoint.
+
+@item enable
+The enable count of the breakpoint.
+
+@item traceframe-usage
+FIXME.
+
+@item static-tracepoint-marker-string-id
+For a static tracepoint, the name of the static tracepoint marker.
+
+@item mask
+For a masked watchpoint, this is the mask.
+
+@item pass
+A tracepoint's pass count.
+
+@item original-location
+The location of the breakpoint as originally specified by the user.
+This field is optional.
+
+@item times
+The number of times the breakpoint has been hit.
+
+@item installed
+This field is only given for tracepoints. This is either @samp{y},
+meaning that the tracepoint is installed, or @samp{n}, meaning that it
+is not.
+
+@item what
+Some extra data, the exact contents of which are type-dependent.
+
+@end table
+
+For example, here is what the output of @code{-break-insert}
+(@pxref{GDB/MI Breakpoint Commands}) might be:
+
+@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",thread-groups=["i1"],
+ times="0"@}
+<- (gdb)
+@end smallexample
+
@node GDB/MI Frame Information
@subsection @sc{gdb/mi} Frame Information
-> -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
@c REDUNDANT???
Get information about a single breakpoint.
+The result is a table of breakpoints. @xref{GDB/MI Breakpoint
+Information}, for details on the format of each breakpoint in the
+table.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
@subsubheading Result
-The result is in the form:
-
-@smallexample
-^done,bkpt=@{number="@var{number}",type="@var{type}",disp="del"|"keep",
-enabled="y"|"n",addr="@var{hex}",func="@var{funcname}",file="@var{filename}",
-fullname="@var{full_filename}",line="@var{lineno}",[thread="@var{threadno},]
-times="@var{times}"@}
-@end smallexample
-
-@noindent
-where @var{number} is the @value{GDBN} number for this breakpoint,
-@var{funcname} is the name of the function where the breakpoint was
-inserted, @var{filename} is the name of the source file which contains
-this function, @var{lineno} is the source line number within that file
-and @var{times} the number of times that the breakpoint has been hit
-(always 0 for -break-insert but may be greater for -break-info or -break-list
-which use the same output).
+@xref{GDB/MI Breakpoint Information}, for details on the format of the
+resulting breakpoint.
Note: this format is open to change.
@c An out-of-band breakpoint instead of part of the result?
(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
@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
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Catchpoint Commands
+@section @sc{gdb/mi} Catchpoint Commands
+
+This section documents @sc{gdb/mi} commands for manipulating
+catchpoints.
+
+@subheading The @code{-catch-load} Command
+@findex -catch-load
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-load [ -t ] [ -d ] @var{regexp}
+@end smallexample
+
+Add a catchpoint for library load events. If the @samp{-t} option is used,
+the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting
+Breakpoints}). If the @samp{-d} option is used, the catchpoint is created
+in a disabled state. The @samp{regexp} argument is a regular
+expression used to match the name of the loaded library.
+
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch load}.
+
+@subsubheading Example
+
+@smallexample
+-catch-load -t foo.so
+^done,bkpt=@{number="1",type="catchpoint",disp="del",enabled="y",
+what="load of library matching foo.so",catch-type="load",times="0"@}
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-catch-unload} Command
+@findex -catch-unload
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-unload [ -t ] [ -d ] @var{regexp}
+@end smallexample
+
+Add a catchpoint for library unload events. If the @samp{-t} option is
+used, the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting
+Breakpoints}). If the @samp{-d} option is used, the catchpoint is
+created in a disabled state. The @samp{regexp} argument is a regular
+expression used to match the name of the unloaded library.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch unload}.
+
+@subsubheading Example
+
+@smallexample
+-catch-unload -d bar.so
+^done,bkpt=@{number="2",type="catchpoint",disp="keep",enabled="n",
+what="load of library matching bar.so",catch-type="unload",times="0"@}
(gdb)
@end smallexample
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Context
@section @sc{gdb/mi} Program Context
used.
@item fullname
-This field is optional. If it is present it will contain an absolute
-file name of @samp{file}. If this field is not present then
-@value{GDBN} was unable to determine the absolute file name.
+Absolute file name of @samp{file}. It is converted to a canonical form
+using the source file search path
+(@pxref{Source Path, ,Specifying Source Directories})
+and after resolving all the symbolic links.
+
+If the source file is not found this field will contain the path as
+present in the debug information.
@item line_asm_insn
This is a list of tuples containing the disassembly for @samp{line} in
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
List the source files for the current executable.
-It will always output the filename, but only when @value{GDBN} can find
-the absolute file name of a source file, will it output the fullname.
+It will always output both the filename and fullname (absolute file
+name) of a source file.
@subsubheading @value{GDBN} 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
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
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
@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
@end table
@item vStopped
-@anchor{vStopped packet}
@cindex @samp{vStopped} packet
-
-In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
-reply and prompt for the stub to report another one.
-
-Reply:
-@table @samp
-@item @r{Any stop packet}
-if there is another unreported stop event (@pxref{Stop Reply Packets})
-@item OK
-if there are no unreported stop events
-@end table
+@xref{Notification Packets}.
@item X @var{addr},@var{length}:@var{XX@dots{}}
@anchor{X packet}
@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{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}).
@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
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
are no notifications defined for @value{GDBN} to send at the moment, but we
assume that most older stubs would ignore them, as well.)
-The following notification packets from the stub to @value{GDBN} are
-defined:
-
+Each notification is comprised of three parts:
@table @samp
-@item Stop: @var{reply}
-Report an asynchronous stop event in non-stop mode.
-The @var{reply} has the form of a stop reply, as
+@item @var{name}:@var{event}
+The notification packet is sent by the side that initiates the
+exchange (currently, only the stub does that), with @var{event}
+carrying the specific information about the notification.
+@var{name} is the name of the notification.
+@item @var{ack}
+The acknowledge sent by the other side, usually @value{GDBN}, to
+acknowledge the exchange and request the event.
+@end table
+
+The purpose of an asynchronous notification mechanism is to report to
+@value{GDBN} that something interesting happened in the remote stub.
+
+The remote stub may send notification @var{name}:@var{event}
+at any time, but @value{GDBN} acknowledges the notification when
+appropriate. The notification event is pending before @value{GDBN}
+acknowledges. Only one notification at a time may be pending; if
+additional events occur before @value{GDBN} has acknowledged the
+previous notification, they must be queued by the stub for later
+synchronous transmission in response to @var{ack} packets from
+@value{GDBN}. Because the notification mechanism is unreliable,
+the stub is permitted to resend a notification if it believes
+@value{GDBN} may not have received it.
+
+Specifically, notifications may appear when @value{GDBN} is not
+otherwise reading input from the stub, or when @value{GDBN} is
+expecting to read a normal synchronous response or a
+@samp{+}/@samp{-} acknowledgment to a packet it has sent.
+Notification packets are distinct from any other communication from
+the stub so there is no ambiguity.
+
+After receiving a notification, @value{GDBN} shall acknowledge it by
+sending a @var{ack} packet as a regular, synchronous request to the
+stub. Such acknowledgment is not required to happen immediately, as
+@value{GDBN} is permitted to send other, unrelated packets to the
+stub first, which the stub should process normally.
+
+Upon receiving a @var{ack} packet, if the stub has other queued
+events to report to @value{GDBN}, it shall respond by sending a
+normal @var{event}. @value{GDBN} shall then send another @var{ack}
+packet to solicit further responses; again, it is permitted to send
+other, unrelated packets as well which the stub should process
+normally.
+
+If the stub receives a @var{ack} packet and there are no additional
+@var{event} to report, the stub shall return an @samp{OK} response.
+At this point, @value{GDBN} has finished processing a notification
+and the stub has completed sending any queued events. @value{GDBN}
+won't accept any new notifications until the final @samp{OK} is
+received . If further notification events occur, the stub shall send
+a new notification, @value{GDBN} shall accept the notification, and
+the process shall be repeated.
+
+The process of asynchronous notification can be illustrated by the
+following example:
+@smallexample
+<- @code{%%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;}
+@code{...}
+-> @code{vStopped}
+<- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;}
+-> @code{vStopped}
+<- @code{T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;}
+-> @code{vStopped}
+<- @code{OK}
+@end smallexample
+
+The following notifications are defined:
+@multitable @columnfractions 0.12 0.12 0.38 0.38
+
+@item Notification
+@tab Ack
+@tab Event
+@tab Description
+
+@item Stop
+@tab vStopped
+@tab @var{reply}. The @var{reply} has the form of a stop reply, as
described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop},
for information on how these notifications are acknowledged by
@value{GDBN}.
-@end table
+@tab Report an asynchronous stop event in non-stop mode.
+
+@end multitable
@node Remote Non-Stop
@section Remote Protocol Support for Non-Stop Mode
to run. When reporting a @samp{W} or @samp{X} response, all running
threads belonging to other attached processes continue to run.
-Only one stop reply notification at a time may be pending; if
-additional stop events occur before @value{GDBN} has acknowledged the
-previous notification, they must be queued by the stub for later
-synchronous transmission in response to @samp{vStopped} packets from
-@value{GDBN}. Because the notification mechanism is unreliable,
-the stub is permitted to resend a stop reply notification
-if it believes @value{GDBN} may not have received it. @value{GDBN}
-ignores additional stop reply notifications received before it has
-finished processing a previous notification and the stub has completed
-sending any queued stop events.
-
-Otherwise, @value{GDBN} must be prepared to receive a stop reply
-notification at any time. Specifically, they may appear when
-@value{GDBN} is not otherwise reading input from the stub, or when
-@value{GDBN} is expecting to read a normal synchronous response or a
-@samp{+}/@samp{-} acknowledgment to a packet it has sent.
-Notification packets are distinct from any other communication from
-the stub so there is no ambiguity.
-
-After receiving a stop reply notification, @value{GDBN} shall
-acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
-as a regular, synchronous request to the stub. Such acknowledgment
-is not required to happen immediately, as @value{GDBN} is permitted to
-send other, unrelated packets to the stub first, which the stub should
-process normally.
-
-Upon receiving a @samp{vStopped} packet, if the stub has other queued
-stop events to report to @value{GDBN}, it shall respond by sending a
-normal stop reply response. @value{GDBN} shall then send another
-@samp{vStopped} packet to solicit further responses; again, it is
-permitted to send other, unrelated packets as well which the stub
-should process normally.
-
-If the stub receives a @samp{vStopped} packet and there are no
-additional stop events to report, the stub shall return an @samp{OK}
-response. At this point, if further stop events occur, the stub shall
-send a new stop reply notification, @value{GDBN} shall accept the
-notification, and the process shall be repeated.
-
In non-stop mode, the target shall respond to the @samp{?} packet as
follows. First, any incomplete stop reply notification/@samp{vStopped}
sequence in progress is abandoned. The target must begin a new
length 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
@node Target Descriptions
registers using the capitalization used in the description.
@menu
+* AArch64 Features::
* ARM Features::
* i386 Features::
* MIPS 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
@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