\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2015 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2016 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2015 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2016 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2015 Free Software Foundation, Inc.
+Copyright (C) 1988-2016 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
option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
Using @value{GDBN} under @sc{gnu} Emacs}).
-@c @item -xdb
-@c @cindex @code{--xdb}
-@c Run in XDB compatibility mode, allowing the use of certain XDB commands.
-@c For information, see the file @file{xdb_trans.html}, which is usually
-@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
-@c systems.
-
@item -interpreter @var{interp}
@cindex @code{--interpreter}
Use the interpreter @var{interp} for interface with the controlling
in the first field of the @samp{info inferiors} display.
@end table
+@vindex $_inferior@r{, convenience variable}
+The debugger convenience variable @samp{$_inferior} contains the
+number of the current inferior. You may find this useful in writing
+breakpoint conditional expressions, command scripts, and so forth.
+@xref{Convenience Vars,, Convenience Variables}, for general
+information on convenience variables.
You can get multiple executables into a debugging session via the
@code{add-inferior} and @w{@code{clone-inferior}} commands. On some
@smallexample
(@value{GDBP}) maint info program-spaces
Id Executable
+* 1 hello
2 goodbye
Bound inferiors: ID 1 (process 21561)
-* 1 hello
@end smallexample
Here we can see that no inferior is running the program @code{hello},
@cindex threads of execution
@cindex multiple threads
@cindex switching threads
-In some operating systems, such as HP-UX and Solaris, a single program
+In some operating systems, such as GNU/Linux and Solaris, a single program
may have more than one @dfn{thread} of execution. The precise semantics
of threads differ from one operating system to another, but in general
the threads of a single program are akin to multiple processes---except
@itemize @bullet
@item automatic notification of new threads
-@item @samp{thread @var{threadno}}, a command to switch among threads
+@item @samp{thread @var{thread-id}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
+@item @samp{thread apply [@var{thread-id-list}] [@var{all}] @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
@item @samp{set print thread-events}, which controls printing of
isn't compatible with the program.
@end itemize
-@quotation
-@emph{Warning:} These facilities are not yet available on every
-@value{GDBN} configuration where the operating system supports threads.
-If your @value{GDBN} does not support threads, these commands have no
-effect. For example, a system without thread support shows no output
-from @samp{info threads}, and always rejects the @code{thread} command,
-like this:
-
-@smallexample
-(@value{GDBP}) info threads
-(@value{GDBP}) thread 1
-Thread ID 1 not known. Use the "info threads" command to
-see the IDs of currently known threads.
-@end smallexample
-@c FIXME to implementors: how hard would it be to say "sorry, this GDB
-@c doesn't support threads"?
-@end quotation
-
@cindex focus of debugging
@cindex current thread
The @value{GDBN} thread debugging facility allows you to observe all
@end smallexample
@noindent
-when @value{GDBN} notices a new thread. In contrast, on an SGI system,
+when @value{GDBN} notices a new thread. In contrast, on other systems,
the @var{systag} is simply something like @samp{process 368}, with no
further qualifier.
@c multithread systems permit starting a program with multiple
@c threads ab initio?
-@cindex thread number
+@anchor{thread numbers}
+@cindex thread number, per inferior
@cindex thread identifier (GDB)
-For debugging purposes, @value{GDBN} associates its own thread
-number---always a single integer---with each thread in your program.
+For debugging purposes, @value{GDBN} associates its own thread number
+---always a single integer---with each thread of an inferior. This
+number is unique between all threads of an inferior, but not unique
+between threads of different inferiors.
+
+@cindex qualified thread ID
+You can refer to a given thread in an inferior using the qualified
+@var{inferior-num}.@var{thread-num} syntax, also known as
+@dfn{qualified thread ID}, with @var{inferior-num} being the inferior
+number and @var{thread-num} being the thread number of the given
+inferior. For example, thread @code{2.3} refers to thread number 3 of
+inferior 2. If you omit @var{inferior-num} (e.g., @code{thread 3}),
+then @value{GDBN} infers you're referring to a thread of the current
+inferior.
+
+Until you create a second inferior, @value{GDBN} does not show the
+@var{inferior-num} part of thread IDs, even though you can always use
+the full @var{inferior-num}.@var{thread-num} form to refer to threads
+of inferior 1, the initial inferior.
+
+@anchor{thread ID lists}
+@cindex thread ID lists
+Some commands accept a space-separated @dfn{thread ID list} as
+argument. A list element can be a thread ID as shown in the first
+field of the @samp{info threads} display, with or without an inferior
+qualifier (e.g., @samp{2.1} or @samp{1}); or can be a range of thread
+numbers, again with or without an inferior qualifier, as in
+@var{inf1}.@var{thr1}-@var{thr2} or @var{thr1}-@var{thr2} (e.g.,
+@samp{1.2-4} or @samp{2-4}). For example, if the current inferior is
+1, the thread list @samp{1 2-3 4.5 6.7-9} includes threads 1 to 3 of
+inferior 1, thread 5 of inferior 4 and threads 7 to 9 of inferior 6.
+That is, in expanded qualified form, the same as @samp{1.1 1.2 1.3 4.5
+6.7 6.8 6.9}.
+
+@anchor{global thread numbers}
+@cindex global thread number
+@cindex global thread identifier (GDB)
+In addition to a @emph{per-inferior} number, each thread is also
+assigned a unique @emph{global} number, also known as @dfn{global
+thread ID}, a single integer. Unlike the thread number component of
+the thread ID, no two threads have the same global ID, even when
+you're debugging multiple inferiors.
+
+From @value{GDBN}'s perspective, a process always has at least one
+thread. In other words, @value{GDBN} assigns a thread number to the
+program's ``main thread'' even if the program is not multi-threaded.
+
+@vindex $_thread@r{, convenience variable}
+The debugger convenience variable @samp{$_thread} contains the
+per-inferior thread number of the current thread. You may find this
+useful in writing breakpoint conditional expressions, command scripts,
+and so forth. @xref{Convenience Vars,, Convenience Variables}, for
+general information on convenience variables.
@table @code
@kindex info threads
-@item info threads @r{[}@var{id}@dots{}@r{]}
-Display a summary of all threads currently in your program. Optional
-argument @var{id}@dots{} is one or more thread ids separated by spaces, and
-means to print information only about the specified thread or threads.
+@item info threads @r{[}@var{thread-id-list}@r{]}
+
+Display information about one or more threads. With no arguments
+displays information about all threads. You can specify the list of
+threads that you want to display using the thread ID list syntax
+(@pxref{thread ID lists}).
+
@value{GDBN} displays for each thread (in this order):
@enumerate
@item
-the thread number assigned by @value{GDBN}
+the per-inferior thread number assigned by @value{GDBN}
@item
the target system's thread identifier (@var{systag})
@smallexample
(@value{GDBP}) info threads
Id Target Id Frame
- 3 process 35 thread 27 0x34e5 in sigpause ()
- 2 process 35 thread 23 0x34e5 in sigpause ()
* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
+ 2 process 35 thread 23 0x34e5 in sigpause ()
+ 3 process 35 thread 27 0x34e5 in sigpause ()
at threadtest.c:68
@end smallexample
+If you're debugging multiple inferiors, @value{GDBN} displays thread
+IDs using the qualified @var{inferior-num}.@var{thread-num} format.
+Otherwise, only @var{thread-num} is shown:
+
+@smallexample
+(@value{GDBP}) info threads
+ Id Target Id Frame
+ 1.1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
+ 1.2 process 35 thread 23 0x34e5 in sigpause ()
+ 1.3 process 35 thread 27 0x34e5 in sigpause ()
+* 2.1 process 65 thread 1 main (argc=1, argv=0x7ffffff8)
+@end smallexample
+
On Solaris, you can display more information about user threads with a
Solaris-specific command:
@end table
@table @code
-@kindex thread @var{threadno}
-@item thread @var{threadno}
-Make thread number @var{threadno} the current thread. The command
-argument @var{threadno} is the internal @value{GDBN} thread number, as
-shown in the first field of the @samp{info threads} display.
-@value{GDBN} responds by displaying the system identifier of the thread
-you selected, and its current stack frame summary:
+@kindex thread @var{thread-id}
+@item thread @var{thread-id}
+Make thread ID @var{thread-id} the current thread. The command
+argument @var{thread-id} is the @value{GDBN} thread ID, as shown in
+the first field of the @samp{info threads} display, with or without an
+inferior qualifier (e.g., @samp{2.1} or @samp{1}).
+
+@value{GDBN} responds by displaying the system identifier of the
+thread you selected, and its current stack frame summary:
@smallexample
(@value{GDBP}) thread 2
@samp{Switching to} depends on your system's conventions for identifying
threads.
-@vindex $_thread@r{, convenience variable}
-The debugger convenience variable @samp{$_thread} contains the number
-of the current thread. You may find this useful in writing breakpoint
-conditional expressions, command scripts, and so forth. See
-@xref{Convenience Vars,, Convenience Variables}, for general
-information on convenience variables.
-
@kindex thread apply
@cindex apply command to several threads
-@item thread apply [@var{threadno} | all [-ascending]] @var{command}
+@item thread apply [@var{thread-id-list} | all [-ascending]] @var{command}
The @code{thread apply} command allows you to apply the named
-@var{command} to one or more threads. Specify the numbers of the
-threads that you want affected with the command argument
-@var{threadno}. It can be a single thread number, one of the numbers
-shown in the first field of the @samp{info threads} display; or it
-could be a range of thread numbers, as in @code{2-4}. To apply
-a command to all threads in descending order, type @kbd{thread apply all
+@var{command} to one or more threads. Specify the threads that you
+want affected using the thread ID list syntax (@pxref{thread ID
+lists}), or specify @code{all} to apply to all threads. To apply a
+command to all threads in descending order, type @kbd{thread apply all
@var{command}}. To apply a command to all threads in ascending order,
type @kbd{thread apply all -ascending @var{command}}.
the child process (@pxref{Attach}). From that point on you can debug
the child process just like any other process which you attached to.
-On some systems, @value{GDBN} provides support for debugging programs that
-create additional processes using the @code{fork} or @code{vfork} functions.
-Currently, the only platforms with this feature are HP-UX (11.x and later
-only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
+On some systems, @value{GDBN} provides support for debugging programs
+that create additional processes using the @code{fork} or @code{vfork}
+functions. On @sc{gnu}/Linux platforms, this feature is supported
+with kernel version 2.5.46 and later.
+
+The fork debugging commands are supported in native mode and when
+connected to @code{gdbserver} in either @code{target remote} mode or
+@code{target extended-remote} mode.
By default, when a program forks, @value{GDBN} will continue to debug
the parent process and the child process will run unimpeded.
Program exited normally.
(@value{GDBP}) info inferiors
Id Description Executable
-* 2 <null> prog2
1 <null> prog1
+* 2 <null> prog2
@end smallexample
@item same
@end table
@end table
+@code{follow-exec-mode} is supported in native mode and
+@code{target extended-remote} mode.
+
You can use the @code{catch} command to make @value{GDBN} stop whenever
a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
Catchpoints, ,Setting Catchpoints}.
program.
On some systems, you can set breakpoints in shared libraries before
-the executable is run. There is a minor limitation on HP-UX systems:
-you must wait until the executable is run in order to set breakpoints
-in shared library routines that are not called directly by the program
-(for example, routines that are arguments in a @code{pthread_create}
-call).
+the executable is run.
@cindex watchpoints
@cindex data breakpoints
catch errors where you have no clue what part of your program is the
culprit.)
-On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other
-x86-based targets, @value{GDBN} includes support for hardware
-watchpoints, which do not slow down the running of your program.
+On some systems, such as most PowerPC or x86-based targets,
+@value{GDBN} includes support for hardware watchpoints, which do not
+slow down the running of your program.
@table @code
@kindex watch
-@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
Set a watchpoint for an expression. @value{GDBN} will break when the
expression @var{expr} is written into by the program and its value
changes. The simplest (and the most popular) use of this command is
(@value{GDBP}) watch foo
@end smallexample
-If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
+If the command includes a @code{@r{[}thread @var{thread-id}@r{]}}
argument, @value{GDBN} breaks only when the thread identified by
-@var{threadnum} changes the value of @var{expr}. If any other threads
+@var{thread-id} changes the value of @var{expr}. If any other threads
change the value of @var{expr}, @value{GDBN} will not break. Note
that watchpoints restricted to a single thread in this way only work
with Hardware Watchpoints.
@end smallexample
@kindex rwatch
-@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
Set a watchpoint that will break when the value of @var{expr} is read
by the program.
@kindex awatch
-@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
@item exec
@kindex catch exec
@cindex break on fork/exec
-A call to @code{exec}. This is currently only available for HP-UX
-and @sc{gnu}/Linux.
+A call to @code{exec}.
@item syscall
@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
@item fork
@kindex catch fork
-A call to @code{fork}. This is currently only available for HP-UX
-and @sc{gnu}/Linux.
+A call to @code{fork}.
@item vfork
@kindex catch vfork
-A call to @code{vfork}. This is currently only available for HP-UX
-and @sc{gnu}/Linux.
+A call to @code{vfork}.
@item load @r{[}regexp@r{]}
@itemx unload @r{[}regexp@r{]}
@subsection Static Probe Points
@cindex static probe point, SystemTap
+@cindex static probe point, DTrace
@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands
for Statically Defined Tracing, and the probes are designed to have a tiny
-runtime code and data footprint, and no dynamic relocations. They are
-usable from assembly, C and C@t{++} languages. See
-@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
-for a good reference on how the @acronym{SDT} probes are implemented.
+runtime code and data footprint, and no dynamic relocations.
-Currently, @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
-@acronym{SDT} probes are supported on ELF-compatible systems. See
+Currently, the following types of probes are supported on
+ELF-compatible systems:
+
+@itemize @bullet
+
+@item @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
+@acronym{SDT} probes@footnote{See
@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
-for more information on how to add @code{SystemTap} @acronym{SDT} probes
-in your applications.
+for more information on how to add @code{SystemTap} @acronym{SDT}
+probes in your applications.}. @code{SystemTap} probes are usable
+from assembly, C and C@t{++} languages@footnote{See
+@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
+for a good reference on how the @acronym{SDT} probes are implemented.}.
+
+@item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace})
+@acronym{USDT} probes. @code{DTrace} probes are usable from C and
+C@t{++} languages.
+@end itemize
@cindex semaphores on static probe points
-Some probes have an associated semaphore variable; for instance, this
-happens automatically if you defined your probe using a DTrace-style
-@file{.d} file. If your probe has a semaphore, @value{GDBN} will
-automatically enable it when you specify a breakpoint using the
-@samp{-probe-stap} notation. But, if you put a breakpoint at a probe's
-location by some other method (e.g., @code{break file:line}), then
-@value{GDBN} will not automatically set the semaphore.
+Some @code{SystemTap} probes have an associated semaphore variable;
+for instance, this happens automatically if you defined your probe
+using a DTrace-style @file{.d} file. If your probe has a semaphore,
+@value{GDBN} will automatically enable it when you specify a
+breakpoint using the @samp{-probe-stap} notation. But, if you put a
+breakpoint at a probe's location by some other method (e.g.,
+@code{break file:line}), then @value{GDBN} will not automatically set
+the semaphore. @code{DTrace} probes do not support semaphores.
You can examine the available static static probes using @code{info
probes}, with optional arguments:
@table @code
@kindex info probes
-@item info probes stap @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+@item info probes @r{[}@var{type}@r{]} @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+If given, @var{type} is either @code{stap} for listing
+@code{SystemTap} probes or @code{dtrace} for listing @code{DTrace}
+probes. If omitted all probes are listed regardless of their types.
+
If given, @var{provider} is a regular expression used to match against provider
names when selecting which probes to list. If omitted, probes by all
probes from all providers are listed.
List the available static probes, from all types.
@end table
+@cindex enabling and disabling probes
+Some probe points can be enabled and/or disabled. The effect of
+enabling or disabling a probe depends on the type of probe being
+handled. Some @code{DTrace} probes can be enabled or
+disabled, but @code{SystemTap} probes cannot be disabled.
+
+You can enable (or disable) one or more probes using the following
+commands, with optional arguments:
+
+@table @code
+@kindex enable probes
+@item enable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+If given, @var{provider} is a regular expression used to match against
+provider names when selecting which probes to enable. If omitted,
+all probes from all providers are enabled.
+
+If given, @var{name} is a regular expression to match against probe
+names when selecting which probes to enable. If omitted, probe names
+are not considered when deciding whether to enable them.
+
+If given, @var{objfile} is a regular expression used to select which
+object files (executable or shared libraries) to examine. If not
+given, all object files are considered.
+
+@kindex disable probes
+@item disable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
+See the @code{enable probes} command above for a description of the
+optional arguments accepted by this command.
+@end table
+
@vindex $_probe_arg@r{, convenience variable}
A probe may specify up to twelve arguments. These are available at the
point at which the probe is defined---that is, when the current PC is
at the probe's location. The arguments are available using the
convenience variables (@pxref{Convenience Vars})
-@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. Each probe argument is
-an integer of the appropriate size; types are not preserved. The
+@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. In @code{SystemTap}
+probes each probe argument is an integer of the appropriate size;
+types are not preserved. In @code{DTrace} probes types are preserved
+provided that they are recognized as such by @value{GDBN}; otherwise
+the value of the probe argument will be a long integer. The
convenience variable @code{$_probe_argc} holds the number of arguments
at the current probe point.
@item set scheduler-locking @var{mode}
@cindex scheduler locking mode
@cindex lock scheduler
-Set the scheduler locking mode. If it is @code{off}, then there is no
-locking and any thread may run at any time. If @code{on}, then only the
-current thread may run when the inferior is resumed. The @code{step}
-mode optimizes for single-stepping; it prevents other threads
-from preempting the current thread while you are stepping, so that
-the focus of debugging does not change unexpectedly.
-Other threads only rarely (or never) get a chance to run
-when you step. They are more likely to run when you @samp{next} over a
-function call, and they are completely free to run when you use commands
-like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
-thread hits a breakpoint during its timeslice, @value{GDBN} does not change
-the current thread away from the thread that you are debugging.
+Set the scheduler locking mode. It applies to normal execution,
+record mode, and replay mode. If it is @code{off}, then there is no
+locking and any thread may run at any time. If @code{on}, then only
+the current thread may run when the inferior is resumed. The
+@code{step} mode optimizes for single-stepping; it prevents other
+threads from preempting the current thread while you are stepping, so
+that the focus of debugging does not change unexpectedly. Other
+threads never get a chance to run when you step, and they are
+completely free to run when you use commands like @samp{continue},
+@samp{until}, or @samp{finish}. However, unless another thread hits a
+breakpoint during its timeslice, @value{GDBN} does not change the
+current thread away from the thread that you are debugging. The
+@code{replay} mode behaves like @code{off} in record mode and like
+@code{on} in replay mode.
@item show scheduler-locking
Display the current scheduler locking mode.
@table @code
@cindex breakpoints and threads
@cindex thread breakpoints
-@kindex break @dots{} thread @var{threadno}
-@item break @var{linespec} thread @var{threadno}
-@itemx break @var{linespec} thread @var{threadno} if @dots{}
-@var{linespec} specifies source lines; there are several ways of
+@kindex break @dots{} thread @var{thread-id}
+@item break @var{location} thread @var{thread-id}
+@itemx break @var{location} thread @var{thread-id} if @dots{}
+@var{location} specifies source lines; there are several ways of
writing them (@pxref{Specify Location}), but the effect is always to
specify some source line.
-Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
+Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
-particular thread reaches this breakpoint. The @var{threadno} specifier
-is one of the numeric thread identifiers assigned by @value{GDBN}, shown
+particular thread reaches this breakpoint. The @var{thread-id} specifier
+is one of the thread identifiers assigned by @value{GDBN}, shown
in the first column of the @samp{info threads} display.
-If you do not specify @samp{thread @var{threadno}} when you set a
+If you do not specify @samp{thread @var{thread-id}} when you set a
breakpoint, the breakpoint applies to @emph{all} threads of your
program.
You can use the @code{thread} qualifier on conditional breakpoints as
-well; in this case, place @samp{thread @var{threadno}} before or
+well; in this case, place @samp{thread @var{thread-id}} before or
after the breakpoint condition, like this:
@smallexample
@kindex record full
@kindex record btrace
@kindex record btrace bts
+@kindex record btrace pt
@kindex record bts
+@kindex record pt
@kindex rec
@kindex rec full
@kindex rec btrace
@kindex rec btrace bts
+@kindex rec btrace pt
@kindex rec bts
+@kindex rec pt
@item record @var{method}
This command starts the process record and replay target. The
recording method can be specified as parameter. Without a parameter
@item btrace @var{format}
Hardware-supported instruction recording. This method does not record
data. Further, the data is collected in a ring buffer so old data will
-be overwritten when the buffer is full. It allows limited replay and
-reverse execution.
+be overwritten when the buffer is full. It allows limited reverse
+execution. Variables and registers are not available during reverse
+execution.
The recording format can be specified as parameter. Without a parameter
the command chooses the recording format. The following recording
Use the @dfn{Branch Trace Store} (@acronym{BTS}) recording format. In
this format, the processor stores a from/to record for each executed
branch in the btrace ring buffer.
+
+@item pt
+@cindex Intel Processor Trace
+Use the @dfn{Intel Processor Trace} recording format. In this
+format, the processor stores the execution trace in a compressed form
+that is afterwards decoded by @value{GDBN}.
+
+The trace can be recorded with very low overhead. The compressed
+trace format also allows small trace buffers to already contain a big
+number of instructions compared to @acronym{BTS}.
+
+Decoding the recorded execution trace, on the other hand, is more
+expensive than decoding @acronym{BTS} trace. This is mostly due to the
+increased number of instructions to process. You should increase the
+buffer-size with care.
@end table
Not all recording formats may be available on all processors.
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})
will be automatically disabled when process record and replay target
Show the current setting of the requested ring buffer size for branch
tracing in @acronym{BTS} format.
+@kindex set record btrace pt
+@item set record btrace pt buffer-size @var{size}
+@itemx set record btrace pt buffer-size unlimited
+Set the requested ring buffer size for branch tracing in Intel
+Processor Trace format. Default is 16KB.
+
+If @var{size} is a positive number, then @value{GDBN} will try to
+allocate a buffer of at least @var{size} bytes for each new thread
+that uses the btrace recording method and the Intel Processor Trace
+format. The actually obtained buffer size may differ from the
+requested @var{size}. Use the @code{info record} command to see the
+actual buffer size for each thread.
+
+If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to
+allocate a buffer of 4MB.
+
+Bigger buffers mean longer traces. On the other hand, @value{GDBN} will
+also need longer to process the branch trace data before it can be used.
+
+@item show record btrace pt buffer-size @var{size}
+Show the current setting of the requested ring buffer size for branch
+tracing in Intel Processor Trace format.
+
@kindex info record
@item info record
Show various statistics about the recording depending on the recording
@item
Size of the perf ring buffer.
@end itemize
+
+For the @code{pt} recording format, it also shows:
+@itemize @bullet
+@item
+Size of the perf ring buffer.
+@end itemize
@end table
@kindex record delete
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:
+are printed in execution order.
+
+It can also print mixed source+disassembly if you specify the the
+@code{/m} or @code{/s} modifier, and print the raw instructions in hex
+as well as in symbolic form by specifying the @code{/r} modifier.
+
+The current position marker is printed for the instruction at the
+current program counter value. This instruction can appear multiple
+times in the trace and the current position marker will be printed
+every time. To omit the current position marker, specify the
+@code{/p} modifier.
+
+To better align the printed instructions when the trace contains
+instructions from more than one function, the function name may be
+omitted by specifying the @code{/f} modifier.
+
+Speculatively executed instructions are prefixed with @samp{?}. This
+feature is not available for all recording formats.
+
+There are several ways to specify what part of the execution log to
+disassemble:
@table @code
@item record instruction-history @var{insn}
@item record instruction-history -
Disassembles ten more instructions before the last disassembly.
-@item record instruction-history @var{begin} @var{end}
+@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 included.
@item record function-call-history -
Prints ten more functions before the last ten-line print.
-@item record function-call-history @var{begin} @var{end}
+@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 included.
@end table
@menu
* Frames:: Stack frames
* Backtrace:: Backtraces
-* Frame Filter Management:: Managing frame filters
* Selection:: Selecting a frame
* Frame Info:: Information on a frame
+* Frame Filter Management:: Managing frame filters
@end menu
correct tracing of the function call chain. However, @value{GDBN} has
no provision for frameless functions elsewhere in the stack.
-@table @code
-@kindex frame@r{, command}
-@cindex current stack frame
-@item frame @r{[}@var{framespec}@r{]}
-The @code{frame} command allows you to move from one stack frame to another,
-and to print the stack frame you select. The @var{framespec} may be either the
-address of the frame or the stack frame number. Without an argument,
-@code{frame} prints the current stack frame.
-
-@kindex select-frame
-@cindex selecting frame silently
-@item select-frame
-The @code{select-frame} command allows you to move from one stack frame
-to another without printing the frame. This is the silent version of
-@code{frame}.
-@end table
-
@node Backtrace
@section Backtraces
Show the current way to display filenames.
@end table
+@node Selection
+@section Selecting a Frame
+
+Most commands for examining the stack and other data in your program work on
+whichever stack frame is selected at the moment. Here are the commands for
+selecting a stack frame; all of them finish by printing a brief description
+of the stack frame just selected.
+
+@table @code
+@kindex frame@r{, selecting}
+@kindex f @r{(@code{frame})}
+@item frame @var{n}
+@itemx f @var{n}
+Select frame number @var{n}. Recall that frame zero is the innermost
+(currently executing) frame, frame one is the frame that called the
+innermost one, and so on. The highest-numbered frame is the one for
+@code{main}.
+
+@item frame @var{stack-addr} [ @var{pc-addr} ]
+@itemx f @var{stack-addr} [ @var{pc-addr} ]
+Select the frame at address @var{stack-addr}. This is useful mainly if the
+chaining of stack frames has been damaged by a bug, making it
+impossible for @value{GDBN} to assign numbers properly to all frames. In
+addition, this can be useful when your program has multiple stacks and
+switches between them. The optional @var{pc-addr} can also be given to
+specify the value of PC for the stack frame.
+
+@kindex up
+@item up @var{n}
+Move @var{n} frames up the stack; @var{n} defaults to 1. For positive
+numbers @var{n}, this advances toward the outermost frame, to higher
+frame numbers, to frames that have existed longer.
+
+@kindex down
+@kindex do @r{(@code{down})}
+@item down @var{n}
+Move @var{n} frames down the stack; @var{n} defaults to 1. For
+positive numbers @var{n}, this advances toward the innermost frame, to
+lower frame numbers, to frames that were created more recently.
+You may abbreviate @code{down} as @code{do}.
+@end table
+
+All of these commands end by printing two lines of output describing the
+frame. The first line shows the frame number, the function name, the
+arguments, and the source file and line number of execution in that
+frame. The second line shows the text of that source line.
+
+@need 1000
+For example:
+
+@smallexample
+@group
+(@value{GDBP}) up
+#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
+ at env.c:10
+10 read_input_file (argv[i]);
+@end group
+@end smallexample
+
+After such a printout, the @code{list} command with no arguments
+prints ten lines centered on the point of execution in the frame.
+You can also edit the program at the point of execution with your favorite
+editing program by typing @code{edit}.
+@xref{List, ,Printing Source Lines},
+for details.
+
+@table @code
+@kindex select-frame
+@item select-frame
+The @code{select-frame} command is a variant of @code{frame} that does
+not display the new frame after selecting it. This command is
+intended primarily for use in @value{GDBN} command scripts, where the
+output might be unnecessary and distracting.
+
+@kindex down-silently
+@kindex up-silently
+@item up-silently @var{n}
+@itemx down-silently @var{n}
+These two commands are variants of @code{up} and @code{down},
+respectively; they differ in that they do their work silently, without
+causing display of the new frame. They are intended primarily for use
+in @value{GDBN} command scripts, where the output might be unnecessary and
+distracting.
+@end table
+
+@node Frame Info
+@section Information About a Frame
+
+There are several other commands to print information about the selected
+stack frame.
+
+@table @code
+@item frame
+@itemx f
+When used without any argument, this command does not change which
+frame is selected, but prints a brief description of the currently
+selected stack frame. It can be abbreviated @code{f}. With an
+argument, this command is used to select a stack frame.
+@xref{Selection, ,Selecting a Frame}.
+
+@kindex info frame
+@kindex info f @r{(@code{info frame})}
+@item info frame
+@itemx info f
+This command prints a verbose description of the selected stack frame,
+including:
+
+@itemize @bullet
+@item
+the address of the frame
+@item
+the address of the next frame down (called by this frame)
+@item
+the address of the next frame up (caller of this frame)
+@item
+the language in which the source code corresponding to this frame is written
+@item
+the address of the frame's arguments
+@item
+the address of the frame's local variables
+@item
+the program counter saved in it (the address of execution in the caller frame)
+@item
+which registers were saved in the frame
+@end itemize
+
+@noindent The verbose description is useful when
+something has gone wrong that has made the stack format fail to fit
+the usual conventions.
+
+@item info frame @var{addr}
+@itemx info f @var{addr}
+Print a verbose description of the frame at address @var{addr}, without
+selecting that frame. The selected frame remains unchanged by this
+command. This requires the same kind of address (more than one for some
+architectures) that you specify in the @code{frame} command.
+@xref{Selection, ,Selecting a Frame}.
+
+@kindex info args
+@item info args
+Print the arguments of the selected frame, each on a separate line.
+
+@item info locals
+@kindex info locals
+Print the local variables of the selected frame, each on a separate
+line. These are all variables (declared either static or automatic)
+accessible at the point of execution of the selected frame.
+
+@end table
+
@node Frame Filter Management
@section Management of Frame Filters.
@cindex managing frame filters
@end smallexample
@end table
-@node Selection
-@section Selecting a Frame
-
-Most commands for examining the stack and other data in your program work on
-whichever stack frame is selected at the moment. Here are the commands for
-selecting a stack frame; all of them finish by printing a brief description
-of the stack frame just selected.
-
-@table @code
-@kindex frame@r{, selecting}
-@kindex f @r{(@code{frame})}
-@item frame @var{n}
-@itemx f @var{n}
-Select frame number @var{n}. Recall that frame zero is the innermost
-(currently executing) frame, frame one is the frame that called the
-innermost one, and so on. The highest-numbered frame is the one for
-@code{main}.
-
-@item frame @var{addr}
-@itemx f @var{addr}
-Select the frame at address @var{addr}. This is useful mainly if the
-chaining of stack frames has been damaged by a bug, making it
-impossible for @value{GDBN} to assign numbers properly to all frames. In
-addition, this can be useful when your program has multiple stacks and
-switches between them.
-
-On the SPARC architecture, @code{frame} needs two addresses to
-select an arbitrary frame: a frame pointer and a stack pointer.
-
-On the @acronym{MIPS} and Alpha architecture, it needs two addresses: a stack
-pointer and a program counter.
-
-On the 29k architecture, it needs three addresses: a register stack
-pointer, a program counter, and a memory stack pointer.
-
-@kindex up
-@item up @var{n}
-Move @var{n} frames up the stack; @var{n} defaults to 1. For positive
-numbers @var{n}, this advances toward the outermost frame, to higher
-frame numbers, to frames that have existed longer.
-
-@kindex down
-@kindex do @r{(@code{down})}
-@item down @var{n}
-Move @var{n} frames down the stack; @var{n} defaults to 1. For
-positive numbers @var{n}, this advances toward the innermost frame, to
-lower frame numbers, to frames that were created more recently.
-You may abbreviate @code{down} as @code{do}.
-@end table
-
-All of these commands end by printing two lines of output describing the
-frame. The first line shows the frame number, the function name, the
-arguments, and the source file and line number of execution in that
-frame. The second line shows the text of that source line.
-
-@need 1000
-For example:
-
-@smallexample
-@group
-(@value{GDBP}) up
-#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
- at env.c:10
-10 read_input_file (argv[i]);
-@end group
-@end smallexample
-
-After such a printout, the @code{list} command with no arguments
-prints ten lines centered on the point of execution in the frame.
-You can also edit the program at the point of execution with your favorite
-editing program by typing @code{edit}.
-@xref{List, ,Printing Source Lines},
-for details.
-
-@table @code
-@kindex down-silently
-@kindex up-silently
-@item up-silently @var{n}
-@itemx down-silently @var{n}
-These two commands are variants of @code{up} and @code{down},
-respectively; they differ in that they do their work silently, without
-causing display of the new frame. They are intended primarily for use
-in @value{GDBN} command scripts, where the output might be unnecessary and
-distracting.
-@end table
-
-@node Frame Info
-@section Information About a Frame
-
-There are several other commands to print information about the selected
-stack frame.
-
-@table @code
-@item frame
-@itemx f
-When used without any argument, this command does not change which
-frame is selected, but prints a brief description of the currently
-selected stack frame. It can be abbreviated @code{f}. With an
-argument, this command is used to select a stack frame.
-@xref{Selection, ,Selecting a Frame}.
-
-@kindex info frame
-@kindex info f @r{(@code{info frame})}
-@item info frame
-@itemx info f
-This command prints a verbose description of the selected stack frame,
-including:
-
-@itemize @bullet
-@item
-the address of the frame
-@item
-the address of the next frame down (called by this frame)
-@item
-the address of the next frame up (caller of this frame)
-@item
-the language in which the source code corresponding to this frame is written
-@item
-the address of the frame's arguments
-@item
-the address of the frame's local variables
-@item
-the program counter saved in it (the address of execution in the caller frame)
-@item
-which registers were saved in the frame
-@end itemize
-
-@noindent The verbose description is useful when
-something has gone wrong that has made the stack format fail to fit
-the usual conventions.
-
-@item info frame @var{addr}
-@itemx info f @var{addr}
-Print a verbose description of the frame at address @var{addr}, without
-selecting that frame. The selected frame remains unchanged by this
-command. This requires the same kind of address (more than one for some
-architectures) that you specify in the @code{frame} command.
-@xref{Selection, ,Selecting a Frame}.
-
-@kindex info args
-@item info args
-Print the arguments of the selected frame, each on a separate line.
-
-@item info locals
-@kindex info locals
-Print the local variables of the selected frame, each on a separate
-line. These are all variables (declared either static or automatic)
-accessible at the point of execution of the selected frame.
-
-@end table
-
-
@node Source
@chapter Examining Source Files
each repetition moves up in the source file.
In general, the @code{list} command expects you to supply zero, one or two
-@dfn{linespecs}. Linespecs specify source lines; there are several ways
+@dfn{locations}. Locations specify source lines; there are several ways
of writing them (@pxref{Specify Location}), but the effect is always
to specify some source line.
Here is a complete description of the possible arguments for @code{list}:
@table @code
-@item list @var{linespec}
-Print lines centered around the line specified by @var{linespec}.
+@item list @var{location}
+Print lines centered around the line specified by @var{location}.
@item list @var{first},@var{last}
Print lines from @var{first} to @var{last}. Both arguments are
-linespecs. When a @code{list} command has two linespecs, and the
-source file of the second linespec is omitted, this refers to
-the same source file as the first linespec.
+locations. When a @code{list} command has two locations, and the
+source file of the second location is omitted, this refers to
+the same source file as the first location.
@item list ,@var{last}
Print lines ending with @var{last}.
@node Specify Location
@section Specifying a Location
@cindex specifying location
-@cindex linespec
+@cindex location
+@cindex source location
+
+@menu
+* Linespec Locations:: Linespec locations
+* Explicit Locations:: Explicit locations
+* Address Locations:: Address locations
+@end menu
Several @value{GDBN} commands accept arguments that specify a location
of your program's code. Since @value{GDBN} is a source-level
-debugger, a location usually specifies some line in the source code;
-for that reason, locations are also known as @dfn{linespecs}.
+debugger, a location usually specifies some line in the source code.
+Locations may be specified using three different formats:
+linespec locations, explicit locations, or address locations.
+
+@node Linespec Locations
+@subsection Linespec Locations
+@cindex linespec locations
-Here are all the different ways of specifying a code location that
-@value{GDBN} understands:
+A @dfn{linespec} is a colon-separated list of source location parameters such
+as file name, function name, etc. Here are all the different ways of
+specifying a linespec:
@table @code
@item @var{linenum}
functions in different source files.
@item @var{label}
-Specifies the line at which the label named @var{label} appears.
-@value{GDBN} searches for the label in the function corresponding to
-the currently selected stack frame. If there is no current selected
-stack frame (for instance, if the inferior is not running), then
-@value{GDBN} will not search for a label.
-
-@item *@var{address}
-Specifies the program address @var{address}. For line-oriented
-commands, such as @code{list} and @code{edit}, this specifies a source
-line that contains @var{address}. For @code{break} and other
-breakpoint oriented commands, this can be used to set breakpoints in
+Specifies the line at which the label named @var{label} appears
+in the function corresponding to the currently selected stack frame.
+If there is no current selected stack frame (for instance, if the inferior
+is not running), then @value{GDBN} will not search for a label.
+
+@cindex breakpoint at static probe point
+@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
+The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
+applications to embed static probes. @xref{Static Probe Points}, for more
+information on finding and using static probes. This form of linespec
+specifies the location of such a static probe.
+
+If @var{objfile} is given, only probes coming from that shared library
+or executable matching @var{objfile} as a regular expression are considered.
+If @var{provider} is given, then only probes from that provider are considered.
+If several probes match the spec, @value{GDBN} will insert a breakpoint at
+each one of those probes.
+@end table
+
+@node Explicit Locations
+@subsection Explicit Locations
+@cindex explicit locations
+
+@dfn{Explicit locations} allow the user to directly specify the source
+location's parameters using option-value pairs.
+
+Explicit locations are useful when several functions, labels, or
+file names have the same name (base name for files) in the program's
+sources. In these cases, explicit locations point to the source
+line you meant more accurately and unambiguously. Also, using
+explicit locations might be faster in large programs.
+
+For example, the linespec @samp{foo:bar} may refer to a function @code{bar}
+defined in the file named @file{foo} or the label @code{bar} in a function
+named @code{foo}. @value{GDBN} must search either the file system or
+the symbol table to know.
+
+The list of valid explicit location options is summarized in the
+following table:
+
+@table @code
+@item -source @var{filename}
+The value specifies the source file name. To differentiate between
+files with the same base name, prepend as many directories as is necessary
+to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise
+@value{GDBN} will use the first file it finds with the given base
+name. This option requires the use of either @code{-function} or @code{-line}.
+
+@item -function @var{function}
+The value specifies the name of a function. Operations
+on function locations unmodified by other options (such as @code{-label}
+or @code{-line}) refer to the line that begins the body of the function.
+In C, for example, this is the line with the open brace.
+
+@item -label @var{label}
+The value specifies the name of a label. When the function
+name is not specified, the label is searched in the function of the currently
+selected stack frame.
+
+@item -line @var{number}
+The value specifies a line offset for the location. The offset may either
+be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on
+the command. When specified without any other options, the line offset is
+relative to the current line.
+@end table
+
+Explicit location options may be abbreviated by omitting any non-unique
+trailing characters from the option name, e.g., @code{break -s main.c -li 3}.
+
+@node Address Locations
+@subsection Address Locations
+@cindex address locations
+
+@dfn{Address locations} indicate a specific program address. They have
+the generalized form *@var{address}.
+
+For line-oriented commands, such as @code{list} and @code{edit}, this
+specifies a source line that contains @var{address}. For @code{break} and
+other breakpoint-oriented commands, this can be used to set breakpoints in
parts of your program which do not have debugging information or
source files.
Here @var{address} may be any expression valid in the current working
language (@pxref{Languages, working language}) that specifies a code
address. In addition, as a convenience, @value{GDBN} extends the
-semantics of expressions used in locations to cover the situations
-that frequently happen during debugging. Here are the various forms
+semantics of expressions used in locations to cover several situations
+that frequently occur during debugging. Here are the various forms
of @var{address}:
@table @code
This form specifies the address of the function's first instruction,
before the stack frame and arguments have been set up.
-@item '@var{filename}'::@var{funcaddr}
+@item '@var{filename}':@var{funcaddr}
Like @var{funcaddr} above, but also specifies the name of the source
file explicitly. This is useful if the name of the function does not
specify the function unambiguously, e.g., if there are several
functions with identical names in different source files.
@end table
-@cindex breakpoint at static probe point
-@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
-The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
-applications to embed static probes. @xref{Static Probe Points}, for more
-information on finding and using static probes. This form of linespec
-specifies the location of such a static probe.
-
-If @var{objfile} is given, only probes coming from that shared library
-or executable matching @var{objfile} as a regular expression are considered.
-If @var{provider} is given, then only probes from that provider are considered.
-If several probes match the spec, @value{GDBN} will insert a breakpoint at
-each one of those probes.
-
-@end table
-
-
@node Edit
@section Editing Source Files
@cindex editing source files
@file{/mnt/cross/baz.c}, then the command
@smallexample
-(@value{GDBP}) set substitute-path /usr/src /mnt/cross
+(@value{GDBP}) set substitute-path /foo/bar /mnt/cross
@end smallexample
@noindent
-will tell @value{GDBN} to replace @samp{/usr/src} with
+will tell @value{GDBN} to replace @samp{/foo/bar} with
@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
@file{baz.c} even though it was moved.
@table @code
@kindex info line
-@item info line @var{linespec}
+@item info line @var{location}
Print the starting and ending addresses of the compiled code for
-source line @var{linespec}. You can specify source lines in any of
+source line @var{location}. You can specify source lines in any of
the ways documented in @ref{Specify Location}.
@end table
@noindent
@cindex code address and its source line
We can also inquire (using @code{*@var{addr}} as the form for
-@var{linespec}) what source line covers a particular address:
+@var{location}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
@cindex listing machine instructions
@item disassemble
@itemx disassemble /m
+@itemx disassemble /s
@itemx disassemble /r
This specialized command dumps a range of memory as machine
instructions. It can also print mixed source+disassembly by specifying
-the @code{/m} modifier and print the raw instructions in hex as well as
-in symbolic form by specifying the @code{/r}.
+the @code{/m} or @code{/s} modifier and print the raw instructions in hex
+as well as in symbolic form by specifying the @code{/r} modifier.
The default memory range is the function surrounding the
program counter of the selected frame. A single argument to this
command is a program counter value; @value{GDBN} dumps the function
End of assembler dump.
@end smallexample
-Here is an example showing mixed source+assembly for Intel x86, when the
-program is stopped just after function prologue:
+Here is an example showing mixed source+assembly for Intel x86
+with @code{/m} or @code{/s}, when the program is stopped just after
+function prologue in a non-optimized function with no inline code.
@smallexample
(@value{GDBP}) disas /m main
End of assembler dump.
@end smallexample
+The @code{/m} option is deprecated as its output is not useful when
+there is either inlined code or re-ordered code.
+The @code{/s} option is the preferred choice.
+Here is an example for AMD x86-64 showing the difference between
+@code{/m} output and @code{/s} output.
+This example has one inline function defined in a header file,
+and the code is compiled with @samp{-O2} optimization.
+Note how the @code{/m} output is missing the disassembly of
+several instructions that are present in the @code{/s} output.
+
+@file{foo.h}:
+
+@smallexample
+int
+foo (int a)
+@{
+ if (a < 0)
+ return a * 2;
+ if (a == 0)
+ return 1;
+ return a + 10;
+@}
+@end smallexample
+
+@file{foo.c}:
+
+@smallexample
+#include "foo.h"
+volatile int x, y;
+int
+main ()
+@{
+ x = foo (y);
+ return 0;
+@}
+@end smallexample
+
+@smallexample
+(@value{GDBP}) disas /m main
+Dump of assembler code for function main:
+5 @{
+
+6 x = foo (y);
+ 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y>
+ 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x>
+
+7 return 0;
+8 @}
+ 0x000000000040041d <+29>: xor %eax,%eax
+ 0x000000000040041f <+31>: retq
+ 0x0000000000400420 <+32>: add %eax,%eax
+ 0x0000000000400422 <+34>: jmp 0x400417 <main+23>
+
+End of assembler dump.
+(@value{GDBP}) disas /s main
+Dump of assembler code for function main:
+foo.c:
+5 @{
+6 x = foo (y);
+ 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 <y>
+
+foo.h:
+4 if (a < 0)
+ 0x0000000000400406 <+6>: test %eax,%eax
+ 0x0000000000400408 <+8>: js 0x400420 <main+32>
+
+6 if (a == 0)
+7 return 1;
+8 return a + 10;
+ 0x000000000040040a <+10>: lea 0xa(%rax),%edx
+ 0x000000000040040d <+13>: test %eax,%eax
+ 0x000000000040040f <+15>: mov $0x1,%eax
+ 0x0000000000400414 <+20>: cmovne %edx,%eax
+
+foo.c:
+6 x = foo (y);
+ 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 <x>
+
+7 return 0;
+8 @}
+ 0x000000000040041d <+29>: xor %eax,%eax
+ 0x000000000040041f <+31>: retq
+
+foo.h:
+5 return a * 2;
+ 0x0000000000400420 <+32>: add %eax,%eax
+ 0x0000000000400422 <+34>: jmp 0x400417 <main+23>
+End of assembler dump.
+@end smallexample
+
Here is another example showing raw instructions in hex for AMD x86-64,
@smallexample
End of assembler dump.
@end smallexample
-Addresses cannot be specified as a linespec (@pxref{Specify Location}).
+Addresses cannot be specified as a location (@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}.
are from the last memory unit printed; this is not the same as the last
address printed if several units were printed on the last line of output.
+@anchor{addressable memory unit}
+@cindex addressable memory unit
+Most targets have an addressable memory unit size of 8 bits. This means
+that to each memory address are associated 8 bits of data. Some
+targets, however, have other addressable memory unit sizes.
+Within @value{GDBN} and this document, the term
+@dfn{addressable memory unit} (or @dfn{memory unit} for short) is used
+when explicitly referring to a chunk of data of that size. The word
+@dfn{byte} is used to refer to a chunk of data of 8 bits, regardless of
+the addressable memory unit size of the target. For most systems,
+addressable memory unit is a synonym of byte.
+
@cindex remote memory comparison
@cindex target memory comparison
@cindex verify remote memory image
@xref{General Query Packets}.
This variable contains the address of the thread information block.
-@end table
+@item $_inferior
+The number of the current inferior. @xref{Inferiors and
+Programs, ,Debugging Multiple Inferiors and Programs}.
-On HP-UX systems, if you refer to a function or variable name that
-begins with a dollar sign, @value{GDBN} searches for a user or system
-name first, before it searches for a convenience variable.
+@item $_thread
+The thread number of the current thread. @xref{thread numbers}.
+
+@end table
@node Convenience Funs
@section Convenience Functions
@anchor{linux info os infotypes}
@table @code
+@kindex info os cpus
+@item cpus
+Display the list of all CPUs/cores. For each CPU/core, @value{GDBN} prints
+the available fields from /proc/cpuinfo. For each supported architecture
+different fields are available. Two common entries are processor which gives
+CPU number and bogomips; a system constant that is calculated during
+kernel initialization.
+
+@kindex info os files
+@item files
+Display the list of open file descriptors on the target. For each
+file descriptor, @value{GDBN} prints the identifier of the process
+owning the descriptor, the command of the owning process, the value
+of the descriptor, and the target of the descriptor.
+
+@kindex info os modules
+@item modules
+Display the list of all loaded kernel modules on the target. For each
+module, @value{GDBN} prints the module name, the size of the module in
+bytes, the number of times the module is used, the dependencies of the
+module, the status of the module, and the address of the loaded module
+in memory.
+
+@kindex info os msg
+@item msg
+Display the list of all System V message queues on the target. For each
+message queue, @value{GDBN} prints the message queue key, the message
+queue identifier, the access permissions, the current number of bytes
+on the queue, the current number of messages on the queue, the processes
+that last sent and received a message on the queue, the user and group
+of the owner and creator of the message queue, the times at which a
+message was last sent and received on the queue, and the time at which
+the message queue was last changed.
+
@kindex info os processes
@item processes
Display the list of processes on the target. For each process,
so that processes belonging to the same process group are grouped together
and the process group leader is listed first.
-@kindex info os threads
-@item threads
-Display the list of threads running on the target. For each thread,
-@value{GDBN} prints the identifier of the process that the thread
-belongs to, the command of the process, the thread identifier, and the
-processor core that it is currently running on. The main thread of a
-process is not listed.
-
-@kindex info os files
-@item files
-Display the list of open file descriptors on the target. For each
-file descriptor, @value{GDBN} prints the identifier of the process
-owning the descriptor, the command of the owning process, the value
-of the descriptor, and the target of the descriptor.
-
-@kindex info os sockets
-@item sockets
-Display the list of Internet-domain sockets on the target. For each
-socket, @value{GDBN} prints the address and port of the local and
-remote endpoints, the current state of the connection, the creator of
-the socket, the IP address family of the socket, and the type of the
-connection.
+@kindex info os semaphores
+@item semaphores
+Display the list of all System V semaphore sets on the target. For each
+semaphore set, @value{GDBN} prints the semaphore set key, the semaphore
+set identifier, the access permissions, the number of semaphores in the
+set, the user and group of the owner and creator of the semaphore set,
+and the times at which the semaphore set was operated upon and changed.
@kindex info os shm
@item shm
attaches to the region, and the times at which the region was last
attached to, detach from, and changed.
-@kindex info os semaphores
-@item semaphores
-Display the list of all System V semaphore sets on the target. For each
-semaphore set, @value{GDBN} prints the semaphore set key, the semaphore
-set identifier, the access permissions, the number of semaphores in the
-set, the user and group of the owner and creator of the semaphore set,
-and the times at which the semaphore set was operated upon and changed.
-
-@kindex info os msg
-@item msg
-Display the list of all System V message queues on the target. For each
-message queue, @value{GDBN} prints the message queue key, the message
-queue identifier, the access permissions, the current number of bytes
-on the queue, the current number of messages on the queue, the processes
-that last sent and received a message on the queue, the user and group
-of the owner and creator of the message queue, the times at which a
-message was last sent and received on the queue, and the time at which
-the message queue was last changed.
+@kindex info os sockets
+@item sockets
+Display the list of Internet-domain sockets on the target. For each
+socket, @value{GDBN} prints the address and port of the local and
+remote endpoints, the current state of the connection, the creator of
+the socket, the IP address family of the socket, and the type of the
+connection.
-@kindex info os modules
-@item modules
-Display the list of all loaded kernel modules on the target. For each
-module, @value{GDBN} prints the module name, the size of the module in
-bytes, the number of times the module is used, the dependencies of the
-module, the status of the module, and the address of the loaded module
-in memory.
+@kindex info os threads
+@item threads
+Display the list of threads running on the target. For each thread,
+@value{GDBN} prints the identifier of the process that the thread
+belongs to, the command of the process, the thread identifier, and the
+processor core that it is currently running on. The main thread of a
+process is not listed.
@end table
@item info os
@code{restore} to copy data between target memory and a file. The
@code{dump} and @code{append} commands write data to a file, and the
@code{restore} command reads data from a file back into the inferior's
-memory. Files may be in binary, Motorola S-record, Intel hex, or
-Tektronix Hex format; however, @value{GDBN} can only append to binary
-files.
+memory. Files may be in binary, Motorola S-record, Intel hex,
+Tektronix Hex, or Verilog Hex format; however, @value{GDBN} can only
+append to binary files, and cannot read from Verilog Hex files.
@table @code
Motorola S-record format.
@item tekhex
Tektronix Hex format.
+@item verilog
+Verilog Hex format.
@end table
@value{GDBN} uses the same definitions of these formats as the
Note that this command is implemented only for some systems (as of
this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390).
+
+On @sc{gnu}/Linux, this command can take into account the value of the
+file @file{/proc/@var{pid}/coredump_filter} when generating the core
+dump (@pxref{set use-coredump-filter}).
+
+@kindex set use-coredump-filter
+@anchor{set use-coredump-filter}
+@item set use-coredump-filter on
+@itemx set use-coredump-filter off
+Enable or disable the use of the file
+@file{/proc/@var{pid}/coredump_filter} when generating core dump
+files. This file is used by the Linux kernel to decide what types of
+memory mappings will be dumped or ignored when generating a core dump
+file. @var{pid} is the process ID of a currently running process.
+
+To make use of this feature, you have to write in the
+@file{/proc/@var{pid}/coredump_filter} file a value, in hexadecimal,
+which is a bit mask representing the memory mapping types. If a bit
+is set in the bit mask, then the memory mappings of the corresponding
+types will be dumped; otherwise, they will be ignored. This
+configuration is inherited by child processes. For more information
+about the bits that can be set in the
+@file{/proc/@var{pid}/coredump_filter} file, please refer to the
+manpage of @code{core(5)}.
+
+By default, this option is @code{on}. If this option is turned
+@code{off}, @value{GDBN} does not read the @file{coredump_filter} file
+and instead uses the same default value as the Linux kernel in order
+to decide which pages will be dumped in the core dump file. This
+value is currently @code{0x33}, which means that bits @code{0}
+(anonymous private mappings), @code{1} (anonymous shared mappings),
+@code{4} (ELF headers) and @code{5} (private huge pages) are active.
+This will cause these memory mappings to be dumped automatically.
@end table
@node Character Sets
the macro may begin with a hyphen.
@kindex info macros
-@item info macros @var{linespec}
+@item info macros @var{location}
Show all macro definitions that are in effect at the location specified
-by @var{linespec}, and describe the source location or compiler
+by @var{location}, and describe the source location or compiler
command-line where those definitions were established.
@kindex macro define
@kindex trace
@item trace @var{location}
The @code{trace} command is very similar to the @code{break} command.
-Its argument @var{location} can be a source line, a function name, or
-an address in the target program. @xref{Specify Location}. The
-@code{trace} command defines a tracepoint, which is a point in the
-target program where the debugger will briefly stop, collect some
-data, and then allow the program to continue. Setting a tracepoint or
-changing its actions takes effect immediately if the remote stub
+Its argument @var{location} can be any valid location.
+@xref{Specify Location}. The @code{trace} command defines a tracepoint,
+which is a point in the target program where the debugger will briefly stop,
+collect some data, and then allow the program to continue. Setting a tracepoint
+or changing its actions takes effect immediately if the remote stub
supports the @samp{InstallInTrace} feature (@pxref{install tracepoint
in tracing}).
If remote stub doesn't support the @samp{InstallInTrace} feature, all
in @value{GDBN}.
* Omissions from Ada:: Restrictions on the Ada expression syntax.
* Additions to Ada:: Extensions of the Ada expression syntax.
+* Overloading support for Ada:: Support for expressions involving overloaded
+ subprograms.
* Stopping Before Main Program:: Debugging the program during elaboration.
* Ada Exceptions:: Ada Exceptions
* Ada Tasks:: Listing and setting breakpoints in tasks.
(@samp{#}) still works at the beginning of a line in Ada mode, but not in the
middle (to allow based literals).
-The debugger supports limited overloading. Given a subprogram call in which
-the function symbol has multiple definitions, it will use the number of
-actual parameters and some information about their types to attempt to narrow
-the set of definitions. It also makes very limited use of context, preferring
-procedures to functions in the context of the @code{call} command, and
-functions to procedures elsewhere.
-
@node Omissions from Ada
@subsubsection Omissions from Ada
@cindex Ada, omissions from
@end itemize
+@node Overloading support for Ada
+@subsubsection Overloading support for Ada
+@cindex overloading, Ada
+
+The debugger supports limited overloading. Given a subprogram call in which
+the function symbol has multiple definitions, it will use the number of
+actual parameters and some information about their types to attempt to narrow
+the set of definitions. It also makes very limited use of context, preferring
+procedures to functions in the context of the @code{call} command, and
+functions to procedures elsewhere.
+
+If, after narrowing, the set of matching definitions still contains more than
+one definition, @value{GDBN} will display a menu to query which one it should
+use, for instance:
+
+@smallexample
+(@value{GDBP}) print f(1)
+Multiple matches for f
+[0] cancel
+[1] foo.f (integer) return boolean at foo.adb:23
+[2] foo.f (foo.new_integer) return boolean at foo.adb:28
+>
+@end smallexample
+
+In this case, just select one menu entry either to cancel expression evaluation
+(type @kbd{0} and press @key{RET}) or to continue evaluation with a specific
+instance (type the corresponding number and press @key{RET}).
+
+Here are a couple of commands to customize @value{GDBN}'s behavior in this
+case:
+
+@table @code
+
+@kindex set ada print-signatures
+@item set ada print-signatures
+Control whether parameter types and return types are displayed in overloads
+selection menus. It is @code{on} by default.
+@xref{Overloading support for Ada}.
+
+@kindex show ada print-signatures
+@item show ada print-signatures
+Show the current setting for displaying parameter types and return types in
+overloads selection menu.
+@xref{Overloading support for Ada}.
+
+@end table
+
@node Stopping Before Main Program
@subsubsection Stopping at the Very Beginning
@item task @var{taskno}
@cindex Ada task switching
-This command is like the @code{thread @var{threadno}}
+This command is like the @code{thread @var{thread-id}}
command (@pxref{Threads}). It switches the context of debugging
from the current task to the given task.
#4 0x804aacc in un () at un.adb:5
@end smallexample
-@item break @var{linespec} task @var{taskno}
-@itemx break @var{linespec} task @var{taskno} if @dots{}
+@item break @var{location} task @var{taskno}
+@itemx break @var{location} task @var{taskno} if @dots{}
@cindex breakpoints and tasks, in Ada
@cindex task breakpoints, in Ada
@kindex break @dots{} task @var{taskno}@r{ (Ada)}
These commands are like the @code{break @dots{} thread @dots{}}
command (@pxref{Thread Stops}). The
-@var{linespec} argument specifies source lines, as described
+@var{location} argument specifies source lines, as described
in @ref{Specify Location}.
Use the qualifier @samp{task @var{taskno}} with a breakpoint command
@table @code
@kindex jump
@kindex j @r{(@code{jump})}
-@item jump @var{linespec}
-@itemx j @var{linespec}
-@itemx jump @var{location}
+@item jump @var{location}
@itemx j @var{location}
-Resume execution at line @var{linespec} or at address given by
-@var{location}. Execution stops again immediately if there is a
-breakpoint there. @xref{Specify Location}, for a description of the
-different forms of @var{linespec} and @var{location}. It is common
+Resume execution at @var{location}. Execution stops again immediately
+if there is a breakpoint there. @xref{Specify Location}, for a description
+of the different forms of @var{location}. It is common
practice to use the @code{tbreak} command in conjunction with
@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}.
The @code{jump} command does not change the current stack frame, or
the stack pointer, or the contents of any memory location or any
-register other than the program counter. If line @var{linespec} is in
+register other than the program counter. If @var{location} is in
a different function from the one currently executing, the results may
be bizarre if the two functions expect different patterns of arguments or
of local variables. For this reason, the @code{jump} command requests
well acquainted with the machine-language code of your program.
@end table
-@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
On many systems, you can get much the same effect as the @code{jump}
command by storing a new value into the register @code{$pc}. The
difference is that this does not start your program running; it only
@end smallexample
@end table
+@table @code
+@item compile print @var{expr}
+@itemx compile print /@var{f} @var{expr}
+Compile and execute @var{expr} with the compiler language found as the
+current language in @value{GDBN} (@pxref{Languages}). By default the
+value of @var{expr} is printed in a format appropriate to its data type;
+you can choose a different format by specifying @samp{/@var{f}}, where
+@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
+Formats}.
+
+@item compile print
+@itemx compile print /@var{f}
+@cindex reprint the last value
+Alternatively you can enter the expression (source code producing it) as
+multiple lines of text. To enter this mode, invoke the @samp{compile print}
+command without any text following the command. This will start the
+multiple-line editor.
+@end table
+
+@noindent
+The process of compiling and injecting the code can be inspected using:
+
+@table @code
+@anchor{set debug compile}
+@item set debug compile
+@cindex compile command debugging info
+Turns on or off display of @value{GDBN} process of compiling and
+injecting the code. The default is off.
+
+@item show debug compile
+Displays the current state of displaying @value{GDBN} process of
+compiling and injecting the code.
+@end table
+
+@subsection Compilation options for the @code{compile} command
+
+@value{GDBN} needs to specify the right compilation options for the code
+to be injected, in part to make its ABI compatible with the inferior
+and in part to make the injected code compatible with @value{GDBN}'s
+injecting process.
+
+@noindent
+The options used, in increasing precedence:
+
+@table @asis
+@item target architecture and OS options (@code{gdbarch})
+These options depend on target processor type and target operating
+system, usually they specify at least 32-bit (@code{-m32}) or 64-bit
+(@code{-m64}) compilation option.
+
+@item compilation options recorded in the target
+@value{NGCC} (since version 4.7) stores the options used for compilation
+into @code{DW_AT_producer} part of DWARF debugging information according
+to the @value{NGCC} option @code{-grecord-gcc-switches}. One has to
+explicitly specify @code{-g} during inferior compilation otherwise
+@value{NGCC} produces no DWARF. This feature is only relevant for
+platforms where @code{-g} produces DWARF by default, otherwise one may
+try to enforce DWARF by using @code{-gdwarf-4}.
+
+@item compilation options set by @code{set compile-args}
+@end table
+
+@noindent
+You can override compilation options using the following command:
+
+@table @code
+@item set compile-args
+@cindex compile command options override
+Set compilation options used for compiling and injecting code with the
+@code{compile} commands. These options override any conflicting ones
+from the target architecture and/or options stored during inferior
+compilation.
+
+@item show compile-args
+Displays the current state of compilation options override.
+This does not show all the options actually used during compilation,
+use @ref{set debug compile} for that.
+@end table
+
@subsection Caveats when using the @code{compile} command
There are a few caveats to keep in mind when using the @code{compile}
will print to the console.
@end table
+@subsection Compiler search for the @code{compile} command
+
+@value{GDBN} needs to find @value{NGCC} for the inferior being debugged which
+may not be obvious for remote targets of different architecture than where
+@value{GDBN} is running. Environment variable @code{PATH} (@code{PATH} from
+shell that executed @value{GDBN}, not the one set by @value{GDBN}
+command @code{set environment}). @xref{Environment}. @code{PATH} on
+@value{GDBN} host is searched for @value{NGCC} binary matching the
+target architecture and operating system.
+
+Specifically @code{PATH} is searched for binaries matching regular expression
+@code{@var{arch}(-[^-]*)?-@var{os}-gcc} according to the inferior target being
+debugged. @var{arch} is processor name --- multiarch is supported, so for
+example both @code{i386} and @code{x86_64} targets look for pattern
+@code{(x86_64|i.86)} and both @code{s390} and @code{s390x} targets look
+for pattern @code{s390x?}. @var{os} is currently supported only for
+pattern @code{linux(-gnu)?}.
+
@node GDB Files
@chapter @value{GDBN} Files
@menu
* Files:: Commands to specify files
+* File Caching:: Information about @value{GDBN}'s file caching
* Separate Debug Files:: Debugging information in separate files
* MiniDebugInfo:: Debugging information in a special section
* Index Files:: Index files speed up GDB
@cindex shared libraries
@anchor{Shared Libraries}
-@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
-and IBM RS/6000 AIX shared libraries.
+@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, SunOS,
+Darwin/Mach-O, SVr4, IBM RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and
+DSBT (TIC6X) shared libraries.
On MS-Windows @value{GDBN} must be linked with the Expat library to support
shared libraries. @xref{Expat}.
references to a function in a shared library, however---unless you are
debugging a core file).
-On HP-UX, if the program loads a library explicitly, @value{GDBN}
-automatically loads the symbols at the time of the @code{shl_load} call.
-
@c FIXME: some @value{GDBN} release may permit some refs to undef
@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
@c FIXME...lib; check this from time to time when updating manual
that match @var{regex}. If @var{regex} is omitted then print
all shared libraries that are loaded.
+@kindex info dll
+@item info dll @var{regex}
+This is an alias of @code{info sharedlibrary}.
+
@kindex sharedlibrary
@kindex share
@item sharedlibrary @var{regex}
to specify the search directories for target libraries.
@table @code
-@cindex prefix for shared library file names
+@cindex prefix for executable and shared library file names
@cindex system root, alternate
@kindex set solib-absolute-prefix
@kindex set sysroot
Use @var{path} as the system root for the program being debugged. Any
absolute shared library paths will be prefixed with @var{path}; many
runtime loaders store the absolute paths to the shared library in the
-target program's memory. If you use @code{set sysroot} to find shared
-libraries, they need to be laid out in the same way that they are on
-the target, with e.g.@: a @file{/lib} and @file{/usr/lib} hierarchy
-under @var{path}.
-
-If @var{path} starts with the sequence @file{remote:}, @value{GDBN} will
-retrieve the target libraries from the remote system. This is only
-supported when using a remote target that supports the @code{remote get}
-command (@pxref{File Transfer,,Sending files to a remote system}).
-The part of @var{path} following the initial @file{remote:}
-(if present) is used as system root prefix on the remote file system.
-@footnote{If you want to specify a local system root using a directory
-that happens to be named @file{remote:}, you need to use some equivalent
-variant of the name like @file{./remote:}.}
+target program's memory. When starting processes remotely, and when
+attaching to already-running processes (local or remote), their
+executable filenames will be prefixed with @var{path} if reported to
+@value{GDBN} as absolute by the operating system. If you use
+@code{set sysroot} to find executables and shared libraries, they need
+to be laid out in the same way that they are on the target, with
+e.g.@: a @file{/bin}, @file{/lib} and @file{/usr/lib} hierarchy under
+@var{path}.
+
+If @var{path} starts with the sequence @file{target:} and the target
+system is remote then @value{GDBN} will retrieve the target binaries
+from the remote system. This is only supported when using a remote
+target that supports the @code{remote get} command (@pxref{File
+Transfer,,Sending files to a remote system}). The part of @var{path}
+following the initial @file{target:} (if present) is used as system
+root prefix on the remote file system. If @var{path} starts with the
+sequence @file{remote:} this is converted to the sequence
+@file{target:} by @code{set sysroot}@footnote{Historically the
+functionality to retrieve binaries from the remote system was
+provided by prefixing @var{path} with @file{remote:}}. If you want
+to specify a local system root using a directory that happens to be
+named @file{target:} or @file{remote:}, you need to use some
+equivalent variant of the name like @file{./target:}.
For targets with an MS-DOS based filesystem, such as MS-Windows and
SymbianOS, @value{GDBN} tries prefixing a few variants of the target
c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll
@end smallexample
-If that does not find the shared library, @value{GDBN} tries removing
+If that does not find the binary, @value{GDBN} tries removing
the @samp{:} character from the drive spec, both for convenience, and,
for the case of the host file system not supporting file names with
colons:
@value{GDBN} can find the correct copies of both
@file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}.
-If that still does not find the shared library, @value{GDBN} tries
+If that still does not find the binary, @value{GDBN} tries
removing the whole drive spec from the target file name:
@smallexample
@kindex show sysroot
@item show sysroot
-Display the current shared library prefix.
+Display the current executable and shared library prefix.
@kindex set solib-search-path
@item set solib-search-path @var{path}
Show whether a source file may have multiple base names.
@end table
+@node File Caching
+@section File Caching
+@cindex caching of opened files
+@cindex caching of bfd objects
+
+To speed up file loading, and reduce memory usage, @value{GDBN} will
+reuse the @code{bfd} objects used to track open files. @xref{Top, ,
+BFD, bfd, The Binary File Descriptor Library}. The following commands
+allow visibility and control of the caching behavior.
+
+@table @code
+@kindex maint info bfds
+@item maint info bfds
+This prints information about each @code{bfd} object that is known to
+@value{GDBN}.
+
+@kindex maint set bfd-sharing
+@kindex maint show bfd-sharing
+@kindex bfd caching
+@item maint set bfd-sharing
+@item maint show bfd-sharing
+Control whether @code{bfd} objects can be shared. When sharing is
+enabled @value{GDBN} reuses already open @code{bfd} objects rather
+than reopening the same file. Turning sharing off does not cause
+already shared @code{bfd} objects to be unshared, but all future files
+that are opened will create a new @code{bfd} object. Similarly,
+re-enabling sharing does not cause multiple existing @code{bfd}
+objects to be collapsed into a single shared @code{bfd} object.
+
+@kindex set debug bfd-cache @var{level}
+@kindex bfd caching
+@item set debug bfd-cache @var{level}
+Turns on debugging of the bfd cache, setting the level to @var{level}.
+
+@kindex show debug bfd-cache
+@kindex bfd caching
+@item show debug bfd-cache
+Show the current debugging level of the bfd cache.
+@end table
+
@node Separate Debug Files
@section Debugging Information in Separate Files
@cindex separate debugging information files
@item
The executable contains a @dfn{build ID}, a unique bit string that is
also present in the corresponding debug info file. (This is supported
-only on some operating systems, notably those which use the ELF format
+only on some operating systems, when using the ELF or PE file formats
for binary files and the @sc{gnu} Binutils.) For more details about
this feature, see the description of the @option{--build-id}
command-line option in @ref{Options, , Command Line Options, ld.info,
@node Connecting
@section Connecting to a Remote Target
+@cindex remote debugging, connecting
+@cindex @code{gdbserver}, connecting
+@cindex remote debugging, types of connections
+@cindex @code{gdbserver}, types of connections
+@cindex @code{gdbserver}, @code{target remote} mode
+@cindex @code{gdbserver}, @code{target extended-remote} mode
-On the @value{GDBN} host machine, you will need an unstripped copy of
-your program, since @value{GDBN} needs symbol and debugging information.
-Start up @value{GDBN} as usual, using the name of the local copy of your
-program as the first argument.
+This section describes how to connect to a remote target, including the
+types of connections and their differences, how to set up executable and
+symbol files on the host and target, and the commands used for
+connecting to and disconnecting from the remote target.
+
+@subsection Types of Remote Connections
+
+@value{GDBN} supports two types of remote connections, @code{target remote}
+mode and @code{target extended-remote} mode. Note that many remote targets
+support only @code{target remote} mode. There are several major
+differences between the two types of connections, enumerated here:
+
+@table @asis
-@cindex @code{target remote}
+@cindex remote debugging, detach and program exit
+@item Result of detach or program exit
+@strong{With target remote mode:} When the debugged program exits or you
+detach from it, @value{GDBN} disconnects from the target. When using
+@code{gdbserver}, @code{gdbserver} will exit.
+
+@strong{With target extended-remote mode:} When the debugged program exits or
+you detach from it, @value{GDBN} remains connected to the target, even
+though no program is running. You can rerun the program, attach to a
+running program, or use @code{monitor} commands specific to the target.
+
+When using @code{gdbserver} in this case, it does not exit unless it was
+invoked using the @option{--once} option. If the @option{--once} option
+was not used, you can ask @code{gdbserver} to exit using the
+@code{monitor exit} command (@pxref{Monitor Commands for gdbserver}).
+
+@item Specifying the program to debug
+For both connection types you use the @code{file} command to specify the
+program on the host system. If you are using @code{gdbserver} there are
+some differences in how to specify the location of the program on the
+target.
+
+@strong{With target remote mode:} You must either specify the program to debug
+on the @code{gdbserver} command line or use the @option{--attach} option
+(@pxref{Attaching to a program,,Attaching to a Running Program}).
+
+@cindex @option{--multi}, @code{gdbserver} option
+@strong{With target extended-remote mode:} You may specify the program to debug
+on the @code{gdbserver} command line, or you can load the program or attach
+to it using @value{GDBN} commands after connecting to @code{gdbserver}.
+
+@anchor{--multi Option in Types of Remote Connnections}
+You can start @code{gdbserver} without supplying an initial command to run
+or process ID to attach. To do this, use the @option{--multi} command line
+option. Then you can connect using @code{target extended-remote} and start
+the program you want to debug (see below for details on using the
+@code{run} command in this scenario). Note that the conditions under which
+@code{gdbserver} terminates depend on how @value{GDBN} connects to it
+(@code{target remote} or @code{target extended-remote}). The
+@option{--multi} option to @code{gdbserver} has no influence on that.
+
+@item The @code{run} command
+@strong{With target remote mode:} The @code{run} command is not
+supported. Once a connection has been established, you can use all
+the usual @value{GDBN} commands to examine and change data. The
+remote program is already running, so you can use commands like
+@kbd{step} and @kbd{continue}.
+
+@strong{With target extended-remote mode:} The @code{run} command is
+supported. The @code{run} command uses the value set by
+@code{set remote exec-file} (@pxref{set remote exec-file}) to select
+the program to run. Command line arguments are supported, except for
+wildcard expansion and I/O redirection (@pxref{Arguments}).
+
+If you specify the program to debug on the command line, then the
+@code{run} command is not required to start execution, and you can
+resume using commands like @kbd{step} and @kbd{continue} as with
+@code{target remote} mode.
+
+@anchor{Attaching in Types of Remote Connections}
+@item Attaching
+@strong{With target remote mode:} The @value{GDBN} command @code{attach} is
+not supported. To attach to a running program using @code{gdbserver}, you
+must use the @option{--attach} option (@pxref{Running gdbserver}).
+
+@strong{With target extended-remote mode:} To attach to a running program,
+you may use the @code{attach} command after the connection has been
+established. If you are using @code{gdbserver}, you may also invoke
+@code{gdbserver} using the @option{--attach} option
+(@pxref{Running gdbserver}).
+
+@end table
+
+@anchor{Host and target files}
+@subsection Host and Target Files
+@cindex remote debugging, symbol files
+@cindex symbol files, remote debugging
+
+@value{GDBN}, running on the host, needs access to symbol and debugging
+information for your program running on the target. This requires
+access to an unstripped copy of your program, and possibly any associated
+symbol files. Note that this section applies equally to both @code{target
+remote} mode and @code{target extended-remote} mode.
+
+Some remote targets (@pxref{qXfer executable filename read}, and
+@pxref{Host I/O Packets}) allow @value{GDBN} to access program files over
+the same connection used to communicate with @value{GDBN}. With such a
+target, if the remote program is unstripped, the only command you need is
+@code{target remote} (or @code{target extended-remote}).
+
+If the remote program is stripped, or the target does not support remote
+program file access, start up @value{GDBN} using the name of the local
+unstripped copy of your program as the first argument, or use the
+@code{file} command. Use @code{set sysroot} to specify the location (on
+the host) of target libraries (unless your @value{GDBN} was compiled with
+the correct sysroot using @code{--with-sysroot}). Alternatively, you
+may use @code{set solib-search-path} to specify how @value{GDBN} locates
+target libraries.
+
+The symbol file and target libraries must exactly match the executable
+and libraries on the target, with one exception: the files on the host
+system should not be stripped, even if the files on the target system
+are. Mismatched or missing files will lead to confusing results
+during debugging. On @sc{gnu}/Linux targets, mismatched or missing
+files may also prevent @code{gdbserver} from debugging multi-threaded
+programs.
+
+@subsection Remote Connection Commands
+@cindex remote connection commands
@value{GDBN} can communicate with the target over a serial line, or
over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In
each case, @value{GDBN} uses the same protocol for debugging your
program; only the medium carrying the debugging packets varies. The
-@code{target remote} command establishes a connection to the target.
-Its arguments indicate which medium to use:
+@code{target remote} and @code{target extended-remote} commands
+establish a connection to the target. Both commands accept the same
+arguments, which indicate the medium to use:
@table @code
@item target remote @var{serial-device}
+@itemx target extended-remote @var{serial-device}
@cindex serial line, @code{target remote}
Use @var{serial-device} to communicate with the target. For example,
to use a serial line connected to the device named @file{/dev/ttyb}:
@item target remote @code{@var{host}:@var{port}}
@itemx target remote @code{tcp:@var{host}:@var{port}}
+@itemx target extended-remote @code{@var{host}:@var{port}}
+@itemx target extended-remote @code{tcp:@var{host}:@var{port}}
@cindex @acronym{TCP} port, @code{target remote}
Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
The @var{host} may be either a host name or a numeric @acronym{IP}
Note that the colon is still required here.
@item target remote @code{udp:@var{host}:@var{port}}
+@itemx target extended-remote @code{udp:@var{host}:@var{port}}
@cindex @acronym{UDP} port, @code{target remote}
Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
cause havoc with your debugging session.
@item target remote | @var{command}
+@itemx target extended-remote | @var{command}
@cindex pipe, @code{target remote} to
Run @var{command} in the background and communicate with it using a
pipe. The @var{command} is a shell command, to be parsed and expanded
@end table
-Once the connection has been established, you can use all the usual
-commands to examine and change data. The remote program is already
-running; you can use @kbd{step} and @kbd{continue}, and you do not
-need to use @kbd{run}.
-
@cindex interrupting remote programs
@cindex remote programs, interrupting
Whenever @value{GDBN} is waiting for the remote program, if you type the
Give up (and stop debugging it)? (y or n)
@end smallexample
-If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
-(If you decide you want to try again later, you can use @samp{target
-remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
-goes back to waiting.
+In @code{target remote} mode, if you type @kbd{y}, @value{GDBN} abandons
+the remote debugging session. (If you decide you want to try again later,
+you can use @kbd{target remote} again to connect once more.) If you type
+@kbd{n}, @value{GDBN} goes back to waiting.
+
+In @code{target extended-remote} mode, typing @kbd{n} will leave
+@value{GDBN} connected to the target.
@table @code
@kindex detach (remote)
@code{detach} command to release it from @value{GDBN} control.
Detaching from the target normally resumes its execution, but the results
will depend on your particular remote stub. After the @code{detach}
-command, @value{GDBN} is free to connect to another target.
+command in @code{target remote} mode, @value{GDBN} is free to connect to
+another target. In @code{target extended-remote} mode, @value{GDBN} is
+still connected to the target.
@kindex disconnect
@item disconnect
-The @code{disconnect} command behaves like @code{detach}, except that
+The @code{disconnect} command closes the connection to the target, and
the target is generally not resumed. It will wait for @value{GDBN}
(this instance or another one) to connect and continue debugging. After
the @code{disconnect} command, @value{GDBN} is again free to connect to
@cindex remote connection without stubs
@code{gdbserver} is a control program for Unix-like systems, which
allows you to connect your program with a remote @value{GDBN} via
-@code{target remote}---but without linking in the usual debugging stub.
+@code{target remote} or @code{target extended-remote}---but without
+linking in the usual debugging stub.
@code{gdbserver} is not a complete replacement for the debugging stubs,
because it requires essentially the same operating-system facilities
@code{gdbserver}.
@end quotation
+@anchor{Running gdbserver}
@subsection Running @code{gdbserver}
@cindex arguments, to @code{gdbserver}
@cindex @code{gdbserver}, command-line arguments
display through a pipe connected to gdbserver.
Both @code{stdout} and @code{stderr} use the same pipe.
+@anchor{Attaching to a program}
@subsubsection Attaching to a Running Program
@cindex attach to a program, @code{gdbserver}
@cindex @option{--attach}, @code{gdbserver} option
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 @code{gdbserver} at a binary for the running process.
+@var{pid} is the process ID of a currently running process. It isn't
+necessary to point @code{gdbserver} at a binary for the running process.
+
+In @code{target extended-remote} mode, you can also attach using the
+@value{GDBN} attach command
+(@pxref{Attaching in Types of Remote Connections}).
@pindex pidof
You can debug processes by name instead of process ID if your target has the
has multiple threads, most versions of @code{pidof} support the
@code{-s} option to only return the first process ID.
-@subsubsection Multi-Process Mode for @code{gdbserver}
-@cindex @code{gdbserver}, multiple processes
-@cindex multiple processes with @code{gdbserver}
-
-When you connect to @code{gdbserver} using @code{target remote},
-@code{gdbserver} debugs the specified program only once. When the
-program exits, or you detach from it, @value{GDBN} closes the connection
-and @code{gdbserver} exits.
-
-If you connect using @kbd{target extended-remote}, @code{gdbserver}
-enters multi-process mode. When the debugged program exits, or you
-detach from it, @value{GDBN} stays connected to @code{gdbserver} even
-though no program is running. The @code{run} and @code{attach}
-commands instruct @code{gdbserver} to run or attach to a new program.
-The @code{run} command uses @code{set remote exec-file} (@pxref{set
-remote exec-file}) to select the program to run. Command line
-arguments are supported, except for wildcard expansion and I/O
-redirection (@pxref{Arguments}).
-
-@cindex @option{--multi}, @code{gdbserver} option
-To start @code{gdbserver} without supplying an initial command to run
-or process ID to attach, use the @option{--multi} command line option.
-Then you can connect using @kbd{target extended-remote} and start
-the program you want to debug.
-
-In multi-process mode @code{gdbserver} does not automatically exit unless you
-use the option @option{--once}. You can terminate it by using
-@code{monitor exit} (@pxref{Monitor Commands for gdbserver}). Note that the
-conditions under which @code{gdbserver} terminates depend on how @value{GDBN}
-connects to it (@kbd{target remote} or @kbd{target extended-remote}). The
-@option{--multi} option to @code{gdbserver} has no influence on that.
-
@subsubsection TCP port allocation lifecycle of @code{gdbserver}
-This section applies only when @code{gdbserver} is run to listen on a TCP port.
+This section applies only when @code{gdbserver} is run to listen on a TCP
+port.
@code{gdbserver} normally terminates after all of its debugged processes have
terminated in @kbd{target remote} mode. On the other hand, for @kbd{target
@anchor{Other Command-Line Arguments for gdbserver}
@subsubsection Other Command-Line Arguments for @code{gdbserver}
+You can use the @option{--multi} option to start @code{gdbserver} without
+specifying a program to debug or a process to attach to. Then you can
+attach in @code{target extended-remote} mode and run or attach to a
+program. For more information,
+@pxref{--multi Option in Types of Remote Connnections}.
+
@cindex @option{--debug}, @code{gdbserver} option
The @option{--debug} option tells @code{gdbserver} to display extra
status information about the debugging process.
@subsection Connecting to @code{gdbserver}
-Run @value{GDBN} on the host system.
+The basic procedure for connecting to the remote target is:
+@itemize
-First make sure you have the necessary symbol files. Load symbols for
-your application using the @code{file} command before you connect. Use
-@code{set sysroot} to locate target libraries (unless your @value{GDBN}
-was compiled with the correct sysroot using @code{--with-sysroot}).
+@item
+Run @value{GDBN} on the host system.
-The symbol file and target libraries must exactly match the executable
-and libraries on the target, with one exception: the files on the host
-system should not be stripped, even if the files on the target system
-are. Mismatched or missing files will lead to confusing results
-during debugging. On @sc{gnu}/Linux targets, mismatched or missing
-files may also prevent @code{gdbserver} from debugging multi-threaded
-programs.
+@item
+Make sure you have the necessary symbol files
+(@pxref{Host and target files}).
+Load symbols for your application using the @code{file} command before you
+connect. Use @code{set sysroot} to locate target libraries (unless your
+@value{GDBN} was compiled with the correct sysroot using
+@code{--with-sysroot}).
+@item
Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}).
For TCP connections, you must start up @code{gdbserver} prior to using
-the @code{target remote} command. Otherwise you may get an error whose
+the @code{target} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
@samp{Connection refused}. Don't use the @code{load}
-command in @value{GDBN} when using @code{gdbserver}, since the program is
-already on the target.
+command in @value{GDBN} when using @code{target remote} mode, since the
+program is already on the target.
+
+@end itemize
+@anchor{Monitor Commands for gdbserver}
@subsection Monitor Commands for @code{gdbserver}
@cindex monitor commands, for @code{gdbserver}
-@anchor{Monitor Commands for gdbserver}
During a @value{GDBN} session using @code{gdbserver}, you can use the
@code{monitor} command to send special requests to @code{gdbserver}.
@item show serial baud
Show the current speed of the remote connection.
+@item set serial parity @var{parity}
+Set the parity for the remote serial I/O. Supported values of @var{parity} are:
+@code{even}, @code{none}, and @code{odd}. The default is @code{none}.
+
+@item show serial parity
+Show the current parity of the serial port.
+
@item set remotebreak
@cindex interrupt remote programs
@cindex BREAK signal instead of Ctrl-C
@tab @code{Z4}
@tab @code{awatch}
+@item @code{pid-to-exec-file}
+@tab @code{qXfer:exec-file:read}
+@tab @code{attach}, @code{run}
+
@item @code{target-features}
@tab @code{qXfer:features:read}
@tab @code{set architecture}
@tab @code{qSupported}
@tab Remote communications parameters
+@item @code{catch-syscalls}
+@tab @code{QCatchSyscalls}
+@tab @code{catch syscall}
+
@item @code{pass-signals}
@tab @code{QPassSignals}
@tab @code{handle @var{signal}}
@tab @code{vFile:readlink}
@tab Host I/O
+@item @code{hostio-fstat-packet}
+@tab @code{vFile:fstat}
+@tab Host I/O
+
+@item @code{hostio-setfs-packet}
+@tab @code{vFile:setfs}
+@tab Host I/O
+
@item @code{noack-packet}
@tab @code{QStartNoAckMode}
@tab Packet acknowledgment
@item @code{conditional-breakpoints-packet}
@tab @code{Z0 and Z1}
@tab @code{Support for target-side breakpoint condition evaluation}
+
+@item @code{multiprocess-extensions}
+@tab @code{multiprocess extensions}
+@tab Debug multiple processes and remote process PID awareness
+
+@item @code{swbreak-feature}
+@tab @code{swbreak stop reason}
+@tab @code{break}
+
+@item @code{hwbreak-feature}
+@tab @code{hwbreak stop reason}
+@tab @code{hbreak}
+
+@item @code{fork-event-feature}
+@tab @code{fork stop reason}
+@tab @code{fork}
+
+@item @code{vfork-event-feature}
+@tab @code{vfork stop reason}
+@tab @code{vfork}
+
+@item @code{exec-event-feature}
+@tab @code{exec stop reason}
+@tab @code{exec}
+
+@item @code{thread-events}
+@tab @code{QThreadEvents}
+@tab Tracking thread lifetime.
+
+@item @code{no-resumed-stop-reply}
+@tab @code{no resumed thread left stop reply}
+@tab Tracking thread lifetime.
+
@end multitable
@node Remote Stub
configurations.
@menu
-* HP-UX:: HP-UX
* BSD libkvm Interface:: Debugging BSD kernel memory images
* SVR4 Process Information:: SVR4 process information
* DJGPP Native:: Features specific to the DJGPP port
* Darwin:: Features specific to Darwin
@end menu
-@node HP-UX
-@subsection HP-UX
-
-On HP-UX systems, if you refer to a function or variable name that
-begins with a dollar sign, @value{GDBN} searches for a user or system
-name first, before it searches for a convenience variable.
-
-
@node BSD libkvm Interface
@subsection BSD libkvm Interface
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 and Solaris, but not HP-UX, for example.
+@sc{gnu}/Linux and Solaris, for example.
This command may also work on core files that were created on a system
that has the @samp{/proc} facility.
Thread Information Block (readable on the X86 CPU family using @code{$fs}
selector for 32-bit programs and @code{$gs} for 64-bit programs).
-@kindex info dll
-@item info dll
-This is a Cygwin-specific alias of @code{info shared}.
-
@kindex set cygwin-exceptions
@cindex debugging the Cygwin DLL
@cindex Cygwin DLL, debugging
@menu
-* ARM:: ARM RDI
-* M32R/D:: Renesas M32R/D
+* ARM:: ARM
+* M32R/SDI:: Renesas M32R/SDI
* M68K:: Motorola M68K
* MicroBlaze:: Xilinx MicroBlaze
* MIPS Embedded:: MIPS Embedded
* PowerPC Embedded:: PowerPC Embedded
-* PA:: HP PA Embedded
-* Sparclet:: Tsqware Sparclet
-* Sparclite:: Fujitsu Sparclite
-* Z8000:: Zilog Z8000
* AVR:: Atmel AVR
* CRIS:: CRIS
* Super-H:: Renesas Super-H
@node ARM
@subsection ARM
-@cindex ARM RDI
-
-@table @code
-@kindex target rdi
-@item target rdi @var{dev}
-ARM Angel monitor, via RDI library interface to ADP protocol. You may
-use this target to communicate with both boards running the Angel
-monitor, or with the EmbeddedICE JTAG debug device.
-
-@kindex target rdp
-@item target rdp @var{dev}
-ARM Demon monitor.
-
-@end table
@value{GDBN} provides the following ARM-specific commands:
Show whether ARM-specific debugging messages are enabled.
@end table
-The following commands are available when an ARM target is debugged
-using the RDI interface:
-
-@table @code
-@item rdilogfile @r{[}@var{file}@r{]}
-@kindex rdilogfile
-@cindex ADP (Angel Debugger Protocol) logging
-Set the filename for the ADP (Angel Debugger Protocol) packet log.
-With an argument, sets the log file to the specified @var{file}. With
-no argument, show the current log file name. The default log file is
-@file{rdi.log}.
-
-@item rdilogenable @r{[}@var{arg}@r{]}
-@kindex rdilogenable
-Control logging of ADP packets. With an argument of 1 or @code{"yes"}
-enables logging, with an argument 0 or @code{"no"} disables it. With
-no arguments displays the current setting. When logging is enabled,
-ADP packets exchanged between @value{GDBN} and the RDI target device
-are logged to a file.
-
-@item set rdiromatzero
-@kindex set rdiromatzero
-@cindex ROM at zero address, RDI
-Tell @value{GDBN} whether the target has ROM at address 0. If on,
-vector catching is disabled, so that zero address can be used. If off
-(the default), vector catching is enabled. For this command to take
-effect, it needs to be invoked prior to the @code{target rdi} command.
-
-@item show rdiromatzero
-@kindex show rdiromatzero
-Show the current setting of ROM at zero address.
-
-@item set rdiheartbeat
-@kindex set rdiheartbeat
-@cindex RDI heartbeat
-Enable or disable RDI heartbeat packets. It is not recommended to
-turn on this option, since it confuses ARM and EPI JTAG interface, as
-well as the Angel monitor.
-
-@item show rdiheartbeat
-@kindex show rdiheartbeat
-Show the setting of RDI heartbeat packets.
-@end table
-
@table @code
@item target sim @r{[}@var{simargs}@r{]} @dots{}
The @value{GDBN} ARM simulator accepts the following optional arguments.
@end table
@end table
-@node M32R/D
-@subsection Renesas M32R/D and M32R/SDI
-
-@table @code
-@kindex target m32r
-@item target m32r @var{dev}
-Renesas M32R/D ROM monitor.
-
-@kindex target m32rsdi
-@item target m32rsdi @var{dev}
-Renesas M32R SDI server, connected via parallel port to the board.
-@end table
-
-The following @value{GDBN} commands are specific to the M32R monitor:
-
-@table @code
-@item set download-path @var{path}
-@kindex set download-path
-@cindex find downloadable @sc{srec} files (M32R)
-Set the default path for finding downloadable @sc{srec} files.
-
-@item show download-path
-@kindex show download-path
-Show the default path for downloadable @sc{srec} files.
-
-@item set board-address @var{addr}
-@kindex set board-address
-@cindex M32-EVA target board address
-Set the IP address for the M32R-EVA target board.
-
-@item show board-address
-@kindex show board-address
-Show the current IP address of the target board.
-
-@item set server-address @var{addr}
-@kindex set server-address
-@cindex download server address (M32R)
-Set the IP address for the download server, which is the @value{GDBN}'s
-host machine.
-
-@item show server-address
-@kindex show server-address
-Display the IP address of the download server.
-
-@item upload @r{[}@var{file}@r{]}
-@kindex upload@r{, M32R}
-Upload the specified @sc{srec} @var{file} via the monitor's Ethernet
-upload capability. If no @var{file} argument is given, the current
-executable file is uploaded.
-
-@item tload @r{[}@var{file}@r{]}
-@kindex tload@r{, M32R}
-Test the @code{upload} command.
-@end table
+@node M32R/SDI
+@subsection Renesas M32R/SDI
The following commands are available for M32R/SDI:
@node M68K
@subsection M68k
-The Motorola m68k configuration includes ColdFire support, and a
-target command for the following ROM monitor.
-
-@table @code
-
-@kindex target dbug
-@item target dbug @var{dev}
-dBUG ROM monitor for Motorola ColdFire.
-
-@end table
+The Motorola m68k configuration includes ColdFire support.
@node MicroBlaze
@subsection MicroBlaze
@kindex target lsi @var{port}
LSI variant of PMON.
-@kindex target r3900
-@item target r3900 @var{dev}
-Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
-
-@kindex target array
-@item target array @var{dev}
-Array Tech LSI33K RAID controller board.
-
@end table
of scalar type, thus assuming that the variable is accessed through the
address of its first byte.
-@kindex target dink32
-@item target dink32 @var{dev}
-DINK32 ROM monitor.
-
-@kindex target ppcbug
-@item target ppcbug @var{dev}
-@kindex target ppcbug1
-@item target ppcbug1 @var{dev}
-PPCBUG ROM monitor for PowerPC.
-
-@kindex target sds
-@item target sds @var{dev}
-SDS monitor, running on a PowerPC board (such as Motorola's ADS).
-@end table
-
-@cindex SDS protocol
-The following commands specific to the SDS protocol are supported
-by @value{GDBN}:
-
-@table @code
-@item set sdstimeout @var{nsec}
-@kindex set sdstimeout
-Set the timeout for SDS protocol reads to be @var{nsec} seconds. The
-default is 2 seconds.
-
-@item show sdstimeout
-@kindex show sdstimeout
-Show the current value of the SDS timeout.
-
-@item sds @var{command}
-@kindex sds@r{, a command}
-Send the specified @var{command} string to the SDS monitor.
-@end table
-
-
-@node PA
-@subsection HP PA Embedded
-
-@table @code
-
-@kindex target op50n
-@item target op50n @var{dev}
-OP50N monitor, running on an OKI HPPA board.
-
-@kindex target w89k
-@item target w89k @var{dev}
-W89K monitor, running on a Winbond HPPA board.
-
-@end table
-
-@node Sparclet
-@subsection Tsqware Sparclet
-
-@cindex Sparclet
-
-@value{GDBN} enables developers to debug tasks running on
-Sparclet targets from a Unix host.
-@value{GDBN} uses code that runs on
-both the Unix host and on the Sparclet target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host.
-
-@table @code
-@item remotetimeout @var{args}
-@kindex remotetimeout
-@value{GDBN} supports the option @code{remotetimeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses.
-@end table
-
-@cindex compiling, on Sparclet
-When compiling for debugging, include the options @samp{-g} to get debug
-information and @samp{-Ttext} to relocate the program to where you wish to
-load it on the target. You may also want to add the options @samp{-n} or
-@samp{-N} in order to reduce the size of the sections. Example:
-
-@smallexample
-sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
-@end smallexample
-
-You can use @code{objdump} to verify that the addresses are what you intended:
-
-@smallexample
-sparclet-aout-objdump --headers --syms prog
-@end smallexample
-
-@cindex running, on Sparclet
-Once you have set
-your Unix execution search path to find @value{GDBN}, you are ready to
-run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
-(or @code{sparclet-aout-gdb}, depending on your installation).
-
-@value{GDBN} comes up showing the prompt:
-
-@smallexample
-(gdbslet)
-@end smallexample
-
-@menu
-* Sparclet File:: Setting the file to debug
-* Sparclet Connection:: Connecting to Sparclet
-* Sparclet Download:: Sparclet download
-* Sparclet Execution:: Running and debugging
-@end menu
-
-@node Sparclet File
-@subsubsection Setting File to Debug
-
-The @value{GDBN} command @code{file} lets you choose with program to debug.
-
-@smallexample
-(gdbslet) file prog
-@end smallexample
-
-@need 1000
-@value{GDBN} then attempts to read the symbol table of @file{prog}.
-@value{GDBN} locates
-the file by searching the directories listed in the command search
-path.
-If the file was compiled with debug information (option @samp{-g}), source
-files will be searched as well.
-@value{GDBN} locates
-the source files by searching the directories listed in the directory search
-path (@pxref{Environment, ,Your Program's Environment}).
-If it fails
-to find a file, it displays a message such as:
-
-@smallexample
-prog: No such file or directory.
-@end smallexample
-
-When this happens, add the appropriate directories to the search paths with
-the @value{GDBN} commands @code{path} and @code{dir}, and execute the
-@code{target} command again.
-
-@node Sparclet Connection
-@subsubsection Connecting to Sparclet
-
-The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
-To connect to a target on serial port ``@code{ttya}'', type:
-
-@smallexample
-(gdbslet) target sparclet /dev/ttya
-Remote target sparclet connected to /dev/ttya
-main () at ../prog.c:3
-@end smallexample
-
-@need 750
-@value{GDBN} displays messages like these:
-
-@smallexample
-Connected to ttya.
-@end smallexample
-
-@node Sparclet Download
-@subsubsection Sparclet Download
-
-@cindex download to Sparclet
-Once connected to the Sparclet target,
-you can use the @value{GDBN}
-@code{load} command to download the file from the host to the target.
-The file name and load offset should be given as arguments to the @code{load}
-command.
-Since the file format is aout, the program must be loaded to the starting
-address. You can use @code{objdump} to find out what this value is. The load
-offset is an offset which is added to the VMA (virtual memory address)
-of each of the file's sections.
-For instance, if the program
-@file{prog} was linked to text address 0x1201000, with data at 0x12010160
-and bss at 0x12010170, in @value{GDBN}, type:
-
-@smallexample
-(gdbslet) load prog 0x12010000
-Loading section .text, size 0xdb0 vma 0x12010000
-@end smallexample
-
-If the code is loaded at a different address then what the program was linked
-to, you may need to use the @code{section} and @code{add-symbol-file} commands
-to tell @value{GDBN} where to map the symbol table.
-
-@node Sparclet Execution
-@subsubsection Running and Debugging
-
-@cindex running and debugging Sparclet programs
-You can now begin debugging the task using @value{GDBN}'s execution control
-commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
-manual for the list of commands.
-
-@smallexample
-(gdbslet) b main
-Breakpoint 1 at 0x12010000: file prog.c, line 3.
-(gdbslet) run
-Starting program: prog
-Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
-3 char *symarg = 0;
-(gdbslet) step
-4 char *execarg = "hello!";
-(gdbslet)
-@end smallexample
-
-@node Sparclite
-@subsection Fujitsu Sparclite
-
-@table @code
-
-@kindex target sparclite
-@item target sparclite @var{dev}
-Fujitsu sparclite boards, used only for the purpose of loading.
-You must use an additional command to debug the program.
-For example: target remote @var{dev} using @value{GDBN} standard
-remote protocol.
-
@end table
-@node Z8000
-@subsection Zilog Z8000
-
-@cindex Z8000
-@cindex simulator, Z8000
-@cindex Zilog Z8000 simulator
-
-When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
-a Z8000 simulator.
-
-For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
-unsegmented variant of the Z8000 architecture) or the Z8001 (the
-segmented variant). The simulator recognizes which architecture is
-appropriate by inspecting the object code.
-
-@table @code
-@item target sim @var{args}
-@kindex sim
-@kindex target sim@r{, with Z8000}
-Debug programs on a simulated CPU. If the simulator supports setup
-options, specify them via @var{args}.
-@end table
-
-@noindent
-After specifying this target, you can debug programs for the simulated
-CPU in the same style as programs for your host computer; use the
-@code{file} command to load a new program image, the @code{run} command
-to run your program, and so on.
-
-As well as making available all the usual machine registers
-(@pxref{Registers, ,Registers}), the Z8000 simulator provides three
-additional items of information as specially named registers:
-
-@table @code
-
-@item cycles
-Counts clock-ticks in the simulator.
-
-@item insts
-Counts instructions run in the simulator.
-
-@item time
-Execution time in 60ths of a second.
-
-@end table
-
-You can refer to these values in @value{GDBN} expressions with the usual
-conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
-conditional breakpoint that suspends only after at least 5000
-simulated clock ticks.
-
@node AVR
@subsection Atmel AVR
@cindex AVR
from functions.
@end table
-@subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX).
-@cindex Intel(R) Memory Protection Extensions (MPX).
+
+@subsubsection Intel @dfn{Memory Protection Extensions} (MPX).
+@cindex Intel Memory Protection Extensions (MPX).
Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
@footnote{The register named with capital letters represent the architecture
Python, the display includes the memory size, in bits, accessible to
the pointer.
+Bounds can also be stored in bounds tables, which are stored in
+application memory. These tables store bounds for pointers by specifying
+the bounds pointer's value along with its bounds. Evaluating and changing
+bounds located in bound tables is therefore interesting while investigating
+bugs on MPX context. @value{GDBN} provides commands for this purpose:
+
+@table @code
+@item show mpx bound @var{pointer}
+@kindex show mpx bound
+Display bounds of the given @var{pointer}.
+
+@item set mpx bound @var{pointer}, @var{lbound}, @var{ubound}
+@kindex set mpx bound
+Set the bounds of a pointer in the bound table.
+This command takes three parameters: @var{pointer} is the pointers
+whose bounds are to be changed, @var{lbound} and @var{ubound} are new values
+for lower and upper bounds respectively.
+@end table
+
@node Alpha
@subsection Alpha
@cindex history size
@kindex set history size
-@cindex @env{HISTSIZE}, environment variable
+@cindex @env{GDBHISTSIZE}, 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. If @var{size}
-is @code{unlimited}, the number of commands @value{GDBN} keeps in the
-history list is unlimited.
+This defaults to the value of the environment variable @env{GDBHISTSIZE}, or
+to 256 if this variable is not set. Non-numeric values of @env{GDBHISTSIZE}
+are ignored. If @var{size} is @code{unlimited} or if @env{GDBHISTSIZE} is
+either a negative number or the empty string, then the number of commands
+@value{GDBN} keeps in the history list is unlimited.
+
+@cindex remove duplicate history
+@kindex set history remove-duplicates
+@item set history remove-duplicates @var{count}
+@itemx set history remove-duplicates unlimited
+Control the removal of duplicate history entries in the command history list.
+If @var{count} is non-zero, @value{GDBN} will look back at the last @var{count}
+history entries and remove the first entry that is a duplicate of the current
+entry being added to the command history list. If @var{count} is
+@code{unlimited} then this lookbehind is unbounded. If @var{count} is 0, then
+removal of duplicate history entries is disabled.
+
+Only history entries added during the current session are considered for
+removal. This option is set to 0 by default.
+
@end table
History expansion assigns special meaning to the character @kbd{!}.
@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.
+@item set debug dwarf-die
+@cindex DWARF DIEs
+Dump DWARF DIEs after they are read in.
The value is the number of nesting levels to print.
A value of zero turns off the display.
-@item show debug dwarf2-die
-Show the current state of DWARF2 DIE debugging.
-@item set debug dwarf2-read
-@cindex DWARF2 Reading
+@item show debug dwarf-die
+Show the current state of DWARF DIE debugging.
+@item set debug dwarf-line
+@cindex DWARF Line Tables
+Turns on or off display of debugging messages related to reading
+DWARF line tables. The default is 0 (off).
+A value of 1 provides basic information.
+A value greater than 1 provides more verbose information.
+@item show debug dwarf-line
+Show the current state of DWARF line table debugging.
+@item set debug dwarf-read
+@cindex DWARF Reading
Turns on or off display of debugging messages related to reading
DWARF debug info. The default is 0 (off).
A value of 1 provides basic information.
A value greater than 1 provides more verbose information.
-@item show debug dwarf2-read
-Show the current state of DWARF2 reader debugging.
+@item show debug dwarf-read
+Show the current state of DWARF reader debugging.
@item set debug displaced
@cindex displaced stepping debugging info
Turns on or off display of @value{GDBN} debugging info for the
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 linux-namespaces
+@cindex @sc{gnu}/Linux namespaces debug messages
+Turns on or off debugging messages from the Linux namespaces debug support.
+@item show debug linux-namespaces
+Show the current state of Linux namespaces debugging messages.
@item set debug mach-o
@cindex Mach-O symbols processing
Control display of debugging messages related to Mach-O symbols
The TUI mode is enabled by default when you invoke @value{GDBN} as
@samp{@value{GDBP} -tui}.
You can also switch in and out of TUI mode while @value{GDBN} runs by
-using various TUI commands and key bindings, such as @kbd{C-x C-a}.
-@xref{TUI Keys, ,TUI Key Bindings}.
+using various TUI commands and key bindings, such as @command{tui
+enable} or @kbd{C-x C-a}. @xref{TUI Commands, ,TUI Commands}, and
+@ref{TUI Keys, ,TUI Key Bindings}.
@node TUI Overview
@section TUI Overview
possible or desirable to enable curses window management.
@table @code
+@item tui enable
+@kindex tui enable
+Activate TUI mode. The last active TUI window layout will be used if
+TUI mode has prevsiouly been used in the current debugging session,
+otherwise a default layout is used.
+
+@item tui disable
+@kindex tui disable
+Disable TUI mode, returning to the console interpreter.
+
@item info win
@kindex info win
List and give the size of all displayed windows.
-@item layout next
+@item layout @var{name}
@kindex layout
+Changes which TUI windows are displayed. In each layout the command
+window is always displayed, the @var{name} parameter controls which
+additional windows are displayed, and can be any of the following:
+
+@table @code
+@item next
Display the next layout.
-@item layout prev
+@item prev
Display the previous layout.
-@item layout src
-Display the source window only.
+@item src
+Display the source and command windows.
-@item layout asm
-Display the assembly window only.
+@item asm
+Display the assembly and command windows.
-@item layout split
-Display the source and assembly window.
+@item split
+Display the source, assembly, and command windows.
-@item layout regs
-Display the register window together with the source or assembly window.
+@item regs
+When in @code{src} layout display the register, source, and command
+windows. When in @code{asm} or @code{split} layout display the
+register, assembler, and command windows.
+@end table
-@item focus next
+@item focus @var{name}
@kindex focus
+Changes which TUI window is currently active for scrolling. The
+@var{name} parameter can be any of the following:
+
+@table @code
+@item next
Make the next window active for scrolling.
-@item focus prev
+@item prev
Make the previous window active for scrolling.
-@item focus src
+@item src
Make the source window active for scrolling.
-@item focus asm
+@item asm
Make the assembly window active for scrolling.
-@item focus regs
+@item regs
Make the register window active for scrolling.
-@item focus cmd
+@item cmd
Make the command window active for scrolling.
+@end table
@item refresh
@kindex refresh
Refresh the screen. This is similar to typing @kbd{C-L}.
-@item tui reg float
+@item tui reg @var{group}
@kindex tui reg
-Show the floating point registers in the register window.
-
-@item tui reg general
-Show the general registers in the register window.
-
-@item tui reg next
-Show the next register group. The list of register groups as well as
-their order is target specific. The predefined register groups are the
-following: @code{general}, @code{float}, @code{system}, @code{vector},
-@code{all}, @code{save}, @code{restore}.
-
-@item tui reg system
-Show the system registers in the register window.
+Changes the register group displayed in the tui register window to
+@var{group}. If the register window is not currently displayed this
+command will cause the register window to be displayed. The list of
+register groups, as well as their order is target specific. The
+following groups are available on most targets:
+@table @code
+@item next
+Repeatedly selecting this group will cause the display to cycle
+through all of the available register groups.
+
+@item prev
+Repeatedly selecting this group will cause the display to cycle
+through all of the available register groups in the reverse order to
+@var{next}.
+
+@item general
+Display the general registers.
+@item float
+Display the floating point registers.
+@item system
+Display the system registers.
+@item vector
+Display the vector registers.
+@item all
+Display all registers.
+@end table
@item update
@kindex update
frontend may be operating on a wrong one. Therefore, each MI command
should explicitly specify which thread and frame to operate on. To
make it possible, each MI command accepts the @samp{--thread} and
-@samp{--frame} options, the value to each is @value{GDBN} identifier
-for thread and frame to operate on.
+@samp{--frame} options, the value to each is @value{GDBN} global
+identifier for thread and frame to operate on.
Usually, each top-level window in a frontend allows the user to select
a thread and a frame, and remembers the user selection for further
@table @code
@item *running,thread-id="@var{thread}"
-The target is now running. The @var{thread} field tells which
-specific thread is now running, and can be @samp{all} if all threads
-are running. The frontend should assume that no interaction with a
-running thread is possible after this notification is produced.
-The frontend should not assume that this notification is output
-only once for any command. @value{GDBN} may emit this notification
-several times, either for different threads, because it cannot resume
-all threads together, or even for a single thread, if the thread must
-be stepped though some code before letting it run freely.
+The target is now running. The @var{thread} field can be the global
+thread ID of the the thread that is now running, and it can be
+@samp{all} if all threads are running. The frontend should assume
+that no interaction with a running thread is possible after this
+notification is produced. The frontend should not assume that this
+notification is output only once for any command. @value{GDBN} may
+emit this notification several times, either for different threads,
+because it cannot resume all threads together, or even for a single
+thread, if the thread must be stepped though some code before letting
+it run freely.
@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}"
The target has stopped. The @var{reason} field can have one of the
@item syscall-entry
The inferior entered a system call. This is reported when @code{catch
syscall} (@pxref{Set Catchpoints}) has been used.
-@item syscall-entry
+@item syscall-return
The inferior returned from a system call. This is reported when
@code{catch syscall} (@pxref{Set Catchpoints}) has been used.
@item exec
(@pxref{Set Catchpoints}) has been used.
@end table
-The @var{id} field identifies the thread that directly caused the stop
--- for example by hitting a breakpoint. Depending on whether all-stop
+The @var{id} field identifies the global thread ID of the thread
+that directly caused the stop -- for example by hitting a breakpoint.
+Depending on whether all-stop
mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either
stop all threads, or only the thread that directly triggered the stop.
If all threads are stopped, the @var{stopped} field will have the
@item =thread-created,id="@var{id}",group-id="@var{gid}"
@itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
A thread either was created, or has exited. The @var{id} field
-contains the @value{GDBN} identifier of the thread. The @var{gid}
+contains the global @value{GDBN} identifier of the thread. The @var{gid}
field identifies the thread group this thread belongs to.
@item =thread-selected,id="@var{id}"
@table @code
@item id
-The numeric id assigned to the thread by @value{GDBN}. This field is
+The global numeric id assigned to the thread by @value{GDBN}. This field is
always present.
@item target-id
@subheading The @code{-break-insert} Command
@findex -break-insert
+@anchor{-break-insert}
@subsubheading Synopsis
@noindent
If specified, @var{location}, can be one of:
-@itemize @bullet
-@item function
-@c @item +offset
-@c @item -offset
-@c @item linenum
-@item filename:linenum
-@item filename:function
-@item *address
-@end itemize
+@table @var
+@item linespec location
+A linespec location. @xref{Linespec Locations}.
+
+@item explicit location
+An explicit location. @sc{gdb/mi} explicit locations are
+analogous to the CLI's explicit locations using the option names
+listed below. @xref{Explicit Locations}.
+
+@table @samp
+@item --source @var{filename}
+The source file name of the location. This option requires the use
+of either @samp{--function} or @samp{--line}.
+
+@item --function @var{function}
+The name of a function or method.
+@item --label @var{label}
+The name of a label.
+
+@item --line @var{lineoffset}
+An absolute or relative line offset from the start of the location.
+@end table
+
+@item address location
+An address location, *@var{address}. @xref{Address Locations}.
+@end table
+
+@noindent
The possible optional parameters of this command are:
@table @samp
@item -i @var{ignore-count}
Initialize the @var{ignore-count}.
@item -p @var{thread-id}
-Restrict the breakpoint to the specified @var{thread-id}.
+Restrict the breakpoint to the thread with the specified global
+@var{thread-id}.
@end table
@subsubheading Result
@end smallexample
@noindent
-If specified, @var{location}, can be one of:
-
-@itemize @bullet
-@item @var{function}
-@c @item +offset
-@c @item -offset
-@c @item @var{linenum}
-@item @var{filename}:@var{linenum}
-@item @var{filename}:function
-@item *@var{address}
-@end itemize
+If supplied, @var{location} may be specified the same way as for
+the @code{-break-insert} command. @xref{-break-insert}.
The possible optional parameters of this command are:
Set the ignore count of the breakpoint (@pxref{Conditions, ignore count})
to @var{ignore-count}.
@item -p @var{thread-id}
-Restrict the breakpoint to the specified @var{thread-id}.
+Restrict the breakpoint to the thread with the specified global
+@var{thread-id}.
@end table
@subsubheading Result
-thread-info [ @var{thread-id} ]
@end smallexample
-Reports information about either a specific thread, if
-the @var{thread-id} parameter is present, or about all
-threads. When printing information about all threads,
-also reports the current thread.
+Reports information about either a specific thread, if the
+@var{thread-id} parameter is present, or about all threads.
+@var{thread-id} is the thread's global thread ID. When printing
+information about all threads, also reports the global ID of the
+current thread.
@subsubheading @value{GDBN} Command
This field exists only for the current thread. It has the value @samp{*}.
@item id
-The identifier that @value{GDBN} uses to refer to the thread.
+The global identifier that @value{GDBN} uses to refer to the thread.
@item target-id
The identifier that the target uses to refer to the thread.
-thread-list-ids
@end smallexample
-Produces a list of the currently known @value{GDBN} thread ids. At the
-end of the list it also prints the total number of such threads.
+Produces a list of the currently known global @value{GDBN} thread ids.
+At the end of the list it also prints the total number of such
+threads.
This command is retained for historical reasons, the
@code{-thread-info} command should be used instead.
@subsubheading Synopsis
@smallexample
- -thread-select @var{threadnum}
+ -thread-select @var{thread-id}
@end smallexample
-Make @var{threadnum} the current thread. It prints the number of the new
-current thread, and the topmost frame for that thread.
+Make thread with global thread number @var{thread-id} the current
+thread. It prints the number of the new current thread, and the
+topmost frame for that thread.
This command is deprecated in favor of explicitly using the
@samp{--thread} option to each command.
The identifier that the target uses to refer to the Ada task.
@item thread-id
-The identifier of the thread corresponding to the Ada task.
+The global thread identifier of the thread corresponding to the Ada
+task.
This field should always exist, as Ada tasks are always implemented
on top of a thread. But if @value{GDBN} cannot find this corresponding
@item thread-id
If a variable object is bound to a specific thread, then this is the
-thread's identifier.
+thread's global identifier.
@item has_more
For a dynamic varobj, this indicates whether there appear to be any
@smallexample
@var{format-spec} @expansion{}
- @{binary | decimal | hexadecimal | octal | natural@}
+ @{binary | decimal | hexadecimal | octal | natural | zero-hexadecimal@}
@end smallexample
The natural format is the default format choosen automatically
based on the variable type (like decimal for an @code{int}, hex
for pointers, etc.).
+The zero-hexadecimal format has a representation similar to hexadecimal
+but with padding zeroes to the left of the value. For example, a 32-bit
+hexadecimal value of 0x1234 would be represented as 0x00001234 in the
+zero-hexadecimal format.
+
For a variable with children, the format is set only on the
variable itself, and the children are not affected.
If values were requested, this is the value.
@item thread-id
-If this variable object is associated with a thread, this is the thread id.
-Otherwise this result is not present.
+If this variable object is associated with a thread, this is the
+thread's global thread id. Otherwise this result is not present.
@item frozen
If the variable object is frozen, this variable will be present with a value of 1.
This section describes the @sc{gdb/mi} commands that manipulate data:
examine memory and registers, evaluate expressions, etc.
+For details about what an addressable memory unit is,
+@pxref{addressable memory unit}.
+
@c REMOVED FROM THE INTERFACE.
@c @subheading -data-assign
@c Change the value of a program variable. Plenty of side effects.
@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
are displayed.
@item @var{mode}
-is either 0 (meaning only disassembly), 1 (meaning mixed source and
-disassembly), 2 (meaning disassembly with raw opcodes), or 3 (meaning
-mixed source and disassembly with raw opcodes).
+is one of:
+@itemize @bullet
+@item 0 disassembly only
+@item 1 mixed source and disassembly (deprecated)
+@item 2 disassembly with raw opcodes
+@item 3 mixed source and disassembly with raw opcodes (deprecated)
+@item 4 mixed source and disassembly
+@item 5 mixed source and disassembly with raw opcodes
+@end itemize
+
+Modes 1 and 3 are deprecated. The output is ``source centric''
+which hasn't proved useful in practice.
+@xref{Machine Code}, for a discussion of the difference between
+@code{/m} and @code{/s} output of the @code{disassemble} command.
@end table
@subsubheading Result
The text disassembly for this @samp{address}.
@item opcodes
-This field is only present for mode 2. This contains the raw opcode
+This field is only present for modes 2, 3 and 5. This contains the raw opcode
bytes for the @samp{inst} field.
@end table
-For modes 1 and 3 the @samp{asm_insns} list contains tuples named
+For modes 1, 3, 4 and 5 the @samp{asm_insns} list contains tuples named
@samp{src_and_asm_line}, each of which has the following fields:
@table @code
@subsubheading Synopsis
@smallexample
- -data-read-memory-bytes [ -o @var{byte-offset} ]
+ -data-read-memory-bytes [ -o @var{offset} ]
@var{address} @var{count}
@end smallexample
@table @samp
@item @var{address}
-An expression specifying the address of the first memory word to be
-read. Complex expressions containing embedded white space should be
+An expression specifying the address of the first addressable memory unit
+to be read. Complex expressions containing embedded white space should be
quoted using the C convention.
@item @var{count}
-The number of bytes to read. This should be an integer literal.
+The number of addressable memory units to read. This should be an integer
+literal.
-@item @var{byte-offset}
-The offsets in bytes relative to @var{address} at which to start
-reading. This should be an integer literal. This option is provided
-so that a frontend is not required to first evaluate address and then
-perform address arithmetics itself.
+@item @var{offset}
+The offset relative to @var{address} at which to start reading. This
+should be an integer literal. This option is provided so that a frontend
+is not required to first evaluate address and then perform address
+arithmetics itself.
@end table
regions. For each one, if reading full region results in an errors,
@value{GDBN} will try to read a subset of the region.
-In general, every single byte in the region may be readable or not,
-and the only way to read every readable byte is to try a read at
+In general, every single memory unit in the region may be readable or not,
+and the only way to read every readable unit is to try a read at
every address, which is not practical. Therefore, @value{GDBN} will
-attempt to read all accessible bytes at either beginning or the end
+attempt to read all accessible memory units at either beginning or the end
of the region, using a binary division scheme. This heuristic works
well for reading accross a memory map boundary. Note that if a region
has a readable range that is neither at the beginning or the end,
@table @samp
@item @var{address}
-An expression specifying the address of the first memory word to be
-read. Complex expressions containing embedded white space should be
-quoted using the C convention.
+An expression specifying the address of the first addressable memory unit
+to be written. Complex expressions containing embedded white space should
+be quoted using the C convention.
@item @var{contents}
-The hex-encoded bytes to write.
+The hex-encoded data to write. It is an error if @var{contents} does
+not represent an integral number of addressable memory units.
@item @var{count}
-Optional argument indicating the number of bytes to be written. If @var{count}
-is greater than @var{contents}' length, @value{GDBN} will repeatedly
-write @var{contents} until it fills @var{count} bytes.
+Optional argument indicating the number of addressable memory units to be
+written. If @var{count} is greater than @var{contents}' length,
+@value{GDBN} will repeatedly write @var{contents} until it fills
+@var{count} memory units.
@end table
@smallexample
@value{GDBP}
-info-os
-^done,OSDataTable=@{nr_rows="9",nr_cols="3",
+^done,OSDataTable=@{nr_rows="10",nr_cols="3",
hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@},
@{width="10",alignment="-1",col_name="col1",colhdr="Description"@},
@{width="10",alignment="-1",col_name="col2",colhdr="Title"@}],
-body=[item=@{col0="processes",col1="Listing of all processes",
+body=[item=@{col0="cpus",col1="Listing of all cpus/cores on the system",
+ col2="CPUs"@},
+ item=@{col0="files",col1="Listing of all file descriptors",
+ col2="File descriptors"@},
+ item=@{col0="modules",col1="Listing of all loaded kernel modules",
+ col2="Kernel modules"@},
+ item=@{col0="msg",col1="Listing of all message queues",
+ col2="Message queues"@},
+ item=@{col0="processes",col1="Listing of all processes",
col2="Processes"@},
item=@{col0="procgroups",col1="Listing of all process groups",
col2="Process groups"@},
- item=@{col0="threads",col1="Listing of all threads",
- col2="Threads"@},
- item=@{col0="files",col1="Listing of all file descriptors",
- col2="File descriptors"@},
- item=@{col0="sockets",col1="Listing of all internet-domain sockets",
- col2="Sockets"@},
- item=@{col0="shm",col1="Listing of all shared-memory regions",
- col2="Shared-memory regions"@},
item=@{col0="semaphores",col1="Listing of all semaphores",
col2="Semaphores"@},
- item=@{col0="msg",col1="Listing of all message queues",
- col2="Message queues"@},
- item=@{col0="modules",col1="Listing of all loaded kernel modules",
- col2="Kernel modules"@}]@}
+ item=@{col0="shm",col1="Listing of all shared-memory regions",
+ col2="Shared-memory regions"@},
+ item=@{col0="sockets",col1="Listing of all internet-domain sockets",
+ col2="Sockets"@},
+ item=@{col0="threads",col1="Listing of all threads",
+ col2="Threads"@}]
@value{GDBP}
-info-os processes
^done,OSDataTable=@{nr_rows="190",nr_cols="4",
@end table
-@kindex maint info bfds
-@item maint info bfds
-This prints information about each @code{bfd} object that is known to
-@value{GDBN}. @xref{Top, , BFD, bfd, The Binary File Descriptor Library}.
+@kindex maint info btrace
+@item maint info btrace
+Pint information about raw branch tracing data.
+
+@kindex maint btrace packet-history
+@item maint btrace packet-history
+Print the raw branch trace packets that are used to compute the
+execution history for the @samp{record btrace} command. Both the
+information and the format in which it is printed depend on the btrace
+recording format.
+
+@table @code
+@item bts
+For the BTS recording format, print a list of blocks of sequential
+code. For each block, the following information is printed:
+
+@table @asis
+@item Block number
+Newer blocks have higher numbers. The oldest block has number zero.
+@item Lowest @samp{PC}
+@item Highest @samp{PC}
+@end table
+
+@item pt
+For the Intel Processor Trace recording format, print a list of
+Intel Processor Trace packets. For each packet, the following
+information is printed:
+
+@table @asis
+@item Packet number
+Newer packets have higher numbers. The oldest packet has number zero.
+@item Trace offset
+The packet's offset in the trace stream.
+@item Packet opcode and payload
+@end table
+@end table
+
+@kindex maint btrace clear-packet-history
+@item maint btrace clear-packet-history
+Discards the cached packet history printed by the @samp{maint btrace
+packet-history} command. The history will be computed again when
+needed.
+
+@kindex maint btrace clear
+@item maint btrace clear
+Discard the branch trace data. The data will be fetched anew and the
+branch trace will be recomputed when needed.
+
+This implicitly truncates the branch trace to a single branch trace
+buffer. When updating branch trace incrementally, the branch trace
+available to @value{GDBN} may be bigger than a single branch trace
+buffer.
+
+@kindex maint set btrace pt skip-pad
+@item maint set btrace pt skip-pad
+@kindex maint show btrace pt skip-pad
+@item maint show btrace pt skip-pad
+Control whether @value{GDBN} will skip PAD packets when computing the
+packet history.
@kindex set displaced-stepping
@kindex show displaced-stepping
Cause @value{GDBN} to call the internal function @code{internal_error},
@code{internal_warning} or @code{demangler_warning} and hence behave
-as though an internal problam has been detected. In addition to
+as though an internal problem has been detected. In addition to
reporting the internal problem, these functions give the user the
opportunity to either quit @value{GDBN} or (for @code{internal_error}
and @code{internal_warning}) create a core file of the current
a recursive definition of the data type as stored in @value{GDBN}'s
data structures, including its flags and contained types.
-@kindex maint set dwarf2 always-disassemble
-@kindex maint show dwarf2 always-disassemble
-@item maint set dwarf2 always-disassemble
-@item maint show dwarf2 always-disassemble
+@kindex maint set dwarf always-disassemble
+@kindex maint show dwarf always-disassemble
+@item maint set dwarf always-disassemble
+@item maint show dwarf always-disassemble
Control the behavior of @code{info address} when using DWARF debugging
information.
For more information on these expressions, see
@uref{http://www.dwarfstd.org/, the DWARF standard}.
-@kindex maint set dwarf2 max-cache-age
-@kindex maint show dwarf2 max-cache-age
-@item maint set dwarf2 max-cache-age
-@itemx maint show dwarf2 max-cache-age
-Control the DWARF 2 compilation unit cache.
+@kindex maint set dwarf max-cache-age
+@kindex maint show dwarf max-cache-age
+@item maint set dwarf max-cache-age
+@itemx maint show dwarf max-cache-age
+Control the DWARF compilation unit cache.
-@cindex DWARF 2 compilation units cache
+@cindex DWARF compilation units cache
In object files with inter-compilation-unit references, such as those
-produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
+produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF
reader needs to frequently refer to previously read compilation units.
This setting controls how long a compilation unit will remain in the
cache if it is not referenced. A higher limit means that cached
default is asynchronous, if it is available; but this can be changed
to more easily debug problems occurring only in synchronous mode.
+@kindex maint set target-non-stop @var{mode} [on|off|auto]
+@kindex maint show target-non-stop
+@item maint set target-non-stop
+@itemx maint show target-non-stop
+
+This controls whether @value{GDBN} targets always operate in non-stop
+mode even if @code{set non-stop} is @code{off} (@pxref{Non-Stop
+Mode}). The default is @code{auto}, meaning non-stop mode is enabled
+if supported by the target.
+
+@table @code
+@item maint set target-non-stop auto
+This is the default mode. @value{GDBN} controls the target in
+non-stop mode if the target supports it.
+
+@item maint set target-non-stop on
+@value{GDBN} controls the target in non-stop mode even if the target
+does not indicate support.
+
+@item maint set target-non-stop off
+@value{GDBN} does not control the target in non-stop mode even if the
+target supports it.
+@end table
+
@kindex maint set per-command
@kindex maint show per-command
@item maint set per-command
@item m @var{addr},@var{length}
@cindex @samp{m} packet
-Read @var{length} bytes of memory starting at address @var{addr}.
-Note that @var{addr} may not be aligned to any particular boundary.
+Read @var{length} addressable memory units starting at address @var{addr}
+(@pxref{addressable memory unit}). Note that @var{addr} may not be aligned to
+any particular boundary.
The stub need not use any particular size or alignment when gathering
data from memory for the response; even if @var{addr} is word-aligned
Reply:
@table @samp
@item @var{XX@dots{}}
-Memory contents; each byte is transmitted as a two-digit hexadecimal
-number. The reply may contain fewer bytes than requested if the
+Memory contents; each byte is transmitted as a two-digit hexadecimal number.
+The reply may contain fewer addressable memory units than requested if the
server was able to read only part of the region of memory.
@item E @var{NN}
@var{NN} is errno
@item M @var{addr},@var{length}:@var{XX@dots{}}
@cindex @samp{M} packet
-Write @var{length} bytes of memory starting at address @var{addr}.
-The data is given by @var{XX@dots{}}; each byte is transmitted as a two-digit
-hexadecimal number.
+Write @var{length} addressable memory units starting at address @var{addr}
+(@pxref{addressable memory unit}). The data is given by @var{XX@dots{}}; each
+byte is transmitted as a two-digit hexadecimal number.
Reply:
@table @samp
The @samp{vCont} packet is not supported.
@end table
+@anchor{vCtrlC packet}
+@item vCtrlC
+@cindex @samp{vCtrlC} packet
+Interrupt remote target as if a control-C was pressed on the remote
+terminal. This is the equivalent to reacting to the @code{^C}
+(@samp{\003}, the control-C character) character in all-stop mode
+while the target is running, except this works in non-stop mode.
+@xref{interrupting remote targets}, for more info on the all-stop
+variant.
+
+Reply:
+@table @samp
+@item E @var{nn}
+for an error
+@item OK
+for success
+@end table
+
@item vFile:@var{operation}:@var{parameter}@dots{}
@cindex @samp{vFile} packet
Perform a file operation on the target system. For details,
@anchor{X packet}
@cindex @samp{X} packet
Write data to memory, where the data is transmitted in binary.
-Memory is specified by its address @var{addr} and number of bytes @var{length};
+Memory is specified by its address @var{addr} and number of addressable memory
+units @var{length} (@pxref{addressable memory unit});
@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
Reply:
conditions that should be taken into consideration when deciding if
the breakpoint trigger should be reported back to @var{GDBN}.
+See also the @samp{swbreak} stop reason (@pxref{swbreak stop reason})
+for how to best report a memory breakpoint event to @value{GDBN}.
+
The @var{cond_list} parameter is comprised of a series of expressions,
concatenated without separators. Each expression has the following form:
The packet indicates a watchpoint hit, and @var{r} is the data address, in
hex.
+@item syscall_entry
+@itemx syscall_return
+The packet indicates a syscall entry or return, and @var{r} is the
+syscall number, in hex.
+
@cindex shared library events, remote reply
@item library
The packet indicates that the loaded libraries have changed.
beginning when executing backward) of the log. The value of @var{r}
will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
for more information.
+
+@item swbreak
+@anchor{swbreak stop reason}
+The packet indicates a memory breakpoint instruction was executed,
+irrespective of whether it was @value{GDBN} that planted the
+breakpoint or the breakpoint is hardcoded in the program. The @var{r}
+part must be left empty.
+
+On some architectures, such as x86, at the architecture level, when a
+breakpoint instruction executes the program counter points at the
+breakpoint address plus an offset. On such targets, the stub is
+responsible for adjusting the PC to point back at the breakpoint
+address.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+This packet is required for correct non-stop mode operation.
+
+@item hwbreak
+The packet indicates the target stopped for a hardware breakpoint.
+The @var{r} part must be left empty.
+
+The same remarks about @samp{qSupported} and non-stop mode above
+apply.
+
+@cindex fork events, remote reply
+@item fork
+The packet indicates that @code{fork} was called, and @var{r}
+is the thread ID of the new child process. Refer to
+@ref{thread-id syntax} for the format of the @var{thread-id}
+field. This packet is only applicable to targets that support
+fork events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex vfork events, remote reply
+@item vfork
+The packet indicates that @code{vfork} was called, and @var{r}
+is the thread ID of the new child process. Refer to
+@ref{thread-id syntax} for the format of the @var{thread-id}
+field. This packet is only applicable to targets that support
+vfork events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex vforkdone events, remote reply
+@item vforkdone
+The packet indicates that a child process created by a vfork
+has either called @code{exec} or terminated, so that the
+address spaces of the parent and child process are no longer
+shared. The @var{r} part is ignored. This packet is only
+applicable to targets that support vforkdone events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex exec events, remote reply
+@item exec
+The packet indicates that @code{execve} was called, and @var{r}
+is the absolute pathname of the file that was executed, in hex.
+This packet is only applicable to targets that support exec events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it. @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}). The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex thread create event, remote reply
+@anchor{thread create event}
+@item create
+The packet indicates that the thread was just created. The new thread
+is stopped until @value{GDBN} sets it running with a resumption packet
+(@pxref{vCont packet}). This packet should not be sent by default;
+@value{GDBN} requests it with the @ref{QThreadEvents} packet. See
+also the @samp{w} (@ref{thread exit event}) remote reply below.
+
@end table
@item W @var{AA}
support for multiprocess protocol extensions; see @ref{multiprocess
extensions}. The @var{pid} is formatted as a big-endian hex string.
+@anchor{thread exit event}
+@cindex thread exit event, remote reply
+@item w @var{AA} ; @var{tid}
+
+The thread exited, and @var{AA} is the exit status. This response
+should not be sent by default; @value{GDBN} requests it with the
+@ref{QThreadEvents} packet. See also @ref{thread create event} above.
+
+@item N
+There are no resumed threads left in the target. In other words, even
+though the process is alive, the last resumed thread has exited. For
+example, say the target process has two threads: thread 1 and thread
+2. The client leaves thread 1 stopped, and resumes thread 2, which
+subsequently exits. At this point, even though the process is still
+alive, and thus no @samp{W} stop reply is sent, no thread is actually
+executing either. The @samp{N} stop reply thus informs the client
+that it can stop waiting for stop replies. This packet should not be
+sent by default; older @value{GDBN} versions did not support it.
+@value{GDBN} requests it, by supplying an appropriate
+@samp{qSupported} feature (@pxref{qSupported}). The remote stub must
+also supply the appropriate @samp{qSupported} feature indicating
+support.
+
@item O @var{XX}@dots{}
@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be
written as the program's console output. This can happen at any time
Use of this packet is controlled by the @code{set non-stop} command;
@pxref{Non-Stop Mode}.
+@item QCatchSyscalls:1 @r{[};@var{sysno}@r{]}@dots{}
+@itemx QCatchSyscalls:0
+@cindex catch syscalls from inferior, remote request
+@cindex @samp{QCatchSyscalls} packet
+@anchor{QCatchSyscalls}
+Enable (@samp{QCatchSyscalls:1}) or disable (@samp{QCatchSyscalls:0})
+catching syscalls from the inferior process.
+
+For @samp{QCatchSyscalls:1}, each listed syscall @var{sysno} (encoded
+in hex) should be reported to @value{GDBN}. If no syscall @var{sysno}
+is listed, every system call should be reported.
+
+Note that if a syscall not in the list is reported, @value{GDBN} will
+still filter the event according to its own list from all corresponding
+@code{catch syscall} commands. However, it is more efficient to only
+report the requested syscalls.
+
+Multiple @samp{QCatchSyscalls:1} packets do not combine; any earlier
+@samp{QCatchSyscalls:1} list is completely replaced by the new list.
+
+If the inferior process execs, the state of @samp{QCatchSyscalls} is
+kept for the new process too. On targets where exec may affect syscall
+numbers, for example with exec between 32 and 64-bit processes, the
+client should send a new packet with the new syscall list.
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+
+@item @w{}
+An empty reply indicates that @samp{QCatchSyscalls} is not supported by
+the stub.
+@end table
+
+Use of this packet is controlled by the @code{set remote catch-syscalls}
+command (@pxref{Remote Configuration, set remote catch-syscalls}).
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
@cindex pass signals to inferior, remote request
@cindex @samp{QPassSignals} packet
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@anchor{QThreadEvents}
+@item QThreadEvents:1
+@itemx QThreadEvents:0
+@cindex thread create/exit events, remote request
+@cindex @samp{QThreadEvents} packet
+
+Enable (@samp{QThreadEvents:1}) or disable (@samp{QThreadEvents:0})
+reporting of thread create and exit events. @xref{thread create
+event}, for the reply specifications. For example, this is used in
+non-stop mode when @value{GDBN} stops a set of threads and
+synchronously waits for the their corresponding stop replies. Without
+exit events, if one of the threads exits, @value{GDBN} would hang
+forever not knowing that it should no longer expect a stop for that
+same thread. @value{GDBN} does not enable this feature unless the
+stub reports that it supports it by including @samp{QThreadEvents+} in
+its @samp{qSupported} reply.
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. The error number @var{nn} is given as hex digits.
+
+@item @w{}
+An empty reply indicates that @samp{QThreadEvents} is not supported by
+the stub.
+@end table
+
+Use of this packet is controlled by the @code{set remote thread-events}
+command (@pxref{Remote Configuration, set remote thread-events}).
+
@item qRcmd,@var{command}
@cindex execute remote command, remote request
@cindex @samp{qRcmd} packet
This feature indicates whether @value{GDBN} supports the
@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate
instruction reply packet}).
+
+@item swbreak
+This feature indicates whether @value{GDBN} supports the swbreak stop
+reason in stop replies. @xref{swbreak stop reason}, for details.
+
+@item hwbreak
+This feature indicates whether @value{GDBN} supports the hwbreak stop
+reason in stop replies. @xref{swbreak stop reason}, for details.
+
+@item fork-events
+This feature indicates whether @value{GDBN} supports fork event
+extensions to the remote protocol. @value{GDBN} does not use such
+extensions unless the stub also reports that it supports them by
+including @samp{fork-events+} in its @samp{qSupported} reply.
+
+@item vfork-events
+This feature indicates whether @value{GDBN} supports vfork event
+extensions to the remote protocol. @value{GDBN} does not use such
+extensions unless the stub also reports that it supports them by
+including @samp{vfork-events+} in its @samp{qSupported} reply.
+
+@item exec-events
+This feature indicates whether @value{GDBN} supports exec event
+extensions to the remote protocol. @value{GDBN} does not use such
+extensions unless the stub also reports that it supports them by
+including @samp{exec-events+} in its @samp{qSupported} reply.
+
+@item vContSupported
+This feature indicates whether @value{GDBN} wants to know the
+supported actions in the reply to @samp{vCont?} packet.
@end table
Stubs should ignore any unknown values for
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:exec-file:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:features:read}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab Yes
+@item @samp{Qbtrace:pt}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
@item @samp{Qbtrace-conf:bts:size}
@tab Yes
@tab @samp{-}
@tab Yes
+@item @samp{Qbtrace-conf:pt:size}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
@item @samp{QNonStop}
@tab No
@tab @samp{-}
@tab Yes
+@item @samp{QCatchSyscalls}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{QPassSignals}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{swbreak}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{hwbreak}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{fork-events}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{vfork-events}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{exec-events}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{QThreadEvents}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{no-resumed}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
The remote stub understands the @samp{qXfer:btrace-conf:read}
packet (@pxref{qXfer btrace-conf read}).
+@item qXfer:exec-file:read
+The remote stub understands the @samp{qXfer:exec-file:read} packet
+(@pxref{qXfer executable filename read}).
+
@item qXfer:features:read
The remote stub understands the @samp{qXfer:features:read} packet
(@pxref{qXfer target description read}).
The remote stub understands the @samp{QNonStop} packet
(@pxref{QNonStop}).
+@item QCatchSyscalls
+The remote stub understands the @samp{QCatchSyscalls} packet
+(@pxref{QCatchSyscalls}).
+
@item QPassSignals
The remote stub understands the @samp{QPassSignals} packet
(@pxref{QPassSignals}).
@item Qbtrace:bts
The remote stub understands the @samp{Qbtrace:bts} packet.
+@item Qbtrace:pt
+The remote stub understands the @samp{Qbtrace:pt} packet.
+
@item Qbtrace-conf:bts:size
The remote stub understands the @samp{Qbtrace-conf:bts:size} packet.
+@item Qbtrace-conf:pt:size
+The remote stub understands the @samp{Qbtrace-conf:pt:size} packet.
+
+@item swbreak
+The remote stub reports the @samp{swbreak} stop reason for memory
+breakpoints.
+
+@item hwbreak
+The remote stub reports the @samp{hwbreak} stop reason for hardware
+breakpoints.
+
+@item fork-events
+The remote stub reports the @samp{fork} stop reason for fork events.
+
+@item vfork-events
+The remote stub reports the @samp{vfork} stop reason for vfork events
+and vforkdone events.
+
+@item exec-events
+The remote stub reports the @samp{exec} stop reason for exec events.
+
+@item vContSupported
+The remote stub reports the supported actions in the reply to
+@samp{vCont?} packet.
+
+@item QThreadEvents
+The remote stub understands the @samp{QThreadEvents} packet.
+
+@item no-resumed
+The remote stub reports the @samp{N} stop reply.
+
@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:exec-file:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer executable filename read}
+Return the full absolute name of the file that was executed to create
+a process running on the remote system. The annex specifies the
+numeric process ID of the process to query, encoded as a hexadecimal
+number. If the annex part is empty the remote stub should return the
+filename corresponding to the currently executing process.
+
+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
@end table
@item Qbtrace:bts
-Enable branch tracing for the current thread using bts tracing.
+Enable branch tracing for the current thread using Branch Trace Store.
+
+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:pt
+Enable branch tracing for the current thread using Intel Processor Trace.
Reply:
@table @samp
A badly formed request or an error was encountered.
@end table
+@item Qbtrace-conf:pt:size=@var{value}
+Set the requested ring buffer size for new threads that use the
+btrace recording method in pt format.
+
+Reply:
+@table @samp
+@item OK
+The ring buffer size has been set.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
@end table
@node Architecture-Specific Protocol Details
which may be shorter than the length of @var{data}, or -1 if an
error occurred.
+@item vFile:fstat: @var{fd}
+Get information about the open file corresponding to @var{fd}.
+On success the information is returned as a binary attachment
+and the return value is the size of this attachment in bytes.
+If an error occurs the return value is -1. The format of the
+returned binary attachment is as described in @ref{struct stat}.
+
@item vFile:unlink: @var{filename}
Delete the file at @var{filename} on the target. Return 0,
or -1 if an error occurs. The @var{filename} is a string.
number of target bytes read; the binary attachment may be longer if
some characters were escaped.
+@item vFile:setfs: @var{pid}
+Select the filesystem on which @code{vFile} operations with
+@var{filename} arguments will operate. This is required for
+@value{GDBN} to be able to access files on remote targets where
+the remote stub does not share a common filesystem with the
+inferior(s).
+
+If @var{pid} is nonzero, select the filesystem as seen by process
+@var{pid}. If @var{pid} is zero, select the filesystem as seen by
+the remote stub. Return 0 on success, or -1 if an error occurs.
+If @code{vFile:setfs:} indicates success, the selected filesystem
+remains selected until the next successful @code{vFile:setfs:}
+operation.
+
@end table
@node Interrupts
@section Interrupts
@cindex interrupts (remote protocol)
+@anchor{interrupting remote targets}
-When a program on the remote target is running, @value{GDBN} may
-attempt to interrupt it by sending a @samp{Ctrl-C}, @code{BREAK} or
-a @code{BREAK} followed by @code{g},
-control of which is specified via @value{GDBN}'s @samp{interrupt-sequence}.
+In all-stop mode, when a program on the remote target is running,
+@value{GDBN} may attempt to interrupt it by sending a @samp{Ctrl-C},
+@code{BREAK} or a @code{BREAK} followed by @code{g}, control of which
+is specified via @value{GDBN}'s @samp{interrupt-sequence}.
The precise meaning of @code{BREAK} is defined by the transport
mechanism and may, in fact, be undefined. @value{GDBN} does not
When Linux kernel receives this sequence from serial port,
it stops execution and connects to gdb.
+In non-stop mode, because packet resumptions are asynchronous
+(@pxref{vCont packet}), @value{GDBN} is always free to send a remote
+command to the remote stub, even when the target is running. For that
+reason, @value{GDBN} instead sends a regular packet (@pxref{vCtrlC
+packet}) with the usual packet framing instead of the single byte
+@code{0x03}.
+
Stubs are not required to recognize these interrupt mechanisms and the
precise meaning associated with receipt of the interrupt is
implementation defined. If the target supports debugging of multiple
of successfully stopping the program in all-stop mode, and a stop reply
for each stopped thread in non-stop mode.
Interrupts received while the
-program is stopped are discarded.
+program is stopped are queued and the program will be interrupted when
+it is resumed next time.
@node Notification Packets
@section Notification Packets
or if the target is not attached to any process, it shall respond
@samp{OK}.
+If the stub supports non-stop mode, it should also support the
+@samp{swbreak} stop reason if software breakpoints are supported, and
+the @samp{hwbreak} stop reason if hardware breakpoints are supported
+(@pxref{swbreak stop reason}). This is because given the asynchronous
+nature of non-stop mode, between the time a thread hits a breakpoint
+and the time the event is finally processed by @value{GDBN}, the
+breakpoint may have already been removed from the target. Due to
+this, @value{GDBN} needs to be able to tell whether a trap stop was
+caused by a delayed breakpoint event, which should be ignored, as
+opposed to a random trap signal, which should be reported to the user.
+Note the @samp{swbreak} feature implies that the target is responsible
+for adjusting the PC when a software breakpoint triggers, if
+necessary, such as on the x86 architecture.
+
@node Packet Acknowledgment
@section Packet Acknowledgment
@smallexample
<?xml version="1.0"?>
<threads>
- <thread id="id" core="0">
+ <thread id="id" core="0" name="name">
... description ...
</thread>
</threads>
Each @samp{thread} element must have the @samp{id} attribute that
identifies the thread (@pxref{thread-id syntax}). The
@samp{core} attribute, if present, specifies which processor core
-the thread was last executing on. The content of the of @samp{thread}
-element is interpreted as human-readable auxilliary information.
+the thread was last executing on. The @samp{name} attribute, if
+present, specifies the human-readable name of the thread. The content
+of the of @samp{thread} element is interpreted as human-readable
+auxiliary information.
@node Traceframe Info Format
@section Traceframe Info Format
The formal DTD for the branch trace format is given below:
@smallexample
-<!ELEMENT btrace (block)* >
+<!ELEMENT btrace (block* | pt) >
<!ATTLIST btrace version CDATA #FIXED "1.0">
<!ELEMENT block EMPTY>
<!ATTLIST block begin CDATA #REQUIRED
end CDATA #REQUIRED>
+
+<!ELEMENT pt (pt-config?, raw?)>
+
+<!ELEMENT pt-config (cpu?)>
+
+<!ELEMENT cpu EMPTY>
+<!ATTLIST cpu vendor CDATA #REQUIRED
+ family CDATA #REQUIRED
+ model CDATA #REQUIRED
+ stepping CDATA #REQUIRED>
+
+<!ELEMENT raw (#PCDATA)>
@end smallexample
@node Branch Trace Configuration Format
@item size
The size of the @acronym{BTS} ring buffer in bytes.
@end table
+@item pt
+This thread uses the @dfn{Intel Processor Trace} (@acronym{Intel
+PT}) format.
+@table @code
+@item size
+The size of the @acronym{Intel PT} ring buffer in bytes.
+@end table
@end table
@value{GDBN} must be linked with the Expat library to support XML
The formal DTD for the branch trace configuration format is given below:
@smallexample
-<!ELEMENT btrace-conf (bts?)>
+<!ELEMENT btrace-conf (bts?, pt?)>
<!ATTLIST btrace-conf version CDATA #FIXED "1.0">
<!ELEMENT bts EMPTY>
<!ATTLIST bts size CDATA #IMPLIED>
+
+<!ELEMENT pt EMPTY>
+<!ATTLIST pt size CDATA #IMPLIED>
@end smallexample
@include agentexpr.texi
@samp{ymm0h} through @samp{ymm15h} for amd64
@end itemize
-The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel(R)
+The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel
Memory Protection Extension (MPX). It should describe the following registers:
@itemize @minus
contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct},
@samp{atia}, and @samp{tr0} through @samp{tr15}.
+The @samp{org.gnu.gdb.s390.vx} feature is optional. It should contain
+64-bit wide registers @samp{v0l} through @samp{v15l}, which will be
+combined by @value{GDBN} with the floating point registers @samp{f0}
+through @samp{f15} to present the 128-bit wide vector registers
+@samp{v0} through @samp{v15}. In addition, this feature should
+contain the 128-bit wide vector registers @samp{v16} through
+@samp{v31}.
+
@node TIC6x Features
@subsection TMS320C6x Features
@cindex target descriptions, TIC6x features
projects / deliverable / binutils-gdb.git / blobdiff