Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
@samp{Switching to} depends on your system's conventions for identifying
threads.
+@vindex $_thread@r{, convenience variable}
+The debugger convenience variable @samp{$_thread} contains the number
+of the current thread. You may find this useful in writing breakpoint
+conditional expressions, command scripts, and so forth. See
+@xref{Convenience Vars,, Convenience Variables}, for general
+information on convenience variables.
+
@kindex thread apply
@cindex apply command to several threads
@item thread apply [@var{threadno}] [@var{all}] @var{command}
When the inferior process exits, or @value{GDBN} detaches from it,
process record and replay target will automatically stop itself.
+@kindex record save
+@item record save @var{filename}
+Save the execution log to a file @file{@var{filename}}.
+Default filename is @file{gdb_record.@var{process_id}}, where
+@var{process_id} is the process ID of the inferior.
+
+@kindex record restore
+@item record restore @var{filename}
+Restore the execution log from a file @file{@var{filename}}.
+File must have been created with @code{record save}.
+
@kindex set record insn-number-max
@item set record insn-number-max @var{limit}
Set the limit of instructions to be recorded. Default value is 200000.
@item show record stop-at-limit
Show the current setting of @code{stop-at-limit}.
+@kindex set record memory-query
+@item set record memory-query
+Control the behavior when @value{GDBN} is unable to record memory
+changes caused by an instruction. If ON, @value{GDBN} will query
+whether to stop the inferior in that case.
+
+If this option is OFF (the default), @value{GDBN} will automatically
+ignore the effect of such instructions on memory. Later, when
+@value{GDBN} replays this execution log, it will mark the log of this
+instruction as not accessible, and it will not affect the replay
+results.
+
+@kindex show record memory-query
+@item show record memory-query
+Show the current setting of @code{memory-query}.
+
@kindex info record
@item info record
Show various statistics about the state of process record and its
function name to avoid ambiguity when there are identically named
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
command is a program counter value; @value{GDBN} dumps the function
surrounding this value. When two arguments are given, they should
be separated by a comma, possibly surrounded by whitespace. The
-arguments specify a range of addresses (first inclusive, second exclusive)
-to dump. In that case, the name of the function is also printed (since
-there could be several functions in the given range).
+arguments specify a range of addresses to dump, in one of two forms:
+
+@table @code
+@item @var{start},@var{end}
+the addresses from @var{start} (inclusive) to @var{end} (exclusive)
+@item @var{start},+@var{length}
+the addresses from @var{start} (inclusive) to
+@code{@var{start}+@var{length}} (exclusive).
+@end table
+
+@noindent
+When 2 arguments are specified, the name of the function is also
+printed (since there could be several functions in the given range).
The argument(s) can be any expression yielding a numeric value, such as
@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}.
End of assembler dump.
@end smallexample
+Here is another example showing raw instructions in hex for AMD x86-64,
+
+@smallexample
+(gdb) disas /r 0x400281,+10
+Dump of assembler code from 0x400281 to 0x40028b:
+ 0x0000000000400281: 38 36 cmp %dh,(%rsi)
+ 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
+ 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx)
+ 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al
+End of assembler dump.
+@end smallexample
+
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
The variable @code{$_exitcode} is automatically set to the exit code when
the program being debugged terminates.
+@item $_sdata
+@vindex $_sdata@r{, inspect, convenience variable}
+The variable @code{$_sdata} contains extra collected static tracepoint
+data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that
+@code{$_sdata} could be empty, if not inspecting a trace buffer, or
+if extra static tracepoint data has not been collected.
+
@item $_siginfo
@vindex $_siginfo@r{, convenience variable}
The variable @code{$_siginfo} contains extra signal information
@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}.
@table @code
+@kindex info os
+@item info os
+List the types of OS information available for the target. If the
+target does not return a list of possible types, this command will
+report an error.
+
@kindex info os processes
@item info os processes
Display the list of processes on the target. For each process,
a different way (such as with a jump instead of a trap), that is
faster but possibly restricted in where they may be installed.
+@cindex static tracepoints
+@cindex markers, static tracepoints
+@cindex probing markers, static tracepoints
+Regular and fast tracepoints are dynamic tracing facilities, meaning
+that they can be used to insert tracepoints at (almost) any location
+in the target. Some targets may also support controlling @dfn{static
+tracepoints} from @value{GDBN}. With static tracing, a set of
+instrumentation points, also known as @dfn{markers}, are embedded in
+the target program, and can be activated or deactivated by name or
+address. These are usually placed at locations which facilitate
+investigating what the target is actually doing. @value{GDBN}'s
+support for static tracing includes being able to list instrumentation
+points, and attach them with @value{GDBN} defined high level
+tracepoints that expose the whole range of convenience of
+@value{GDBN}'s tracepoints support. Namelly, support for collecting
+registers values and values of global or local (to the instrumentation
+point) variables; tracepoint conditions and trace state variables.
+The act of installing a @value{GDBN} static tracepoint on an
+instrumentation point, or marker, is referred to as @dfn{probing} a
+static tracepoint marker.
+
@code{gdbserver} supports tracepoints on some target systems.
@xref{Server,,Tracepoints support in @code{gdbserver}}.
* Trace State Variables::
* Tracepoint Actions::
* Listing Tracepoints::
+* Listing Static Tracepoint Markers::
* Starting and Stopping Trace Experiments::
* Tracepoint Restrictions::
@end menu
@item ftrace @var{location} [ if @var{cond} ]
@cindex set fast tracepoint
+@cindex fast tracepoints, setting
@kindex ftrace
The @code{ftrace} command sets a fast tracepoint. For targets that
support them, fast tracepoints will use a more efficient but possibly
@value{GDBN} handles arguments to @code{ftrace} exactly as for
@code{trace}.
+@item strace @var{location} [ if @var{cond} ]
+@cindex set static tracepoint
+@cindex static tracepoints, setting
+@cindex probe static tracepoint marker
+@kindex strace
+The @code{strace} command sets a static tracepoint. For targets that
+support it, setting a static tracepoint probes a static
+instrumentation point, or marker, found at @var{location}. It may not
+be possible to set a static tracepoint at the desired location, in
+which case the command will exit with an explanatory message.
+
+@value{GDBN} handles arguments to @code{strace} exactly as for
+@code{trace}, with the addition that the user can also specify
+@code{-m @var{marker}} as @var{location}. This probes the marker
+identified by the @var{marker} string identifier. This identifier
+depends on the static tracepoint backend library your program is
+using. You can find all the marker identifiers in the @samp{ID} field
+of the @code{info static-tracepoint-markers} command output.
+@xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint
+Markers}. For example, in the following small program using the UST
+tracing engine:
+
+@smallexample
+main ()
+@{
+ trace_mark(ust, bar33, "str %s", "FOOBAZ");
+@}
+@end smallexample
+
+@noindent
+the marker id is composed of joining the first two arguments to the
+@code{trace_mark} call with a slash, which translates to:
+
+@smallexample
+(@value{GDBP}) info static-tracepoint-markers
+Cnt Enb ID Address What
+1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22
+ Data: "str %s"
+[etc...]
+@end smallexample
+
+@noindent
+so you may probe the marker above with:
+
+@smallexample
+(@value{GDBP}) strace -m ust/bar33
+@end smallexample
+
+Static tracepoints accept an extra collect action --- @code{collect
+$_sdata}. This collects arbitrary user data passed in the probe point
+call to the tracing library. In the UST example above, you'll see
+that the third argument to @code{trace_mark} is a printf-like format
+string. The user data is then the result of running that formating
+string against the following arguments. Note that @code{info
+static-tracepoint-markers} command output lists that format string in
+the @samp{Data:} field.
+
+You can inspect this data when analyzing the trace buffer, by printing
+the $_sdata variable like any other variable available to
+@value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}.
+
@vindex $tpnum
@cindex last tracepoint number
@cindex recent tracepoint number
@table @code
@item $regs
-collect all registers
+Collect all registers.
@item $args
-collect all function arguments
+Collect all function arguments.
@item $locals
-collect all local variables.
+Collect all local variables.
+
+@item $_sdata
+@vindex $_sdata@r{, collect}
+Collect static tracepoint marker specific data. Only available for
+static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action
+Lists}. On the UST static tracepoints library backend, an
+instrumentation point resembles a @code{printf} function call. The
+tracing library is able to collect user specified data formatted to a
+character string using the format provided by the programmer that
+instrumented the program. Other backends have similar mechanisms.
+Here's an example of a UST marker call:
+
+@smallexample
+ const char master_name[] = "$your_name";
+ trace_mark(channel1, marker1, "hello %s", master_name)
+@end smallexample
+
+In this case, collecting @code{$_sdata} collects the string
+@samp{hello $yourname}. When analyzing the trace buffer, you can
+inspect @samp{$_sdata} like any other variable available to
+@value{GDBN}.
@end table
You can give several consecutive @code{collect} commands, each one
This command can be abbreviated @code{info tp}.
@end table
+@node Listing Static Tracepoint Markers
+@subsection Listing Static Tracepoint Markers
+
+@table @code
+@kindex info static-tracepoint-markers
+@cindex information about static tracepoint markers
+@item info static-tracepoint-markers
+Display information about all static tracepoint markers defined in the
+program.
+
+For each marker, the following columns are printed:
+
+@table @emph
+@item Count
+An incrementing counter, output to help readability. This is not a
+stable identifier.
+@item ID
+The marker ID, as reported by the target.
+@item Enabled or Disabled
+Probed markers are tagged with @samp{y}. @samp{n} identifies marks
+that are not enabled.
+@item Address
+Where the marker is in your program, as a memory address.
+@item What
+Where the marker is in the source for your program, as a file and line
+number. If the debug information included in the program does not
+allow @value{GDBN} to locate the source of the marker, this column
+will be left blank.
+@end table
+
+@noindent
+In addition, the following information may be printed for each marker:
+
+@table @emph
+@item Data
+User data passed to the tracing library by the marker call. In the
+UST backend, this is the format string passed as argument to the
+marker call.
+@item Static tracepoints probing the marker
+The list of static tracepoints attached to the marker.
+@end table
+
+@smallexample
+(@value{GDBP}) info static-tracepoint-markers
+Cnt ID Enb Address What
+1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25
+ Data: number1 %d number2 %d
+ Probed by static tracepoints: #2
+2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24
+ Data: str %s
+(@value{GDBP})
+@end smallexample
+@end table
+
@node Starting and Stopping Trace Experiments
@subsection Starting and Stopping Trace Experiments
@menu
* Files:: Commands to specify files
* Separate Debug Files:: Debugging information in separate files
+* Index Files:: Index files speed up GDB
* Symbol Errors:: Errors reading symbol files
* Data Files:: GDB data files
@end menu
This computation does not apply to the ``build ID'' method.
+@node Index Files
+@section Index Files Speed Up @value{GDBN}
+@cindex index files
+@cindex @samp{.gdb_index} section
+
+When @value{GDBN} finds a symbol file, it scans the symbols in the
+file in order to construct an internal symbol table. This lets most
+@value{GDBN} operations work quickly---at the cost of a delay early
+on. For large programs, this delay can be quite lengthy, so
+@value{GDBN} provides a way to build an index, which speeds up
+startup.
+
+The index is stored as a section in the symbol file. @value{GDBN} can
+write the index to a file, then you can put it into the symbol file
+using @command{objcopy}.
+
+To create an index file, use the @code{save gdb-index} command:
+
+@table @code
+@item save gdb-index @var{directory}
+@kindex save gdb-index
+Create an index file for each symbol file currently known by
+@value{GDBN}. Each file is named after its corresponding symbol file,
+with @samp{.gdb-index} appended, and is written into the given
+@var{directory}.
+@end table
+
+Once you have created an index file you can merge it into your symbol
+file, here named @file{symfile}, using @command{objcopy}:
+
+@smallexample
+$ objcopy --add-section .gdb_index=symfile.gdb-index \
+ --set-section-flags .gdb_index=readonly symfile symfile
+@end smallexample
+
+There are currently some limitation on indices. They only work when
+for DWARF debugging information, not stabs. And, they do not
+currently work for programs using Ada.
+
+
@node Symbol Errors
@section Errors Reading Symbol Files
@cindex active targets
@cindex multiple targets
-There are three classes of targets: processes, core files, and
-executable files. @value{GDBN} can work concurrently on up to three
-active targets, one in each class. This allows you to (for example)
-start a process and inspect its activity without abandoning your work on
-a core file.
-
-For example, if you execute @samp{gdb a.out}, then the executable file
-@code{a.out} is the only active target. If you designate a core file as
-well---presumably from a prior run that crashed and coredumped---then
-@value{GDBN} has two active targets and uses them in tandem, looking
-first in the corefile target, then in the executable file, to satisfy
-requests for memory addresses. (Typically, these two classes of target
-are complementary, since core files contain only a program's
-read-write memory---variables and so on---plus machine status, while
-executable files contain only the program text and initialized data.)
-
-When you type @code{run}, your executable file becomes an active process
-target as well. When a process target is active, all @value{GDBN}
-commands requesting memory addresses refer to that target; addresses in
-an active core file or executable file target are obscured while the
-process target is active.
-
-Use the @code{core-file} and @code{exec-file} commands to select a new
-core file or executable target (@pxref{Files, ,Commands to Specify
-Files}). To specify as a target a process that is already running, use
-the @code{attach} command (@pxref{Attach, ,Debugging an Already-running
-Process}).
+There are multiple classes of targets such as: processes, executable files or
+recording sessions. Core files belong to the process class, making core file
+and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently
+on multiple active targets, one in each class. This allows you to (for
+example) start a process and inspect its activity, while still having access to
+the executable file after the process finishes. Or if you start process
+recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are
+presented a virtual layer of the recording target, while the process target
+remains stopped at the chronologically last point of the process execution.
+
+Use the @code{core-file} and @code{exec-file} commands to select a new core
+file or executable target (@pxref{Files, ,Commands to Specify Files}). To
+specify as a target a process that is already running, use the @code{attach}
+command (@pxref{Attach, ,Debugging an Already-running Process}).
@node Target Commands
@section Commands for Managing Targets
@subsection Tracepoints support in @code{gdbserver}
@cindex tracepoints support in @code{gdbserver}
-On some targets, @code{gdbserver} supports tracepoints and fast
-tracepoints.
+On some targets, @code{gdbserver} supports tracepoints, fast
+tracepoints and static tracepoints.
-For fast tracepoints to work, a special library called the
+For fast or static tracepoints to work, a special library called the
@dfn{in-process agent} (IPA), must be loaded in the inferior process.
This library is built and distributed as an integral part of
-@code{gdbserver}.
+@code{gdbserver}. In addition, support for static tracepoints
+requires building the in-process agent library with static tracepoints
+support. At present, the UST (LTTng Userspace Tracer,
+@url{http://lttng.org/ust}) tracing engine is supported. This support
+is automatically available if UST development headers are found in the
+standard include path when @code{gdbserver} is built, or if
+@code{gdbserver} was explicitly configured using @option{--with-ust}
+to point at such headers. You can explicitly disable the support
+using @option{--with-ust=no}.
There are several ways to load the in-process agent in your program:
remote}, you'll find that the program is stopped at the dynamic
loader's entry point, and no shared library has been loaded in the
program's address space yet, including the in-process agent. In that
-case, before being able to use any of the fast tracepoints features,
-you need to let the loader run and load the shared libraries. The
-most simple way to do that is to run the program to the main
-procedure. E.g., if debugging a C or C@t{++} program, start
+case, before being able to use any of the fast or static tracepoints
+features, you need to let the loader run and load the shared
+libraries. The simplest way to do that is to run the program to the
+main procedure. E.g., if debugging a C or C@t{++} program, start
@code{gdbserver} like so:
@smallexample
The in-process tracing agent library should now be loaded into the
process; you can confirm it with the @code{info sharedlibrary}
command, which will list @file{libinproctrace.so} as loaded in the
-process. You are now ready to install fast tracepoints and start
+process. You are now ready to install fast tracepoints, list static
+tracepoint markers, probe static tracepoints markers, and start
tracing.
@node Remote Configuration
@tab @code{qXfer:memory-map:read}
@tab @code{info mem}
+@item @code{read-sdata-object}
+@tab @code{qXfer:sdata:read}
+@tab @code{print $_sdata}
+
@item @code{read-spu-object}
@tab @code{qXfer:spu:read}
@tab @code{info spu}
printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
@end smallexample
+@kindex eval
+@item eval @var{template}, @var{expressions}@dots{}
+Convert the values of one or more @var{expressions} under the control of
+the string @var{template} to a command line, and call it.
+
@end table
@node Python
Python programming language}. This feature is available only if
@value{GDBN} was configured using @option{--with-python}.
+@cindex python directory
+Python scripts used by @value{GDBN} should be installed in
+@file{@var{data-directory}/python}, where @var{data-directory} is
+the data directory as determined at @value{GDBN} startup (@pxref{Data Files}). This directory, known as the @dfn{python directory},
+is automatically added to the Python Search Path in order to allow
+the Python interpreter to locate all scripts installed at this location.
+
@menu
* Python Commands:: Accessing Python from @value{GDBN}.
* Python API:: Accessing @value{GDBN} from Python.
* Pretty Printing API:: Pretty-printing values.
* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
* Disabling Pretty-Printers:: Disabling broken printers.
+* Inferiors In Python:: Python representation of inferiors (processes)
+* Threads In Python:: Accessing inferior threads from Python.
* Commands In Python:: Implementing new commands in Python.
* Parameters In Python:: Adding new @value{GDBN} parameters.
* Functions In Python:: Writing new convenience functions.
@value{GDBN} automatically @code{import}s the @code{gdb} module for
use in all scripts evaluated by the @code{python} command.
+@findex gdb.PYTHONDIR
+@defvar PYTHONDIR
+A string containing the python directory (@pxref{Python}).
+@end defvar
+
@findex gdb.execute
-@defun execute command [from_tty]
+@defun execute command [from_tty] [to_string]
Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
If a GDB exception happens while @var{command} runs, it is
translated as described in @ref{Exception Handling,,Exception Handling}.
-If no exceptions occur, this function returns @code{None}.
@var{from_tty} specifies whether @value{GDBN} ought to consider this
command as having originated from the user invoking it interactively.
It must be a boolean value. If omitted, it defaults to @code{False}.
+
+By default, any output produced by @var{command} is sent to
+@value{GDBN}'s standard output. If the @var{to_string} parameter is
+@code{True}, then output will be collected by @code{gdb.execute} and
+returned as a string. The default is @code{False}, in which case the
+return value is @code{None}.
@end defun
@findex gdb.breakpoints
Again, @code{bar} will also be a @code{gdb.Value} object.
+A @code{gdb.Value} that represents a function can be executed via
+inferior function call. Any arguments provided to the call must match
+the function's prototype, and must be provided in the order specified
+by that prototype.
+
+For example, @code{some_val} is a @code{gdb.Value} instance
+representing a function that takes two integers as arguments. To
+execute this function, call it like so:
+
+@smallexample
+result = some_val (10,20)
+@end smallexample
+
+Any values returned from a function call will be stored as a
+@code{gdb.Value}.
+
The following attributes are provided:
@table @code
is present and its value is @code{False}, the printer is disabled, otherwise
the printer is enabled.
+@node Inferiors In Python
+@subsubsection Inferiors In Python
+@cindex inferiors in python
+
+@findex gdb.Inferior
+Programs which are being run under @value{GDBN} are called inferiors
+(@pxref{Inferiors and Programs}). Python scripts can access
+information about and manipulate inferiors controlled by @value{GDBN}
+via objects of the @code{gdb.Inferior} class.
+
+The following inferior-related functions are available in the @code{gdb}
+module:
+
+@defun inferiors
+Return a tuple containing all inferior objects.
+@end defun
+
+A @code{gdb.Inferior} object has the following attributes:
+
+@table @code
+@defivar Inferior num
+ID of inferior, as assigned by GDB.
+@end defivar
+
+@defivar Inferior pid
+Process ID of the inferior, as assigned by the underlying operating
+system.
+@end defivar
+
+@defivar Inferior was_attached
+Boolean signaling whether the inferior was created using `attach', or
+started by @value{GDBN} itself.
+@end defivar
+@end table
+
+A @code{gdb.Inferior} object has the following methods:
+
+@table @code
+@defmethod Inferior threads
+This method returns a tuple holding all the threads which are valid
+when it is called. If there are no valid threads, the method will
+return an empty tuple.
+@end defmethod
+
+@findex gdb.read_memory
+@defmethod Inferior read_memory address length
+Read @var{length} bytes of memory from the inferior, starting at
+@var{address}. Returns a buffer object, which behaves much like an array
+or a string. It can be modified and given to the @code{gdb.write_memory}
+function.
+@end defmethod
+
+@findex gdb.write_memory
+@defmethod Inferior write_memory address buffer @r{[}length@r{]}
+Write the contents of @var{buffer} to the inferior, starting at
+@var{address}. The @var{buffer} parameter must be a Python object
+which supports the buffer protocol, i.e., a string, an array or the
+object returned from @code{gdb.read_memory}. If given, @var{length}
+determines the number of bytes from @var{buffer} to be written.
+@end defmethod
+
+@findex gdb.search_memory
+@defmethod Inferior search_memory address length pattern
+Search a region of the inferior memory starting at @var{address} with
+the given @var{length} using the search pattern supplied in
+@var{pattern}. The @var{pattern} parameter must be a Python object
+which supports the buffer protocol, i.e., a string, an array or the
+object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
+containing the address where the pattern was found, or @code{None} if
+the pattern could not be found.
+@end defmethod
+@end table
+
+@node Threads In Python
+@subsubsection Threads In Python
+@cindex threads in python
+
+@findex gdb.InferiorThread
+Python scripts can access information about, and manipulate inferior threads
+controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
+
+The following thread-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.selected_thread
+@defun selected_thread
+This function returns the thread object for the selected thread. If there
+is no selected thread, this will return @code{None}.
+@end defun
+
+A @code{gdb.InferiorThread} object has the following attributes:
+
+@table @code
+@defivar InferiorThread num
+ID of the thread, as assigned by GDB.
+@end defivar
+
+@defivar InferiorThread ptid
+ID of the thread, as assigned by the operating system. This attribute is a
+tuple containing three integers. The first is the Process ID (PID); the second
+is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
+Either the LWPID or TID may be 0, which indicates that the operating system
+does not use that identifier.
+@end defivar
+@end table
+
+A @code{gdb.InferiorThread} object has the following methods:
+
+@table @code
+@defmethod InferiorThread switch
+This changes @value{GDBN}'s currently selected thread to the one represented
+by this object.
+@end defmethod
+
+@defmethod InferiorThread is_stopped
+Return a Boolean indicating whether the thread is stopped.
+@end defmethod
+
+@defmethod InferiorThread is_running
+Return a Boolean indicating whether the thread is running.
+@end defmethod
+
+@defmethod InferiorThread is_exited
+Return a Boolean indicating whether the thread is exited.
+@end defmethod
+@end table
+
@node Commands In Python
@subsubsection Commands In Python
Return a list of the children of the specified variable object and
create variable objects for them, if they do not already exist. With
-a single argument or if @var{print-values} has a value for of 0 or
+a single argument or if @var{print-values} has a value of 0 or
@code{--no-values}, print only the names of the variables; if
@var{print-values} is 1 or @code{--all-values}, also print their
values; and if it is 2 or @code{--simple-values} print the name and
more thread IDs, separated by commas.
@value{GDBN} will respond to each reply with a request for more thread
ids (using the @samp{qs} form of the query), until the target responds
-with @samp{l} (lower-case el, for @dfn{last}).
+with @samp{l} (lower-case ell, for @dfn{last}).
Refer to @ref{thread-id syntax}, for the format of the @var{thread-id}
fields.
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:sdata:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:spu:read}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:memory-map:read} packet
(@pxref{qXfer memory map read}).
+@item qXfer:sdata:read
+The remote stub understands the @samp{qXfer:sdata:read} packet
+(@pxref{qXfer sdata read}).
+
@item qXfer:spu:read
The remote stub understands the @samp{qXfer:spu:read} packet
(@pxref{qXfer spu read}).
@item QAllow
The remote stub understands the @samp{QAllow} packet.
+@item StaticTracepoint
+@cindex static tracepoints, in remote protocol
+The remote stub supports static tracepoints.
+
@end table
@item qSymbol::
@itemx QTro
@itemx qTStatus
@itemx qTV
+@itemx qTfSTM
+@itemx qTsSTM
+@itemx qTSTMat
@xref{Tracepoint Packets}.
@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:sdata:read::@var{offset},@var{length}
+@anchor{qXfer sdata read}
+
+Read contents of the extra collected static tracepoint marker
+information. The annex part of the generic @samp{qXfer} packet must
+be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint
+Action Lists}.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}).
+
@item qXfer:siginfo:read::@var{offset},@var{length}
@anchor{qXfer siginfo read}
Read contents of the extra signal information on the target
these packets follow the syntax of the @code{QTDV} packets that define
trace state variables.
+@item qTfSTM
+@itemx qTsSTM
+These packets request data about static tracepoint markers that exist
+in the target program. @value{GDBN} sends @code{qTfSTM} to get the
+first piece of data, and multiple @code{qTsSTM} to get additional
+pieces. Replies to these packets take the following form:
+
+Reply:
+@table @samp
+@item m @var{address}:@var{id}:@var{extra}
+A single marker
+@item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{}
+a comma-separated list of markers
+@item l
+(lower case letter @samp{L}) denotes end of list.
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+@item
+An empty reply indicates that the request is not supported by the
+stub.
+@end table
+
+@var{address} is encoded in hex.
+@var{id} and @var{extra} are strings encoded in hex.
+
+In response to each query, the target will reply with a list of one or
+more markers, separated by commas. @value{GDBN} will respond to each
+reply with a request for more markers (using the @samp{qs} form of the
+query), until the target responds with @samp{l} (lower-case ell, for
+@dfn{last}).
+
+@item qTSTMat:@var{address}
+This packets requests data about static tracepoint markers in the
+target program at @var{address}. Replies to this packet follow the
+syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static
+tracepoint markers.
+
@item QTSave:@var{filename}
This packet directs the target to save trace data to the file name
@var{filename} in the target's filesystem. @var{filename} is encoded
@include gpl.texi
-@raisesections
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
@include fdl.texi
-@lowersections
@node Index
@unnumbered Index
projects / deliverable / binutils-gdb.git / blobdiff