command files specified with @samp{-x} (and all commands from
initialization files, if not inhibited with @samp{-n}). Exit with
nonzero status if an error occurs in executing the @value{GDBN} commands
-in the command files.
+in the command files. Batch mode also disables pagination;
+@pxref{Screen Size} and acts as if @kbd{set confirm off} were in
+effect (@pxref{Messages/Warnings}).
Batch mode may be useful for running @value{GDBN} as a filter, for
example to download and run a program on another computer; in order to
@cindex @code{$_} and @code{info breakpoints}
@item info breakpoints @r{[}@var{n}@r{]}
@itemx info break @r{[}@var{n}@r{]}
-@itemx info watchpoints @r{[}@var{n}@r{]}
Print a table of all breakpoints, watchpoints, and catchpoints set and
not deleted. Optional argument @var{n} means print information only
about the specified breakpoint (or watchpoint or catchpoint). For
@kindex info watchpoints @r{[}@var{n}@r{]}
@item info watchpoints
-This command prints a list of watchpoints, breakpoints, and catchpoints;
-it is the same as @code{info break} (@pxref{Set Breaks}).
+This command prints a list of watchpoints, using the same format as
+@code{info break} (@pxref{Set Breaks}).
@end table
@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
and @sc{gnu}/Linux.
@item syscall
-@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @r{...}
+@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
@cindex break on a system call.
A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
syscall is a mechanism for application programs to request a service
that you can @dfn{enable} it again later.
You disable and enable breakpoints, watchpoints, and catchpoints with
-the @code{enable} and @code{disable} commands, optionally specifying one
-or more breakpoint numbers as arguments. Use @code{info break} or
-@code{info watch} to print a list of breakpoints, watchpoints, and
-catchpoints if you do not know which numbers to use.
+the @code{enable} and @code{disable} commands, optionally specifying
+one or more breakpoint numbers as arguments. Use @code{info break} to
+print a list of all breakpoints, watchpoints, and catchpoints if you
+do not know which numbers to use.
Disabling and enabling a breakpoint that has multiple locations
affects all of its locations.
@table @code
@kindex commands
@kindex end@r{ (breakpoint commands)}
-@item commands @r{[}@var{bnum}@r{]}
+@item commands @r{[}@var{range}@dots{}@r{]}
@itemx @dots{} @var{command-list} @dots{}
@itemx end
-Specify a list of commands for breakpoint number @var{bnum}. The commands
+Specify a list of commands for the given breakpoints. The commands
themselves appear on the following lines. Type a line containing just
@code{end} to terminate the commands.
To remove all commands from a breakpoint, type @code{commands} and
follow it immediately with @code{end}; that is, give no commands.
-With no @var{bnum} argument, @code{commands} refers to the last
-breakpoint, watchpoint, or catchpoint set (not to the breakpoint most
-recently encountered).
+With no argument, @code{commands} refers to the last breakpoint,
+watchpoint, or catchpoint set (not to the breakpoint most recently
+encountered). If the most recent breakpoints were set with a single
+command, then the @code{commands} will apply to all the breakpoints
+set by that command. This applies to breakpoints set by
+@code{rbreak}, and also applies when a single @code{break} command
+creates multiple breakpoints (@pxref{Ambiguous Expressions,,Ambiguous
+Expressions}).
@end table
Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
Like @code{nexti}, @code{reverse-nexti} executes a single instruction
in reverse, except that called functions are ``un-executed'' atomically.
That is, if the previously executed instruction was a return from
-another instruction, @code{reverse-nexti} will continue to execute
+another function, @code{reverse-nexti} will continue to execute
in reverse until the call to that function (from the current stack
frame) is reached.
command (abbreviated @code{p}), or its synonym @code{inspect}. It
evaluates and prints the value of an expression of the language your
program is written in (@pxref{Languages, ,Using @value{GDBN} with
-Different Languages}).
+Different Languages}). It may also print the expression using a
+Python-based pretty-printer (@pxref{Pretty Printing}).
@table @code
@item print @var{expr}
@item r
@cindex raw printing
Print using the @samp{raw} formatting. By default, @value{GDBN} will
-use a type-specific pretty-printer. The @samp{r} format bypasses any
-pretty-printer which might exist for the value's type.
+use a Python-based pretty-printer, if one is available (@pxref{Pretty
+Printing}). This typically results in a higher-level display of the
+value's contents. The @samp{r} format bypasses any Python
+pretty-printer which might exist.
@end table
For example, to print the program counter in hex (@pxref{Registers}), type
commands to examine the values these data had at the time the
tracepoint was hit.
-Tracepoints do not support every breakpoint feature. Conditional
-expressions and ignore counts on tracepoints have no effect, and
-tracepoints cannot run @value{GDBN} commands when they are
-hit. Tracepoints may not be thread-specific either.
+Tracepoints do not support every breakpoint feature. Ignore counts on
+tracepoints have no effect, and tracepoints cannot run @value{GDBN}
+commands when they are hit. Tracepoints may not be thread-specific
+either.
@cindex fast tracepoints
Some targets may support @dfn{fast tracepoints}, which are inserted in
* Tracepoint Actions::
* Listing Tracepoints::
* Starting and Stopping Trace Experiments::
+* Tracepoint Restrictions::
@end menu
@node Create and Delete Tracepoints
@code{actions} without bothering about its number). You specify the
actions themselves on the following lines, one action at a time, and
terminate the actions list with a line containing just @code{end}. So
-far, the only defined actions are @code{collect} and
+far, the only defined actions are @code{collect}, @code{teval}, and
@code{while-stepping}.
@cindex remove actions from a tracepoint
commands indicating the things to be collected when the tracepoint is
hit. Then, in order to single-step and collect additional data
following the tracepoint, a @code{while-stepping} command is used,
-followed by the list of things to be collected while stepping. The
-@code{while-stepping} command is terminated by its own separate
-@code{end} command. Lastly, the action list is terminated by an
-@code{end} command.
+followed by the list of things to be collected after each step in a
+sequence of single steps. The @code{while-stepping} command is
+terminated by its own separate @code{end} command. Lastly, the action
+list is terminated by an @code{end} command.
@smallexample
(@value{GDBP}) @b{trace foo}
@kindex while-stepping @r{(tracepoints)}
@item while-stepping @var{n}
-Perform @var{n} single-step traces after the tracepoint, collecting
-new data at each step. The @code{while-stepping} command is
-followed by the list of what to collect while stepping (followed by
-its own @code{end} command):
+Perform @var{n} single-step instruction traces after the tracepoint,
+collecting new data after each step. The @code{while-stepping}
+command is followed by the list of what to collect while stepping
+(followed by its own @code{end} command):
@smallexample
> while-stepping 12
@end smallexample
@noindent
-You may abbreviate @code{while-stepping} as @code{ws} or
+Note that @code{$pc} is not automatically collected by
+@code{while-stepping}; you need to explicitly collect that register if
+you need it. You may abbreviate @code{while-stepping} as @code{ws} or
@code{stepping}.
@item set default-collect @var{expr1}, @var{expr2}, @dots{}
necessarily heuristic, and it may result in useless tracepoints being
created; you may simply delete them if they are of no use.
+@cindex circular trace buffer
+If your target agent supports a @dfn{circular trace buffer}, then you
+can run a trace experiment indefinitely without filling the trace
+buffer; when space runs out, the agent deletes already-collected trace
+frames, oldest first, until there is enough room to continue
+collecting. This is especially useful if your tracepoints are being
+hit too often, and your trace gets terminated prematurely because the
+buffer is full. To ask for a circular trace buffer, simply set
+@samp{circular_trace_buffer} to on. You can set this at any time,
+including during tracing; if the agent can do it, it will change
+buffer handling on the fly, otherwise it will not take effect until
+the next run.
+
+@table @code
+@item set circular-trace-buffer on
+@itemx set circular-trace-buffer off
+@kindex set circular-trace-buffer
+Choose whether a tracing run should use a linear or circular buffer
+for trace data. A linear buffer will not lose any trace data, but may
+fill up prematurely, while a circular buffer will discard old trace
+data, but it will have always room for the latest tracepoint hits.
+
+@item show circular-trace-buffer
+@kindex show circular-trace-buffer
+Show the current choice for the trace buffer. Note that this may not
+match the agent's current buffer handling, nor is it guaranteed to
+match the setting that might have been in effect during a past run,
+for instance if you are looking at frames from a trace file.
+
+@end table
+
+@node Tracepoint Restrictions
+@subsection Tracepoint Restrictions
+
+@cindex tracepoint restrictions
+There are a number of restrictions on the use of tracepoints. As
+described above, tracepoint data gathering occurs on the target
+without interaction from @value{GDBN}. Thus the full capabilities of
+the debugger are not available during data gathering, and then at data
+examination time, you will be limited by only having what was
+collected. The following items describe some common problems, but it
+is not exhaustive, and you may run into additional difficulties not
+mentioned here.
+
+@itemize @bullet
+
+@item
+Tracepoint expressions are intended to gather objects (lvalues). Thus
+the full flexibility of GDB's expression evaluator is not available.
+You cannot call functions, cast objects to aggregate types, access
+convenience variables or modify values (except by assignment to trace
+state variables). Some language features may implicitly call
+functions (for instance Objective-C fields with accessors), and therefore
+cannot be collected either.
+
+@item
+Collection of local variables, either individually or in bulk with
+@code{$locals} or @code{$args}, during @code{while-stepping} may
+behave erratically. The stepping action may enter a new scope (for
+instance by stepping into a function), or the location of the variable
+may change (for instance it is loaded into a register). The
+tracepoint data recorded uses the location information for the
+variables that is correct for the tracepoint location. When the
+tracepoint is created, it is not possible, in general, to determine
+where the steps of a @code{while-stepping} sequence will advance the
+program---particularly if a conditional branch is stepped.
+
+@item
+Collection of an incompletely-initialized or partially-destroyed object
+may result in something that @value{GDBN} cannot display, or displays
+in a misleading way.
+
+@item
+When @value{GDBN} displays a pointer to character it automatically
+dereferences the pointer to also display characters of the string
+being pointed to. However, collecting the pointer during tracing does
+not automatically collect the string. You need to explicitly
+dereference the pointer and provide size information if you want to
+collect not only the pointer, but the memory pointed to. For example,
+@code{*ptr@@50} can be used to collect the 50 element array pointed to
+by @code{ptr}.
+
+@item
+It is not possible to collect a complete stack backtrace at a
+tracepoint. Instead, you may collect the registers and a few hundred
+bytes from the stack pointer with something like @code{*$esp@@300}
+(adjust to use the name of the actual stack pointer register on your
+target architecture, and the amount of stack you wish to capture).
+Then the @code{backtrace} command will show a partial backtrace when
+using a trace frame. The number of stack frames that can be examined
+depends on the sizes of the frames in the collected stack. Note that
+if you ask for a block so large that it goes past the bottom of the
+stack, the target agent may report an error trying to read from an
+invalid address.
+
+@item
+If you do not collect registers at a tracepoint, @value{GDBN} can
+infer that the value of @code{$pc} must be the same as the address of
+the tracepoint and use that when you are looking at a trace frame
+for that tracepoint. However, this cannot work if the tracepoint has
+multiple locations (for instance if it was set in a function that was
+inlined), or if it has a @code{while-stepping} loop. In those cases
+@value{GDBN} will warn you that it can't infer @code{$pc}, and default
+it to zero.
+
+@end itemize
+
@node Analyze Collected Data
@section Using the Collected Data
(@value{GDBP})
@end smallexample
+@code{tdump} works by scanning the tracepoint's current collection
+actions and printing the value of each expression listed. So
+@code{tdump} can fail, if after a run, you change the tracepoint's
+actions to mention variables that were not collected during the run.
+
+Also, for tracepoints with @code{while-stepping} loops, @code{tdump}
+uses the collected value of @code{$pc} to distinguish between trace
+frames that were collected at the tracepoint hit, and frames that were
+collected while stepping. This allows it to correctly choose whether
+to display the basic list of collections, or the collections from the
+body of the while-stepping loop. However, if @code{$pc} was not collected,
+then @code{tdump} will always attempt to dump using the basic collection
+list, and may fail if a while-stepping frame does not include all the
+same data that is collected at the tracepoint hit.
+@c This is getting pretty arcane, example would be good.
+
@node save-tracepoints
@subsection @code{save-tracepoints @var{filename}}
@kindex save-tracepoints
system, and you can put it somewhere in memory where it won't get
clobbered by the download.
-@item target sim
+@item target sim @r{[}@var{simargs}@r{]} @dots{}
@cindex built-in simulator target
Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
In general,
@item set new-console @var{mode}
If @var{mode} is @code{on} the debuggee will
be started in a new console on next start.
-If @var{mode} is @code{off}i, the debuggee will
+If @var{mode} is @code{off}, the debuggee will
be started in the same console as the debugger.
@kindex show new-console
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.
+
+@table @code
+@item --swi-support=@var{type}
+Tell the simulator which SWI interfaces to support.
+@var{type} may be a comma separated list of the following values.
+The default value is @code{all}.
+
+@table @code
+@item none
+@item demon
+@item angel
+@item redboot
+@item all
+@end table
+@end table
+@end table
@node M32R/D
@subsection Renesas M32R/D and M32R/SDI
@itemx set pagination off
@kindex set pagination
Turn the output pagination on or off; the default is on. Turning
-pagination off is the alternative to @code{set height 0}.
+pagination off is the alternative to @code{set height 0}. Note that
+running @value{GDBN} with the @option{--batch} option (@pxref{Mode
+Options, -batch}) also automatically disables pagination.
@item show pagination
@kindex show pagination
@cindex confirmation
@cindex stupid questions
@item set confirm off
-Disables confirmation requests.
+Disables confirmation requests. Note that running @value{GDBN} with
+the @option{--batch} option (@pxref{Mode Options, -batch}) also
+automatically disables confirmation requests.
@item set confirm on
Enables confirmation requests (the default).
@table @code
@kindex source
@cindex execute commands from a file
-@item source [@code{-v}] @var{filename}
+@item source [-s] [-v] @var{filename}
Execute the command file @var{filename}.
@end table
printed as they are executed. An error in any command terminates
execution of the command file and control is returned to the console.
-@value{GDBN} searches for @var{filename} in the current directory and then
-on the search path (specified with the @samp{directory} command).
+@value{GDBN} first searches for @var{filename} in the current directory.
+If the file is not found there, and @var{filename} does not specify a
+directory, then @value{GDBN} also looks for the file on the source search path
+(specified with the @samp{directory} command);
+except that @file{$cdir} is not searched because the compilation directory
+is not relevant to scripts.
+
+If @code{-s} is specified, then @value{GDBN} searches for @var{filename}
+on the search path even if @var{filename} specifies a directory.
+The search is done by appending @var{filename} to each element of the
+search path. So, for example, if @var{filename} is @file{mylib/myscript}
+and the search path contains @file{/home/user} then @value{GDBN} will
+look for the script @file{/home/user/mylib/myscript}.
+The search is also done if @var{filename} is an absolute path.
+For example, if @var{filename} is @file{/tmp/myscript} and
+the search path contains @file{/home/user} then @value{GDBN} will
+look for the script @file{/home/user/tmp/myscript}.
+For DOS-like systems, if @var{filename} contains a drive specification,
+it is stripped before concatenation. For example, if @var{filename} is
+@file{d:myscript} and the search path contains @file{c:/tmp} then @value{GDBN}
+will look for the script @file{c:/tmp/myscript}.
If @code{-v}, for verbose mode, is given then @value{GDBN} displays
each command as it is executed. The option must be given before
* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
* Commands In Python:: Implementing new commands in Python.
* Functions In Python:: Writing new convenience functions.
+* Progspaces In Python:: Program spaces.
* Objfiles In Python:: Object files.
-* Frames In Python:: Acessing inferior stack frames from Python.
+* Frames In Python:: Accessing inferior stack frames from Python.
+* Blocks In Python:: Accessing frame blocks from Python.
+* Symbols In Python:: Python representation of symbols.
+* Symbol Tables In Python:: Python representation of symbol tables.
* Lazy Strings In Python:: Python representation of lazy strings.
+* Breakpoints In Python:: Manipulating breakpoints using Python.
@end menu
@node Basic Python
It must be a boolean value. If omitted, it defaults to @code{False}.
@end defun
+@findex gdb.breakpoints
+@defun breakpoints
+Return a sequence holding all of @value{GDBN}'s breakpoints.
+@xref{Breakpoints In Python}, for more information.
+@end defun
+
@findex gdb.parameter
@defun parameter parameter
Return the value of a @value{GDBN} parameter. @var{parameter} is a
function.
@end defun
+@findex gdb.target_charset
+@defun target_charset
+Return the name of the current target character set (@pxref{Character
+Sets}). This differs from @code{gdb.parameter('target-charset')} in
+that @samp{auto} is never returned.
+@end defun
+
+@findex gdb.target_wide_charset
+@defun target_wide_charset
+Return the name of the current target wide character set
+(@pxref{Character Sets}). This differs from
+@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
+never returned.
+@end defun
+
@node Exception Handling
@subsubsection Exception Handling
@cindex python exceptions
@item maint set python auto-load [yes|no]
Enable or disable the Python auto-loading feature.
-@kindex show python auto-load
-@item show python auto-load
+@kindex maint show python auto-load
+@item maint show python auto-load
Show whether Python auto-loading is enabled or disabled.
@end table
This function looks up a type by name. @var{name} is the name of the
type to look up. It must be a string.
+If @var{block} is given, then @var{name} is looked up in that scope.
+Otherwise, it is searched for globally.
+
Ordinarily, this function will return an instance of @code{gdb.Type}.
If the named type cannot be found, it will throw an exception.
@end defun
exception.
@end defmethod
-@defmethod Type template_argument n
+@defmethod Type template_argument n [block]
If this @code{gdb.Type} is an instantiation of a template, this will
return a new @code{gdb.Type} which represents the type of the
@var{n}th template argument.
If this @code{gdb.Type} is not a template type, this will throw an
exception. Ordinarily, only C@t{++} code will have template types.
-@var{name} is searched for globally.
+If @var{block} is given, then @var{name} is looked up in that scope.
+Otherwise, it is searched for globally.
@end defmethod
@end table
pretty-printer. Python scalars (integers, floats, and booleans) and
strings are convertible to @code{gdb.Value}; other types are not.
+Finally, if this method returns @code{None} then no further operations
+are peformed in this method and nothing is printed.
+
If the result is not one of these types, an exception is raised.
@end defop
The Python list @code{gdb.pretty_printers} contains an array of
functions that have been registered via addition as a pretty-printer.
+Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
Each @code{gdb.Objfile} also contains a @code{pretty_printers}
attribute.
@code{None}.
@value{GDBN} first checks the @code{pretty_printers} attribute of each
-@code{gdb.Objfile} and iteratively calls each function in the list for
-that @code{gdb.Objfile} until it receives a pretty-printer object.
+@code{gdb.Objfile} in the current program space and iteratively calls
+each function in the list for that @code{gdb.Objfile} until it receives
+a pretty-printer object.
+If no pretty-printer is found in the objfile lists, @value{GDBN} then
+searches the pretty-printer list of the current program space,
+calling each function until an object is returned.
After these lists have been exhausted, it tries the global
@code{gdb.pretty-printers} list, again calling each function until an
object is returned.
Python code is read into @value{GDBN}, you may need to import the
@code{gdb} module explicitly.
+@node Progspaces In Python
+@subsubsection Program Spaces In Python
+
+@cindex progspaces in python
+@tindex gdb.Progspace
+@tindex Progspace
+A program space, or @dfn{progspace}, represents a symbolic view
+of an address space.
+It consists of all of the objfiles of the program.
+@xref{Objfiles In Python}.
+@xref{Inferiors and Programs, program spaces}, for more details
+about program spaces.
+
+The following progspace-related functions are available in the
+@code{gdb} module:
+
+@findex gdb.current_progspace
+@defun current_progspace
+This function returns the program space of the currently selected inferior.
+@xref{Inferiors and Programs}.
+@end defun
+
+@findex gdb.progspaces
+@defun progspaces
+Return a sequence of all the progspaces currently known to @value{GDBN}.
+@end defun
+
+Each progspace is represented by an instance of the @code{gdb.Progspace}
+class.
+
+@defivar Progspace filename
+The file name of the progspace as a string.
+@end defivar
+
+@defivar Progspace pretty_printers
+The @code{pretty_printers} attribute is a list of functions. It is
+used to look up pretty-printers. A @code{Value} is passed to each
+function in order; if the function returns @code{None}, then the
+search continues. Otherwise, the return value should be an object
+which is used to format the value. @xref{Pretty Printing}, for more
+information.
+@end defivar
+
@node Objfiles In Python
@subsubsection Objfiles In Python
@end defivar
@node Frames In Python
-@subsubsection Acessing inferior stack frames from Python.
+@subsubsection Accessing inferior stack frames from Python.
@cindex frames in python
When the debugged program stops, @value{GDBN} is able to analyze its call
Returns the frame's resume address.
@end defmethod
+@defmethod Frame block
+Return the frame's code block. @xref{Blocks In Python}.
+@end defmethod
+
+@defmethod Frame function
+Return the symbol for the function corresponding to this frame.
+@xref{Symbols In Python}.
+@end defmethod
+
@defmethod Frame older
Return the frame that called this frame.
@end defmethod
Return the frame called by this frame.
@end defmethod
-@defmethod Frame read_var variable
-Return the value of the given variable in this frame. @var{variable} must
-be a string.
+@defmethod Frame find_sal
+Return the frame's symtab and line object.
+@xref{Symbol Tables In Python}.
+@end defmethod
+
+@defmethod Frame read_var variable @r{[}block@r{]}
+Return the value of @var{variable} in this frame. If the optional
+argument @var{block} is provided, search for the variable from that
+block; otherwise start at the frame's current block (which is
+determined by the frame's current program counter). @var{variable}
+must be a string or a @code{gdb.Symbol} object. @var{block} must be a
+@code{gdb.Block} object.
+@end defmethod
+
+@defmethod Frame select
+Set this frame to be the selected frame. @xref{Stack, ,Examining the
+Stack}.
@end defmethod
@end table
+@node Blocks In Python
+@subsubsection Accessing frame blocks from Python.
+
+@cindex blocks in python
+@tindex gdb.Block
+
+Within each frame, @value{GDBN} maintains information on each block
+stored in that frame. These blocks are organized hierarchically, and
+are represented individually in Python as a @code{gdb.Block}.
+Please see @ref{Frames In Python}, for a more in-depth discussion on
+frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more
+detailed technical information on @value{GDBN}'s book-keeping of the
+stack.
+
+The following block-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.block_for_pc
+@defun block_for_pc pc
+Return the @code{gdb.Block} containing the given @var{pc} value. If the
+block cannot be found for the @var{pc} value specified, the function
+will return @code{None}.
+@end defun
+
+A @code{gdb.Block} object has the following attributes:
+
+@table @code
+@defivar Block start
+The start address of the block. This attribute is not writable.
+@end defivar
+
+@defivar Block end
+The end address of the block. This attribute is not writable.
+@end defivar
+
+@defivar Block function
+The name of the block represented as a @code{gdb.Symbol}. If the
+block is not named, then this attribute holds @code{None}. This
+attribute is not writable.
+@end defivar
+
+@defivar Block superblock
+The block containing this block. If this parent block does not exist,
+this attribute holds @code{None}. This attribute is not writable.
+@end defivar
+@end table
+
+@node Symbols In Python
+@subsubsection Python representation of Symbols.
+
+@cindex symbols in python
+@tindex gdb.Symbol
+
+@value{GDBN} represents every variable, function and type as an
+entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
+Similarly, Python represents these symbols in @value{GDBN} with the
+@code{gdb.Symbol} object.
+
+The following symbol-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.lookup_symbol
+@defun lookup_symbol name [block] [domain]
+This function searches for a symbol by name. The search scope can be
+restricted to the parameters defined in the optional domain and block
+arguments.
+
+@var{name} is the name of the symbol. It must be a string. The
+optional @var{block} argument restricts the search to symbols visible
+in that @var{block}. The @var{block} argument must be a
+@code{gdb.Block} object. The optional @var{domain} argument restricts
+the search to the domain type. The @var{domain} argument must be a
+domain constant defined in the @code{gdb} module and described later
+in this chapter.
+@end defun
+
+A @code{gdb.Symbol} object has the following attributes:
+
+@table @code
+@defivar Symbol symtab
+The symbol table in which the symbol appears. This attribute is
+represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
+Python}. This attribute is not writable.
+@end defivar
+
+@defivar Symbol name
+The name of the symbol as a string. This attribute is not writable.
+@end defivar
+
+@defivar Symbol linkage_name
+The name of the symbol, as used by the linker (i.e., may be mangled).
+This attribute is not writable.
+@end defivar
+
+@defivar Symbol print_name
+The name of the symbol in a form suitable for output. This is either
+@code{name} or @code{linkage_name}, depending on whether the user
+asked @value{GDBN} to display demangled or mangled names.
+@end defivar
+
+@defivar Symbol addr_class
+The address class of the symbol. This classifies how to find the value
+of a symbol. Each address class is a constant defined in the
+@code{gdb} module and described later in this chapter.
+@end defivar
+
+@defivar Symbol is_argument
+@code{True} if the symbol is an argument of a function.
+@end defivar
+
+@defivar Symbol is_constant
+@code{True} if the symbol is a constant.
+@end defivar
+
+@defivar Symbol is_function
+@code{True} if the symbol is a function or a method.
+@end defivar
+
+@defivar Symbol is_variable
+@code{True} if the symbol is a variable.
+@end defivar
+@end table
+
+The available domain categories in @code{gdb.Symbol} are represented
+as constants in the @code{gdb} module:
+
+@table @code
+@findex SYMBOL_UNDEF_DOMAIN
+@findex gdb.SYMBOL_UNDEF_DOMAIN
+@item SYMBOL_UNDEF_DOMAIN
+This is used when a domain has not been discovered or none of the
+following domains apply. This usually indicates an error either
+in the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_VAR_DOMAIN
+@findex gdb.SYMBOL_VAR_DOMAIN
+@item SYMBOL_VAR_DOMAIN
+This domain contains variables, function names, typedef names and enum
+type values.
+@findex SYMBOL_STRUCT_DOMAIN
+@findex gdb.SYMBOL_STRUCT_DOMAIN
+@item SYMBOL_STRUCT_DOMAIN
+This domain holds struct, union and enum type names.
+@findex SYMBOL_LABEL_DOMAIN
+@findex gdb.SYMBOL_LABEL_DOMAIN
+@item SYMBOL_LABEL_DOMAIN
+This domain contains names of labels (for gotos).
+@findex SYMBOL_VARIABLES_DOMAIN
+@findex gdb.SYMBOL_VARIABLES_DOMAIN
+@item SYMBOL_VARIABLES_DOMAIN
+This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
+contains everything minus functions and types.
+@findex SYMBOL_FUNCTIONS_DOMAIN
+@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
+@item SYMBOL_FUNCTION_DOMAIN
+This domain contains all functions.
+@findex SYMBOL_TYPES_DOMAIN
+@findex gdb.SYMBOL_TYPES_DOMAIN
+@item SYMBOL_TYPES_DOMAIN
+This domain contains all types.
+@end table
+
+The available address class categories in @code{gdb.Symbol} are represented
+as constants in the @code{gdb} module:
+
+@table @code
+@findex SYMBOL_LOC_UNDEF
+@findex gdb.SYMBOL_LOC_UNDEF
+@item SYMBOL_LOC_UNDEF
+If this is returned by address class, it indicates an error either in
+the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_LOC_CONST
+@findex gdb.SYMBOL_LOC_CONST
+@item SYMBOL_LOC_CONST
+Value is constant int.
+@findex SYMBOL_LOC_STATIC
+@findex gdb.SYMBOL_LOC_STATIC
+@item SYMBOL_LOC_STATIC
+Value is at a fixed address.
+@findex SYMBOL_LOC_REGISTER
+@findex gdb.SYMBOL_LOC_REGISTER
+@item SYMBOL_LOC_REGISTER
+Value is in a register.
+@findex SYMBOL_LOC_ARG
+@findex gdb.SYMBOL_LOC_ARG
+@item SYMBOL_LOC_ARG
+Value is an argument. This value is at the offset stored within the
+symbol inside the frame's argument list.
+@findex SYMBOL_LOC_REF_ARG
+@findex gdb.SYMBOL_LOC_REF_ARG
+@item SYMBOL_LOC_REF_ARG
+Value address is stored in the frame's argument list. Just like
+@code{LOC_ARG} except that the value's address is stored at the
+offset, not the value itself.
+@findex SYMBOL_LOC_REGPARM_ADDR
+@findex gdb.SYMBOL_LOC_REGPARM_ADDR
+@item SYMBOL_LOC_REGPARM_ADDR
+Value is a specified register. Just like @code{LOC_REGISTER} except
+the register holds the address of the argument instead of the argument
+itself.
+@findex SYMBOL_LOC_LOCAL
+@findex gdb.SYMBOL_LOC_LOCAL
+@item SYMBOL_LOC_LOCAL
+Value is a local variable.
+@findex SYMBOL_LOC_TYPEDEF
+@findex gdb.SYMBOL_LOC_TYPEDEF
+@item SYMBOL_LOC_TYPEDEF
+Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
+have this class.
+@findex SYMBOL_LOC_BLOCK
+@findex gdb.SYMBOL_LOC_BLOCK
+@item SYMBOL_LOC_BLOCK
+Value is a block.
+@findex SYMBOL_LOC_CONST_BYTES
+@findex gdb.SYMBOL_LOC_CONST_BYTES
+@item SYMBOL_LOC_CONST_BYTES
+Value is a byte-sequence.
+@findex SYMBOL_LOC_UNRESOLVED
+@findex gdb.SYMBOL_LOC_UNRESOLVED
+@item SYMBOL_LOC_UNRESOLVED
+Value is at a fixed address, but the address of the variable has to be
+determined from the minimal symbol table whenever the variable is
+referenced.
+@findex SYMBOL_LOC_OPTIMIZED_OUT
+@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
+@item SYMBOL_LOC_OPTIMIZED_OUT
+The value does not actually exist in the program.
+@findex SYMBOL_LOC_COMPUTED
+@findex gdb.SYMBOL_LOC_COMPUTED
+@item SYMBOL_LOC_COMPUTED
+The value's address is a computed location.
+@end table
+
+@node Symbol Tables In Python
+@subsubsection Symbol table representation in Python.
+
+@cindex symbol tables in python
+@tindex gdb.Symtab
+@tindex gdb.Symtab_and_line
+
+Access to symbol table data maintained by @value{GDBN} on the inferior
+is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
+@code{gdb.Symtab}. Symbol table and line data for a frame is returned
+from the @code{find_sal} method in @code{gdb.Frame} object.
+@xref{Frames In Python}.
+
+For more information on @value{GDBN}'s symbol table management, see
+@ref{Symbols, ,Examining the Symbol Table}, for more information.
+
+A @code{gdb.Symtab_and_line} object has the following attributes:
+
+@table @code
+@defivar Symtab_and_line symtab
+The symbol table object (@code{gdb.Symtab}) for this frame.
+This attribute is not writable.
+@end defivar
+
+@defivar Symtab_and_line pc
+Indicates the current program counter address. This attribute is not
+writable.
+@end defivar
+
+@defivar Symtab_and_line line
+Indicates the current line number for this object. This
+attribute is not writable.
+@end defivar
+@end table
+
+A @code{gdb.Symtab} object has the following attributes:
+
+@table @code
+@defivar Symtab filename
+The symbol table's source filename. This attribute is not writable.
+@end defivar
+
+@defivar Symtab objfile
+The symbol table's backing object file. @xref{Objfiles In Python}.
+This attribute is not writable.
+@end defivar
+@end table
+
+The following methods are provided:
+
+@table @code
+@defmethod Symtab fullname
+Return the symbol table's source absolute file name.
+@end defmethod
+@end table
+
+@node Breakpoints In Python
+@subsubsection Manipulating breakpoints using Python
+
+@cindex breakpoints in python
+@tindex gdb.Breakpoint
+
+Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
+class.
+
+@defmethod Breakpoint __init__ spec @r{[}type@r{]} @r{[}wp_class@r{]}
+Create a new breakpoint. @var{spec} is a string naming the
+location of the breakpoint, or an expression that defines a
+watchpoint. The contents can be any location recognized by the
+@code{break} command, or in the case of a watchpoint, by the @code{watch}
+command. The optional @var{type} denotes the breakpoint to create
+from the types defined later in this chapter. This argument can be
+either: @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}. @var{type}
+defaults to @code{BP_BREAKPOINT}. The optional @var{wp_class}
+argument defines the class of watchpoint to create, if @var{type} is
+defined as @code{BP_WATCHPOINT}. If a watchpoint class is not
+provided, it is assumed to be a @var{WP_WRITE} class.
+@end defmethod
+
+The available watchpoint types represented by constants are defined in the
+@code{gdb} module:
+
+@table @code
+@findex WP_READ
+@findex gdb.WP_READ
+@item WP_READ
+Read only watchpoint.
+
+@findex WP_WRITE
+@findex gdb.WP_WRITE
+@item WP_WRITE
+Write only watchpoint.
+
+@findex WP_ACCESS
+@findex gdb.WP_ACCESS
+@item WP_ACCESS
+Read/Write watchpoint.
+@end table
+
+@defmethod Breakpoint is_valid
+Return @code{True} if this @code{Breakpoint} object is valid,
+@code{False} otherwise. A @code{Breakpoint} object can become invalid
+if the user deletes the breakpoint. In this case, the object still
+exists, but the underlying breakpoint does not. In the cases of
+watchpoint scope, the watchpoint remains valid even if execution of the
+inferior leaves the scope of that watchpoint.
+@end defmethod
+
+@defivar Breakpoint enabled
+This attribute is @code{True} if the breakpoint is enabled, and
+@code{False} otherwise. This attribute is writable.
+@end defivar
+
+@defivar Breakpoint silent
+This attribute is @code{True} if the breakpoint is silent, and
+@code{False} otherwise. This attribute is writable.
+
+Note that a breakpoint can also be silent if it has commands and the
+first command is @code{silent}. This is not reported by the
+@code{silent} attribute.
+@end defivar
+
+@defivar Breakpoint thread
+If the breakpoint is thread-specific, this attribute holds the thread
+id. If the breakpoint is not thread-specific, this attribute is
+@code{None}. This attribute is writable.
+@end defivar
+
+@defivar Breakpoint task
+If the breakpoint is Ada task-specific, this attribute holds the Ada task
+id. If the breakpoint is not task-specific (or the underlying
+language is not Ada), this attribute is @code{None}. This attribute
+is writable.
+@end defivar
+
+@defivar Breakpoint ignore_count
+This attribute holds the ignore count for the breakpoint, an integer.
+This attribute is writable.
+@end defivar
+
+@defivar Breakpoint number
+This attribute holds the breakpoint's number --- the identifier used by
+the user to manipulate the breakpoint. This attribute is not writable.
+@end defivar
+
+@defivar Breakpoint type
+This attribute holds the breakpoint's type --- the identifier used to
+determine the actual breakpoint type or use-case. This attribute is not
+writable.
+@end defivar
+
+The available types are represented by constants defined in the @code{gdb}
+module:
+
+@table @code
+@findex BP_BREAKPOINT
+@findex gdb.BP_BREAKPOINT
+@item BP_BREAKPOINT
+Normal code breakpoint.
+
+@findex BP_WATCHPOINT
+@findex gdb.BP_WATCHPOINT
+@item BP_WATCHPOINT
+Watchpoint breakpoint.
+
+@findex BP_HARDWARE_WATCHPOINT
+@findex gdb.BP_HARDWARE_WATCHPOINT
+@item BP_HARDWARE_WATCHPOINT
+Hardware assisted watchpoint.
+
+@findex BP_READ_WATCHPOINT
+@findex gdb.BP_READ_WATCHPOINT
+@item BP_READ_WATCHPOINT
+Hardware assisted read watchpoint.
+
+@findex BP_ACCESS_WATCHPOINT
+@findex gdb.BP_ACCESS_WATCHPOINT
+@item BP_ACCESS_WATCHPOINT
+Hardware assisted access watchpoint.
+@end table
+
+@defivar Breakpoint hit_count
+This attribute holds the hit count for the breakpoint, an integer.
+This attribute is writable, but currently it can only be set to zero.
+@end defivar
+
+@defivar Breakpoint location
+This attribute holds the location of the breakpoint, as specified by
+the user. It is a string. If the breakpoint does not have a location
+(that is, it is a watchpoint) the attribute's value is @code{None}. This
+attribute is not writable.
+@end defivar
+
+@defivar Breakpoint expression
+This attribute holds a breakpoint expression, as specified by
+the user. It is a string. If the breakpoint does not have an
+expression (the breakpoint is not a watchpoint) the attribute's value
+is @code{None}. This attribute is not writable.
+@end defivar
+
+@defivar Breakpoint condition
+This attribute holds the condition of the breakpoint, as specified by
+the user. It is a string. If there is no condition, this attribute's
+value is @code{None}. This attribute is writable.
+@end defivar
+
+@defivar Breakpoint commands
+This attribute holds the commands attached to the breakpoint. If
+there are commands, this attribute's value is a string holding all the
+commands, separated by newlines. If there are no commands, this
+attribute is @code{None}. This attribute is not writable.
+@end defivar
+
@node Lazy Strings In Python
@subsubsection Python representation of lazy strings.
the TUI mode. When @value{GDBN} is in the standard mode, most
of these commands will automatically switch to the TUI mode.
+Note that if @value{GDBN}'s @code{stdout} is not connected to a
+terminal, or @value{GDBN} has been started with the machine interface
+interpreter (@pxref{GDB/MI, ,The @sc{gdb/mi} Interface}), most of
+these commands will fail with an error, because it would not be
+possible or desirable to enable curses window management.
+
@table @code
@item info win
@kindex info win
In general, the content of a thread group may be only retrieved only
after attaching to that thread group.
+Thread groups are related to inferiors (@pxref{Inferiors and
+Programs}). Each inferior corresponds to a thread group of a special
+type @samp{process}, and some additional operations are permitted on
+such thread groups.
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Command Syntax
@section @sc{gdb/mi} Command Syntax
processor core on which the stop event has happened. This field may be absent
if such information is not available.
-@item =thread-group-created,id="@var{id}"
+@item =thread-group-added,id="@var{id}"
+@itemx =thread-group-removed,id="@var{id}"
+A thread group was either added or removed. The @var{id} field
+contains the @value{GDBN} identifier of the thread group. When a thread
+group is added, it generally might not be associated with a running
+process. When a thread group is removed, its id becomes invalid and
+cannot be used in any way.
+
+@item =thread-group-started,id="@var{id}",pid="@var{pid}"
+A thread group became associated with a running program,
+either because the program was just started or the thread group
+was attached to a program. The @var{id} field contains the
+@value{GDBN} identifier of the thread group. The @var{pid} field
+contains process identifier, specific to the operating system.
+
@itemx =thread-group-exited,id="@var{id}"
-A thread thread group either was attached to, or has exited/detached
+A thread group is no longer associated with a running program,
+either because the program has exited, or because it was detached
from. The @var{id} field contains the @value{GDBN} identifier of the
thread group.
library file on the target, and on the host respectively. For native
debugging, both those fields have the same value. The
@var{symbols-loaded} field reports if the debug symbols for this
-library are loaded.
+library are loaded. The @var{thread-group} field, if present,
+specifies the id of the thread group in whose context the library was loaded.
+If the field is absent, it means the library was loaded in the context
+of all present thread groups.
@item =library-unloaded,...
Reports that a library was unloaded by the program. This notification
has 3 fields---@var{id}, @var{target-name} and @var{host-name} with
-the same meaning as for the @code{=library-loaded} notification
+the same meaning as for the @code{=library-loaded} notification.
+The @var{thread-group} field, if present, specifies the id of the
+thread group in whose context the library was unloaded. If the field is
+absent, it means the library was unloaded in the context of all present
+thread groups.
@end table
@subsubheading Synopsis
@smallexample
- -break-insert [ -t ] [ -h ] [ -f ] [ -d ]
+ -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
[ -p @var{thread} ] [ @var{location} ]
@end smallexample
cannot be parsed.
@item -d
Create a disabled breakpoint.
+@item -a
+Create a tracepoint. @xref{Tracepoints}. When this parameter
+is used together with @samp{-h}, a fast tracepoint is created.
@end table
@subsubheading Result
(gdb)
@end smallexample
+@subheading The @code{-break-passcount} Command
+@findex -break-passcount
+
+@subsubheading Synopsis
+
+@smallexample
+ -break-passcount @var{tracepoint-number} @var{passcount}
+@end smallexample
+
+Set the passcount for tracepoint @var{tracepoint-number} to
+@var{passcount}. If the breakpoint referred to by @var{tracepoint-number}
+is not a tracepoint, error is emitted. This corresponds to CLI
+command @samp{passcount}.
+
@subheading The @code{-break-watch} Command
@findex -break-watch
@subsubheading Synopsis
@smallexample
- -exec-continue [--all|--thread-group N]
+ -exec-continue [--reverse] [--all|--thread-group N]
@end smallexample
-Resumes the execution of the inferior program until a breakpoint is
-encountered, or until the inferior exits. In all-stop mode
-(@pxref{All-Stop Mode}), may resume only one thread, or all threads,
-depending on the value of the @samp{scheduler-locking} variable. In
-non-stop mode (@pxref{Non-Stop Mode}), if the @samp{--all} is not
-specified, only the thread specified with the @samp{--thread} option
-(or current thread, if no @samp{--thread} is provided) is resumed. If
-@samp{--all} is specified, all threads will be resumed. The
-@samp{--all} option is ignored in all-stop mode. If the
-@samp{--thread-group} options is specified, then all threads in that
-thread group are resumed.
+Resumes the execution of the inferior program, which will continue
+to execute until it reaches a debugger stop event. If the
+@samp{--reverse} option is specified, execution resumes in reverse until
+it reaches a stop event. Stop events may include
+@itemize @bullet
+@item
+breakpoints or watchpoints
+@item
+signals or exceptions
+@item
+the end of the process (or its beginning under @samp{--reverse})
+@item
+the end or beginning of a replay log if one is being used.
+@end itemize
+In all-stop mode (@pxref{All-Stop
+Mode}), may resume only one thread, or all threads, depending on the
+value of the @samp{scheduler-locking} variable. If @samp{--all} is
+specified, all threads (in all inferiors) will be resumed. The @samp{--all} option is
+ignored in all-stop mode. If the @samp{--thread-group} options is
+specified, then all threads in that thread group are resumed.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
@smallexample
- -exec-finish
+ -exec-finish [--reverse]
@end smallexample
Resumes the execution of the inferior program until the current
function is exited. Displays the results returned by the function.
+If the @samp{--reverse} option is specified, resumes the reverse
+execution of the inferior program until the point where current
+function was called.
@subsubheading @value{GDBN} Command
reported after that using the @samp{*stopped} notification.
In non-stop mode, only the context thread is interrupted by default.
-All threads will be interrupted if the @samp{--all} option is
-specified. If the @samp{--thread-group} option is specified, all
-threads in that group will be interrupted.
+All threads (in all inferiors) will be interrupted if the
+@samp{--all} option is specified. If the @samp{--thread-group}
+option is specified, all threads in that group will be interrupted.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
@smallexample
- -exec-next
+ -exec-next [--reverse]
@end smallexample
Resumes execution of the inferior program, stopping when the beginning
of the next source line is reached.
+If the @samp{--reverse} option is specified, resumes reverse execution
+of the inferior program, stopping at the beginning of the previous
+source line. If you issue this command on the first line of a
+function, it will take you back to the caller of that function, to the
+source line where the function was called.
+
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{next}.
@subsubheading Synopsis
@smallexample
- -exec-next-instruction
+ -exec-next-instruction [--reverse]
@end smallexample
Executes one machine instruction. If the instruction is a function
instruction in the middle of a source line, the address will be
printed as well.
+If the @samp{--reverse} option is specified, resumes reverse execution
+of the inferior program, stopping at the previous instruction. If the
+previously executed instruction was a return from another function,
+it will continue to execute in reverse until the call to that function
+(from the current stack frame) is reached.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{nexti}.
@subsubheading Synopsis
@smallexample
- -exec-run
+ -exec-run [--all | --thread-group N]
@end smallexample
Starts execution of the inferior from the beginning. The inferior
exits. In the latter case the output will include an exit code, if
the program has exited exceptionally.
+When no option is specified, the current inferior is started. If the
+@samp{--thread-group} option is specified, it should refer to a thread
+group of type @samp{process}, and that thread group will be started.
+If the @samp{--all} option is specified, then all inferiors will be started.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{run}.
@subsubheading Synopsis
@smallexample
- -exec-step
+ -exec-step [--reverse]
@end smallexample
Resumes execution of the inferior program, stopping when the beginning
of the next source line is reached, if the next source line is not a
function call. If it is, stop at the first instruction of the called
-function.
+function. If the @samp{--reverse} option is specified, resumes reverse
+execution of the inferior program, stopping at the beginning of the
+previously executed source line.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
@smallexample
- -exec-step-instruction
+ -exec-step-instruction [--reverse]
@end smallexample
-Resumes the inferior which executes one machine instruction. The
-output, once @value{GDBN} has stopped, will vary depending on whether
-we have stopped in the middle of a source line or not. In the former
-case, the address at which the program stopped will be printed as
-well.
+Resumes the inferior which executes one machine instruction. If the
+@samp{--reverse} option is specified, resumes reverse execution of the
+inferior program, stopping at the previously executed instruction.
+The output, once @value{GDBN} has stopped, will vary depending on
+whether we have stopped in the middle of a source line or not. In the
+former case, the address at which the program stopped will be printed
+as well.
@subsubheading @value{GDBN} Command
@node GDB/MI Tracepoint Commands
@section @sc{gdb/mi} Tracepoint Commands
-The tracepoint commands are not yet implemented.
+The commands defined in this section implement MI support for
+tracepoints. For detailed introduction, see @ref{Tracepoints}.
+
+@subheading The @code{-trace-find} Command
+@findex -trace-find
-@c @subheading -trace-actions
+@subsubheading Synopsis
+
+@smallexample
+ -trace-find @var{mode} [@var{parameters}@dots{}]
+@end smallexample
+
+Find a trace frame using criteria defined by @var{mode} and
+@var{parameters}. The following table lists permissible
+modes and their parameters. For details of operation, see @ref{tfind}.
-@c @subheading -trace-delete
+@table @samp
-@c @subheading -trace-disable
+@item none
+No parameters are required. Stops examining trace frames.
-@c @subheading -trace-dump
+@item frame-number
+An integer is required as parameter. Selects tracepoint frame with
+that index.
-@c @subheading -trace-enable
+@item tracepoint-number
+An integer is required as parameter. Finds next
+trace frame that corresponds to tracepoint with the specified number.
-@c @subheading -trace-exists
+@item pc
+An address is required as parameter. Finds
+next trace frame that corresponds to any tracepoint at the specified
+address.
-@c @subheading -trace-find
+@item pc-inside-range
+Two addresses are required as parameters. Finds next trace
+frame that corresponds to a tracepoint at an address inside the
+specified range. Both bounds are considered to be inside the range.
-@c @subheading -trace-frame-number
+@item pc-outside-range
+Two addresses are required as parameters. Finds
+next trace frame that corresponds to a tracepoint at an address outside
+the specified range. Both bounds are considered to be inside the range.
-@c @subheading -trace-info
+@item line
+Line specification is required as parameter. @xref{Specify Location}.
+Finds next trace frame that corresponds to a tracepoint at
+the specified location.
-@c @subheading -trace-insert
+@end table
-@c @subheading -trace-list
+If @samp{none} was passed as @var{mode}, the response does not
+have fields. Otherwise, the response may have the following fields:
-@c @subheading -trace-pass-count
+@table @samp
+@item found
+This field has either @samp{0} or @samp{1} as the value, depending
+on whether a matching tracepoint was found.
-@c @subheading -trace-save
+@item traceframe
+The index of the found traceframe. This field is present iff
+the @samp{found} field has value of @samp{1}.
-@c @subheading -trace-start
+@item tracepoint
+The index of the found tracepoint. This field is present iff
+the @samp{found} field has value of @samp{1}.
+
+@item frame
+The information about the frame corresponding to the found trace
+frame. This field is present only if a trace frame was found.
+@xref{GDB/MI Frame Information}, for description of this field.
+
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tfind}.
+
+@subheading -trace-define-variable
+@findex -trace-define-variable
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-define-variable @var{name} [ @var{value} ]
+@end smallexample
+
+Create trace variable @var{name} if it does not exist. If
+@var{value} is specified, sets the initial value of the specified
+trace variable to that value. Note that the @var{name} should start
+with the @samp{$} character.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tvariable}.
+
+@subheading -trace-list-variables
+@findex -trace-list-variables
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-list-variables
+@end smallexample
-@c @subheading -trace-stop
+Return a table of all defined trace variables. Each element of the
+table has the following fields:
+
+@table @samp
+@item name
+The name of the trace variable. This field is always present.
+
+@item initial
+The initial value. This is a 64-bit signed integer. This
+field is always present.
+
+@item current
+The value the trace variable has at the moment. This is a 64-bit
+signed integer. This field is absent iff current value is
+not defined, for example if the trace was never run, or is
+presently running.
+
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tvariables}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-trace-list-variables
+^done,trace-variables=@{nr_rows="1",nr_cols="3",
+hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
+ @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
+ @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
+body=[variable=@{name="$trace_timestamp",initial="0"@}
+ variable=@{name="$foo",initial="10",current="15"@}]@}
+(gdb)
+@end smallexample
+
+@subheading -trace-save
+@findex -trace-save
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-save [-r ] @var{filename}
+@end smallexample
+
+Saves the collected trace data to @var{filename}. Without the
+@samp{-r} option, the data is downloaded from the target and saved
+in a local file. With the @samp{-r} option the target is asked
+to perform the save.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tsave}.
+
+
+@subheading -trace-start
+@findex -trace-start
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-start
+@end smallexample
+
+Starts a tracing experiments. The result of this command does not
+have any fields.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tstart}.
+
+@subheading -trace-status
+@findex -trace-status
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-status
+@end smallexample
+
+Obtains the status of a tracing experiment. The result may include
+the following fields:
+
+@table @samp
+
+@item supported
+May have a value of either @samp{0}, when no tracing operations are
+supported, @samp{1}, when all tracing operations are supported, or
+@samp{file} when examining trace file. In the latter case, examining
+of trace frame is possible but new tracing experiement cannot be
+started. This field is always present.
+
+@item running
+May have a value of either @samp{0} or @samp{1} depending on whether
+tracing experiement is in progress on target. This field is present
+if @samp{supported} field is not @samp{0}.
+
+@item stop-reason
+Report the reason why the tracing was stopped last time. This field
+may be absent iff tracing was never stopped on target yet. The
+value of @samp{request} means the tracing was stopped as result of
+the @code{-trace-stop} command. The value of @samp{overflow} means
+the tracing buffer is full. The value of @samp{disconnection} means
+tracing was automatically stopped when @value{GDBN} has disconnected.
+The value of @samp{passcount} means tracing was stopped when a
+tracepoint was passed a maximal number of times for that tracepoint.
+This field is present if @samp{supported} field is not @samp{0}.
+
+@item stopping-tracepoint
+The number of tracepoint whose passcount as exceeded. This field is
+present iff the @samp{stop-reason} field has the value of
+@samp{passcount}.
+
+@item frames
+@itemx frames-created
+The @samp{frames} field is a count of the total number of trace frames
+in the trace buffer, while @samp{frames-created} is the total created
+during the run, including ones that were discarded, such as when a
+circular trace buffer filled up. Both fields are optional.
+
+@item buffer-size
+@itemx buffer-free
+These fields tell the current size of the tracing buffer and the
+remaining space. These fields are optional.
+
+@item circular
+The value of the circular trace buffer flag. @code{1} means that the
+trace buffer is circular and old trace frames will be discarded if
+necessary to make room, @code{0} means that the trace buffer is linear
+and may fill up.
+
+@item disconnected
+The value of the disconnected tracing flag. @code{1} means that
+tracing will continue after @value{GDBN} disconnects, @code{0} means
+that the trace run will stop.
+
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tstatus}.
+
+@subheading -trace-stop
+@findex -trace-stop
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-stop
+@end smallexample
+
+Stops a tracing experiment. The result of this command has the same
+fields as @code{-trace-status}, except that the @samp{supported} and
+@samp{running} fields are not output.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tstop}.
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@table @code
@item id
Identifier of the thread group. This field is always present.
+The identifier is an opaque string; frontends should not try to
+convert it to an integer, even though it might look like one.
@item type
The type of the thread group. At present, only @samp{process} is a
@item pid
The target-specific process identifier. This field is only present
-for thread groups of type @samp{process}.
+for thread groups of type @samp{process} and only if the process exists.
@item num_children
The number of children this thread group has. This field may be
thread of the group is running on. This field may be absent if
such information is not available.
+@item executable
+The name of the executable file that corresponds to this thread group.
+The field is only present for thread groups of type @samp{process},
+and only if there is a corresponding executable file.
+
@end table
@subheading Example
@{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...]
@end smallexample
+
+@subheading The @code{-add-inferior} Command
+@findex -add-inferior
+
+@subheading Synopsis
+
+@smallexample
+-add-inferior
+@end smallexample
+
+Creates a new inferior (@pxref{Inferiors and Programs}). The created
+inferior is not associated with any executable. Such association may
+be established with the @samp{-file-exec-and-symbols} command
+(@pxref{GDB/MI File Commands}). The command response has a single
+field, @samp{thread-group}, whose value is the identifier of the
+thread group corresponding to the new inferior.
+
+@subheading Example
+
+@smallexample
+@value{GDBP}
+-add-inferior
+^done,thread-group="i3"
+@end smallexample
+
@subheading The @code{-interpreter-exec} Command
@findex -interpreter-exec
The command @code{maint print raw-registers} includes the contents of
the raw register cache; the command @code{maint print cooked-registers}
-includes the (cooked) value of all registers; and the command
-@code{maint print register-groups} includes the groups that each
+includes the (cooked) value of all registers, including registers which
+aren't available on the target nor visible to user; and the
+command @code{maint print register-groups} includes the groups that each
register is a member of. @xref{Registers,, Registers, gdbint,
@value{GDBN} Internals}.
extensions unless the stub also reports that it supports them by
including @samp{multiprocess+} in its @samp{qSupported} reply.
@xref{multiprocess extensions}, for details.
+
+@item xmlRegisters
+This feature indicates that @value{GDBN} supports the XML target
+description. If the stub sees @samp{xmlRegisters=} with target
+specific strings separated by a comma, it will report register
+description.
@end table
Stubs should ignore any unknown values for
@tab @samp{-}
@tab No
+@item @samp{TracepointSource}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
The remote stub accepts and implements the reverse step packet
(@pxref{bs}).
+@item TracepointSource
+The remote stub understands the @samp{QTDPsrc} packet that supplies
+the source form of tracepoint definitions.
+
@end table
@item qSymbol::
@end table
@item qTBuffer
+@item QTBuffer
@item QTDisconnected
@itemx QTDP
+@itemx QTDPsrc
@itemx QTDV
@itemx qTfP
@itemx qTfV
The packet was not recognized.
@end table
+@item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes}
+@cindex @samp{QTDPsrc} packet
+Specify a source string of tracepoint @var{n} at address @var{addr}.
+This is useful to get accurate reproduction of the tracepoints
+originally downloaded at the beginning of the trace run. @var{type}
+is the name of the tracepoint part, such as @samp{cond} for the
+tracepoint's conditional expression (see below for a list of types), while
+@var{bytes} is the string, encoded in hexadecimal.
+
+@var{start} is the offset of the @var{bytes} within the overall source
+string, while @var{slen} is the total length of the source string.
+This is intended for handling source strings that are longer than will
+fit in a single packet.
+@c Add detailed example when this info is moved into a dedicated
+@c tracepoint descriptions section.
+
+The available string types are @samp{at} for the location,
+@samp{cond} for the conditional, and @samp{cmd} for an action command.
+@value{GDBN} sends a separate packet for each command in the action
+list, in the same order in which the commands are stored in the list.
+
+The target does not need to do anything with source strings except
+report them back as part of the replies to the @samp{qTfP}/@samp{qTsP}
+query packets.
+
+Although this packet is optional, and @value{GDBN} will only send it
+if the target replies with @samp{TracepointSource} @xref{General
+Query Packets}, it makes both disconnected tracing and trace files
+much easier to use. Otherwise the user must be careful that the
+tracepoints in effect while looking at trace frames are identical to
+the ones in effect during the trace run; even a small discrepancy
+could cause @samp{tdump} not to work, or a particular trace frame not
+be found.
+
@item QTDV:@var{n}:@var{value}
@cindex define trace state variable, remote request
@cindex @samp{QTDV} packet
@item qTStatus
Ask the stub if there is a trace experiment running right now.
-Replies:
+The reply has the form:
+
+@table @samp
+
+@item T@var{running}@r{[};@var{field}@r{]}@dots{}
+@var{running} is a single digit @code{1} if the trace is presently
+running, or @code{0} if not. It is followed by semicolon-separated
+optional fields that an agent may use to report additional status.
+
+@end table
+
+If the trace is not running, the agent may report any of several
+explanations as one of the optional fields:
+
@table @samp
-@item T0
-There is no trace experiment running.
-@item T1
-There is a trace experiment running.
+
+@item tnotrun:0
+No trace has been run yet.
+
+@item tstop:0
+The trace was stopped by a user-originated stop command.
+
+@item tfull:0
+The trace stopped because the trace buffer filled up.
+
+@item tdisconnected:0
+The trace stopped because @value{GDBN} disconnected from the target.
+
+@item tpasscount:@var{tpnum}
+The trace stopped because tracepoint @var{tpnum} exceeded its pass count.
+
+@item terror:@var{text}:@var{tpnum}
+The trace stopped because tracepoint @var{tpnum} had an error. The
+string @var{text} is available to describe the nature of the error
+(for instance, a divide by zero in the condition expression).
+@var{text} is hex encoded.
+
+@item tunknown:0
+The trace stopped for some other reason.
+
+@end table
+
+Additional optional fields supply statistical and other information.
+Although not required, they are extremely useful for users monitoring
+the progress of a trace run. If a trace has stopped, and these
+numbers are reported, they must reflect the state of the just-stopped
+trace.
+
+@table @samp
+
+@item tframes:@var{n}
+The number of trace frames in the buffer.
+
+@item tcreated:@var{n}
+The total number of trace frames created during the run. This may
+be larger than the trace frame count, if the buffer is circular.
+
+@item tsize:@var{n}
+The total size of the trace buffer, in bytes.
+
+@item tfree:@var{n}
+The number of bytes still unused in the buffer.
+
+@item circular:@var{n}
+The value of the circular trace buffer flag. @code{1} means that the
+trace buffer is circular and old trace frames will be discarded if
+necessary to make room, @code{0} means that the trace buffer is linear
+and may fill up.
+
+@item disconn:@var{n}
+The value of the disconnected tracing flag. @code{1} means that
+tracing will continue after @value{GDBN} disconnects, @code{0} means
+that the trace run will stop.
+
@end table
@item qTV:@var{var}
A reply consisting of just @code{l} indicates that no bytes are
available.
+@item QTBuffer:circular:@var{value}
+This packet directs the target to use a circular trace buffer if
+@var{value} is 1, or a linear buffer if the value is 0.
+
@end table
@node Host I/O Packets
</union>
@end smallexample
+@cindex <struct>
+If a register's value is composed from several separate values, define
+it with a structure type. There are two forms of the @samp{<struct>}
+element; a @samp{<struct>} element must either contain only bitfields
+or contain no bitfields. If the structure contains only bitfields,
+its total size in bytes must be specified, each bitfield must have an
+explicit start and end, and bitfields are automatically assigned an
+integer type. The field's @var{start} should be less than or
+equal to its @var{end}, and zero represents the least significant bit.
+
+@smallexample
+<struct id="@var{id}" size="@var{size}">
+ <field name="@var{name}" start="@var{start}" end="@var{end}"/>
+ @dots{}
+</struct>
+@end smallexample
+
+If the structure contains no bitfields, then each field has an
+explicit type, and no implicit padding is added.
+
+@smallexample
+<struct id="@var{id}">
+ <field name="@var{name}" type="@var{type}"/>
+ @dots{}
+</struct>
+@end smallexample
+
+@cindex <flags>
+If a register's value is a series of single-bit flags, define it with
+a flags type. The @samp{<flags>} element has an explicit @var{size}
+and contains one or more @samp{<field>} elements. Each field has a
+@var{name}, a @var{start}, and an @var{end}. Only single-bit flags
+are supported.
+
+@smallexample
+<flags id="@var{id}" size="@var{size}">
+ <field name="@var{name}" start="@var{start}" end="@var{end}"/>
+ @dots{}
+</flags>
+@end smallexample
+
@subsection Registers
@cindex <reg>
The register sets may be different, depending on the target.
-The @samp{org.gnu.gdb.i386.sse} feature is required. It should
+The @samp{org.gnu.gdb.i386.sse} feature is optional. It should
describe registers:
@itemize @minus
@samp{mxcsr}
@end itemize
+The @samp{org.gnu.gdb.i386.avx} feature is optional and requires the
+@samp{org.gnu.gdb.i386.sse} feature. It should
+describe the upper 128 bits of @sc{ymm} registers:
+
+@itemize @minus
+@item
+@samp{ymm0h} through @samp{ymm7h} for i386
+@item
+@samp{ymm0h} through @samp{ymm15h} for amd64
+@item
+@end itemize
+
The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
describe a single register, @samp{orig_eax}.