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
@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},
@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
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).
+The fork debugging commands are supported in both native mode and when
+connected to @code{gdbserver} using @kbd{target extended-remote}.
+
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
@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 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.
+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.
@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
+@item break @var{location} thread @var{threadno}
+@itemx break @var{location} thread @var{threadno} 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.
@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(R) Processor Trace
+Use the @dfn{Intel(R) 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(R)
+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(R) 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(R) 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.
-Here are all the different ways of specifying a code location that
-@value{GDBN} understands:
+@node Linespec Locations
+@subsection Linespec Locations
+@cindex linespec locations
+
+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
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
@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
#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
@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
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
-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.
+@value{GDBN} needs an unstripped copy of your program to access symbol
+and debugging information. 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}. Otherwise, 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.
@cindex @code{target remote}
@value{GDBN} can communicate with the target over a serial line, or
@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{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
@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}
@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
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).
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
@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
@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:
@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.
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(R) Processor Trace recording format, print a list of
+Intel(R) 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
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:
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
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
@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 @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}).
@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.
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(R) 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
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
@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(R) Processor Trace} (@acronym{Intel(R)
+PT}) format.
+@table @code
+@item size
+The size of the @acronym{Intel(R) 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
projects / deliverable / binutils-gdb.git / blobdiff