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,''
For more information, see @ref{Supported Languages,,Supported Languages}.
For more information, see @ref{C,,C and C++}.
+Support for D is partial. For information on D, see
+@ref{D,,D}.
+
@cindex Modula-2
Support for Modula-2 is partial. For information on Modula-2, see
@ref{Modula-2,,Modula-2}.
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
@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}
* Disabling:: Disabling breakpoints
* Conditions:: Break conditions
* Break Commands:: Breakpoint command lists
+* Save Breakpoints:: How to save breakpoints in a file
* Error in Breakpoints:: ``Cannot insert breakpoints''
* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
@end menu
@kindex rbreak
@cindex regular expression
-@cindex breakpoints in functions matching a regexp
+@cindex breakpoints at functions matching a regexp
@cindex set breakpoints in many functions
@item rbreak @var{regex}
Set breakpoints on all functions matching the regular expression
(@value{GDBP}) rbreak .
@end smallexample
+@item rbreak @var{file}:@var{regex}
+If @code{rbreak} is called with a filename qualification, it limits
+the search for functions matching the given regular expression to the
+specified @var{file}. This can be used, for example, to set breakpoints on
+every function in a given file:
+
+@smallexample
+(@value{GDBP}) rbreak file.c:.
+@end smallexample
+
+The colon separating the filename qualifier from the regex may
+optionally be surrounded by spaces.
+
@kindex info breakpoints
@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
+If you watch for a change in a numerically entered address you need to
+dereference it, as the address itself is just a constant number which will
+never change. @value{GDBN} refuses to create a watchpoint that watches
+a never-changing value:
+
+@smallexample
+(@value{GDBP}) watch 0x600850
+Cannot watch constant value 0x600850.
+(@value{GDBP}) watch *(int *) 0x600850
+Watchpoint 1: *(int *) 6293584
+@end smallexample
+
@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
watchpoints execute very quickly, and the debugger reports a change in
value at the exact instruction where the change occurs. If @value{GDBN}
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
end
@end smallexample
+@node Save Breakpoints
+@subsection How to save breakpoints to a file
+
+To save breakpoint definitions to a file use the @w{@code{save
+breakpoints}} command.
+
+@table @code
+@kindex save breakpoints
+@cindex save breakpoints to a file for future sessions
+@item save breakpoints [@var{filename}]
+This command saves all current breakpoint definitions together with
+their commands and ignore counts, into a file @file{@var{filename}}
+suitable for use in a later debugging session. This includes all
+types of breakpoints (breakpoints, watchpoints, catchpoints,
+tracepoints). To read the saved breakpoint definitions, use the
+@code{source} command (@pxref{Command Files}). Note that watchpoints
+with expressions involving local variables may fail to be recreated
+because it may not be possible to access the context where the
+watchpoint is valid anymore. Because the saved breakpoint definitions
+are simply a sequence of @value{GDBN} commands that recreate the
+breakpoints, you can edit the file in your favorite editing program,
+and remove the breakpoint definitions you're not interested in, or
+that can no longer be recreated.
+@end table
+
@c @ifclear BARETARGET
@node Error in Breakpoints
@subsection ``Cannot insert breakpoints''
* Background Execution:: Running your program asynchronously
* Thread-Specific Breakpoints:: Controlling breakpoints
* Interrupted System Calls:: GDB may interfere with system calls
+* Observer Mode:: GDB does not alter program behavior
@end menu
@node All-Stop Mode
When such an event happens, a system call in another thread may return
prematurely, even though your program does not appear to stop.
+@node Observer Mode
+@subsection Observer Mode
+
+If you want to build on non-stop mode and observe program behavior
+without any chance of disruption by @value{GDBN}, you can set
+variables to disable all of the debugger's attempts to modify state,
+whether by writing memory, inserting breakpoints, etc. These operate
+at a low level, intercepting operations from all commands.
+
+When all of these are set to @code{off}, then @value{GDBN} is said to
+be @dfn{observer mode}. As a convenience, the variable
+@code{observer} can be set to disable these, plus enable non-stop
+mode.
+
+Note that @value{GDBN} will not prevent you from making nonsensical
+combinations of these settings. For instance, if you have enabled
+@code{may-insert-breakpoints} but disabled @code{may-write-memory},
+then breakpoints that work by writing trap instructions into the code
+stream will still not be able to be placed.
+
+@table @code
+
+@kindex observer
+@item set observer on
+@itemx set observer off
+When set to @code{on}, this disables all the permission variables
+below (except for @code{insert-fast-tracepoints}), plus enables
+non-stop debugging. Setting this to @code{off} switches back to
+normal debugging, though remaining in non-stop mode.
+
+@item show observer
+Show whether observer mode is on or off.
+
+@kindex may-write-registers
+@item set may-write-registers on
+@itemx set may-write-registers off
+This controls whether @value{GDBN} will attempt to alter the values of
+registers, such as with assignment expressions in @code{print}, or the
+@code{jump} command. It defaults to @code{on}.
+
+@item show may-write-registers
+Show the current permission to write registers.
+
+@kindex may-write-memory
+@item set may-write-memory on
+@itemx set may-write-memory off
+This controls whether @value{GDBN} will attempt to alter the contents
+of memory, such as with assignment expressions in @code{print}. It
+defaults to @code{on}.
+
+@item show may-write-memory
+Show the current permission to write memory.
+
+@kindex may-insert-breakpoints
+@item set may-insert-breakpoints on
+@itemx set may-insert-breakpoints off
+This controls whether @value{GDBN} will attempt to insert breakpoints.
+This affects all breakpoints, including internal breakpoints defined
+by @value{GDBN}. It defaults to @code{on}.
+
+@item show may-insert-breakpoints
+Show the current permission to insert breakpoints.
+
+@kindex may-insert-tracepoints
+@item set may-insert-tracepoints on
+@itemx set may-insert-tracepoints off
+This controls whether @value{GDBN} will attempt to insert (regular)
+tracepoints at the beginning of a tracing experiment. It affects only
+non-fast tracepoints, fast tracepoints being under the control of
+@code{may-insert-fast-tracepoints}. It defaults to @code{on}.
+
+@item show may-insert-tracepoints
+Show the current permission to insert tracepoints.
+
+@kindex may-insert-fast-tracepoints
+@item set may-insert-fast-tracepoints on
+@itemx set may-insert-fast-tracepoints off
+This controls whether @value{GDBN} will attempt to insert fast
+tracepoints at the beginning of a tracing experiment. It affects only
+fast tracepoints, regular (non-fast) tracepoints being under the
+control of @code{may-insert-tracepoints}. It defaults to @code{on}.
+
+@item show may-insert-fast-tracepoints
+Show the current permission to insert fast tracepoints.
+
+@kindex may-interrupt
+@item set may-interrupt on
+@itemx set may-interrupt off
+This controls whether @value{GDBN} will attempt to interrupt or stop
+program execution. When this variable is @code{off}, the
+@code{interrupt} command will have no effect, nor will
+@kbd{Ctrl-c}. It defaults to @code{on}.
+
+@item show may-interrupt
+Show the current permission to interrupt or stop the program.
+
+@end table
@node Reverse Execution
@chapter Running programs backward
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
* Memory:: Examining memory
* Auto Display:: Automatic display
* Print Settings:: Print settings
+* Pretty Printing:: Python pretty printing
* Value History:: Value history
* Convenience Vars:: Convenience variables
* Registers:: Registers
@end table
Each time you specify a unit size with @code{x}, that size becomes the
-default unit the next time you use @code{x}. (For the @samp{s} and
-@samp{i} formats, the unit size is ignored and is normally not written.)
+default unit the next time you use @code{x}. For the @samp{i} format,
+the unit size is ignored and is normally not written. For the @samp{s} format,
+the unit size defaults to @samp{b}, unless it is explicitly given.
+Use @kbd{x /hs} to display 16-bit char strings and @kbd{x /ws} to display
+32-bit strings. The next use of @kbd{x /s} will again display 8-bit strings.
+Note that the results depend on the programming language of the
+current compilation unit. If the language is C, the @samp{s}
+modifier will use the UTF-16 encoding while @samp{w} will use
+UTF-32. The encoding is set by the programming language and cannot
+be altered.
@item @var{addr}, starting display address
@var{addr} is the address where you want @value{GDBN} to begin displaying
Show whether C@t{++} virtual function tables are pretty printed, or not.
@end table
+@node Pretty Printing
+@section Pretty Printing
+
+@value{GDBN} provides a mechanism to allow pretty-printing of values using
+Python code. It greatly simplifies the display of complex objects. This
+mechanism works for both MI and the CLI.
+
+For example, here is how a C@t{++} @code{std::string} looks without a
+pretty-printer:
+
+@smallexample
+(@value{GDBP}) print s
+$1 = @{
+ static npos = 4294967295,
+ _M_dataplus = @{
+ <std::allocator<char>> = @{
+ <__gnu_cxx::new_allocator<char>> = @{
+ <No data fields>@}, <No data fields>
+ @},
+ members of std::basic_string<char, std::char_traits<char>,
+ std::allocator<char> >::_Alloc_hider:
+ _M_p = 0x804a014 "abcd"
+ @}
+@}
+@end smallexample
+
+With a pretty-printer for @code{std::string} only the contents are printed:
+
+@smallexample
+(@value{GDBP}) print s
+$2 = "abcd"
+@end smallexample
+
+For implementing pretty printers for new types you should read the Python API
+details (@pxref{Pretty Printing API}).
+
@node Value History
@section Value History
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
(@pxref{extra signal information}). Note that @code{$_siginfo}
could be empty, if the application has not yet received any signals.
For example, it will be empty before you execute the @code{run} command.
+
+@item $_tlb
+@vindex $_tlb@r{, convenience variable}
+The variable @code{$_tlb} is automatically set when debugging
+applications running on MS-Windows in native mode or connected to
+gdbserver that supports the @code{qGetTIBAddr} request.
+@xref{General Query Packets}.
+This variable contains the address of the thread information block.
+
@end table
On HP-UX systems, if you refer to a function or variable name that
@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,
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
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}}.
+
This section describes commands to set tracepoints and associated
conditions and actions.
* Trace State Variables::
* Tracepoint Actions::
* Listing Tracepoints::
+* Listing Static Tracepoint Markers::
* Starting and Stopping Trace Experiments::
+* Tracepoint Restrictions::
@end menu
@node Create and Delete Tracepoints
@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
@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}.
+@code{actions} is actually equivalent to @code{commands} (@pxref{Break
+Commands, ,Breakpoint Command Lists}), except that only the defined
+actions are allowed; any other @value{GDBN} command is rejected.
+
@cindex remove actions from a tracepoint
To remove all actions from a tracepoint, type @samp{actions @var{num}}
and follow it immediately with @samp{end}.
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}
> collect bar,baz
> collect $regs
> while-stepping 12
- > collect $fp, $sp
+ > collect $pc, arr[i]
> end
end
@end smallexample
@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
with a single argument, or one @code{collect} command with several
-arguments separated by commas: the effect is the same.
+arguments separated by commas; the effect is the same.
The command @code{info scope} (@pxref{Symbols, info scope}) is
particularly useful for figuring out what data to collect.
@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{}
@itemize @bullet
@item
its passcount as given by the @code{passcount @var{n}} command
-@item
-its step count as given by the @code{while-stepping @var{n}} command
-@item
-its action list as given by the @code{actions} command. The actions
-are prefixed with an @samp{A} so as to distinguish them from commands.
@end itemize
@smallexample
(@value{GDBP}) @b{info trace}
Num Type Disp Enb Address What
1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7
+ while-stepping 20
+ collect globfoo, $regs
+ end
+ collect globfoo2
+ end
pass count 1200
- step count 20
- A while-stepping 20
- A collect globfoo, $regs
- A end
- A collect globfoo2
- A end
(@value{GDBP})
@end smallexample
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
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
@menu
* tfind:: How to select a trace snapshot
* tdump:: How to display all data for a snapshot
-* save-tracepoints:: How to save tracepoints for a future run
+* save tracepoints:: How to save tracepoints for a future run
@end menu
@node tfind
(@value{GDBP})
@end smallexample
-@node save-tracepoints
-@subsection @code{save-tracepoints @var{filename}}
+@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
@kindex save-tracepoints
@cindex save tracepoints for future sessions
their actions and passcounts, into a file @file{@var{filename}}
suitable for use in a later debugging session. To read the saved
tracepoint definitions, use the @code{source} command (@pxref{Command
-Files}).
+Files}). The @w{@code{save-tracepoints}} command is a deprecated
+alias for @w{@code{save tracepoints}}
@node Tracepoint Variables
@section Convenience Variables for Tracepoints
@itemx .c++
C@t{++} source file
+@item .d
+D source file
+
@item .m
Objective-C source file
@node Supported Languages
@section Supported Languages
-@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal,
+@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, Pascal,
assembly, Modula-2, and Ada.
@c This is false ...
Some @value{GDBN} features may be used in expressions regardless of the
@menu
* C:: C and C@t{++}
+* D:: D
* Objective-C:: Objective-C
* Fortran:: Fortran
* Pascal:: Pascal
to inspect @code{_Decimal128} values stored in floating point registers.
See @ref{PowerPC,,PowerPC} for more details.
+@node D
+@subsection D
+
+@cindex D
+@value{GDBN} can be used to debug programs written in D and compiled with
+GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D
+specific feature --- dynamic arrays.
+
@node Objective-C
@subsection Objective-C
that happens to be named @file{remote:}, you need to use some equivalent
variant of the name like @file{./remote:}.}
+For targets with an MS-DOS based filesystem, such as MS-Windows and
+SymbianOS, @value{GDBN} tries prefixing a few variants of the target
+absolute file name with @var{path}. But first, on Unix hosts,
+@value{GDBN} converts all backslash directory separators into forward
+slashes, because the backslash is not a directory separator on Unix:
+
+@smallexample
+ c:\foo\bar.dll @result{} c:/foo/bar.dll
+@end smallexample
+
+Then, @value{GDBN} attempts prefixing the target file name with
+@var{path}, and looks for the resulting file name in the host file
+system:
+
+@smallexample
+ c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll
+@end smallexample
+
+If that does not find the shared library, @value{GDBN} tries removing
+the @samp{:} character from the drive spec, both for convenience, and,
+for the case of the host file system not supporting file names with
+colons:
+
+@smallexample
+ c:/foo/bar.dll @result{} /path/to/sysroot/c/foo/bar.dll
+@end smallexample
+
+This makes it possible to have a system root that mirrors a target
+with more than one drive. E.g., you may want to setup your local
+copies of the target system shared libraries like so (note @samp{c} vs
+@samp{z}):
+
+@smallexample
+ @file{/path/to/sysroot/c/sys/bin/foo.dll}
+ @file{/path/to/sysroot/c/sys/bin/bar.dll}
+ @file{/path/to/sysroot/z/sys/bin/bar.dll}
+@end smallexample
+
+@noindent
+and point the system root at @file{/path/to/sysroot}, so that
+@value{GDBN} can find the correct copies of both
+@file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}.
+
+If that still does not find the shared library, @value{GDBN} tries
+removing the whole drive spec from the target file name:
+
+@smallexample
+ c:/foo/bar.dll @result{} /path/to/sysroot/foo/bar.dll
+@end smallexample
+
+This last lookup makes it possible to not care about the drive name,
+if you don't want or need to.
+
The @code{set solib-absolute-prefix} command is an alias for @code{set
sysroot}.
@kindex show solib-search-path
@item show solib-search-path
Display the current shared library search path.
+
+@cindex DOS file-name semantics of file names.
+@kindex set target-file-system-kind (unix|dos-based|auto)
+@kindex show target-file-system-kind
+@item set target-file-system-kind @var{kind}
+Set assumed file system kind for target reported file names.
+
+Shared library file names as reported by the target system may not
+make sense as is on the system @value{GDBN} is running on. For
+example, when remote debugging a target that has MS-DOS based file
+system semantics, from a Unix host, the target may be reporting to
+@value{GDBN} a list of loaded shared libraries with file names such as
+@file{c:\Windows\kernel32.dll}. On Unix hosts, there's no concept of
+drive letters, so the @samp{c:\} prefix is not normally understood as
+indicating an absolute file name, and neither is the backslash
+normally considered a directory separator character. In that case,
+the native file system would interpret this whole absolute file name
+as a relative file name with no directory components. This would make
+it impossible to point @value{GDBN} at a copy of the remote target's
+shared libraries on the host using @code{set sysroot}, and impractical
+with @code{set solib-search-path}. Setting
+@code{target-file-system-kind} to @code{dos-based} tells @value{GDBN}
+to interpret such file names similarly to how the target would, and to
+map them to file names valid on @value{GDBN}'s native file system
+semantics. The value of @var{kind} can be @code{"auto"}, in addition
+to one of the supported file system kinds. In that case, @value{GDBN}
+tries to determine the appropriate file system variant based on the
+current target's operating system (@pxref{ABI, ,Configuring the
+Current ABI}). The supported file system settings are:
+
+@table @code
+@item unix
+Instruct @value{GDBN} to assume the target file system is of Unix
+kind. Only file names starting the forward slash (@samp{/}) character
+are considered absolute, and the directory separator character is also
+the forward slash.
+
+@item dos-based
+Instruct @value{GDBN} to assume the target file system is DOS based.
+File names starting with either a forward slash, or a drive letter
+followed by a colon (e.g., @samp{c:}), are considered absolute, and
+both the slash (@samp{/}) and the backslash (@samp{\\}) characters are
+considered directory separators.
+
+@item auto
+Instruct @value{GDBN} to use the file system kind associated with the
+target operating system (@pxref{ABI, ,Configuring the Current ABI}).
+This is the default.
+@end table
@end table
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,
@end table
+@subsection Tracepoints support in @code{gdbserver}
+@cindex tracepoints support in @code{gdbserver}
+
+On some targets, @code{gdbserver} supports tracepoints, fast
+tracepoints and static tracepoints.
+
+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}. 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:
+
+@table @code
+@item Specifying it as dependency at link time
+
+You can link your program dynamically with the in-process agent
+library. On most systems, this is accomplished by adding
+@code{-linproctrace} to the link command.
+
+@item Using the system's preloading mechanisms
+
+You can force loading the in-process agent at startup time by using
+your system's support for preloading shared libraries. Many Unixes
+support the concept of preloading user defined libraries. In most
+cases, you do that by specifying @code{LD_PRELOAD=libinproctrace.so}
+in the environment. See also the description of @code{gdbserver}'s
+@option{--wrapper} command line option.
+
+@item Using @value{GDBN} to force loading the agent at run time
+
+On some systems, you can force the inferior to load a shared library,
+by calling a dynamic loader function in the inferior that takes care
+of dynamically looking up and loading a shared library. On most Unix
+systems, the function is @code{dlopen}. You'll use the @code{call}
+command for that. For example:
+
+@smallexample
+(@value{GDBP}) call dlopen ("libinproctrace.so", ...)
+@end smallexample
+
+Note that on most Unix systems, for the @code{dlopen} function to be
+available, the program needs to be linked with @code{-ldl}.
+@end table
+
+On systems that have a userspace dynamic loader, like most Unix
+systems, when you connect to @code{gdbserver} using @code{target
+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 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
+$ gdbserver :9999 myprogram
+@end smallexample
+
+Start GDB and connect to @code{gdbserver} like so, and run to main:
+
+@smallexample
+$ gdb myprogram
+(@value{GDBP}) target remote myhost:9999
+0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2
+(@value{GDBP}) b main
+(@value{GDBP}) continue
+@end 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, list static
+tracepoint markers, probe static tracepoints markers, and start
+tracing.
+
@node Remote Configuration
@section 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}
@tab @code{qGetTLSAddr}
@tab Displaying @code{__thread} variables
+@item @code{get-thread-information-block-address}
+@tab @code{qGetTIBAddr}
+@tab Display MS-Windows Thread Information Block.
+
@item @code{search-memory}
@tab @code{qSearch:memory}
@tab @code{find}
Without argument, this command displays information
about the six segment registers.
+@item info w32 thread-information-block
+This command displays thread specific information stored in the
+Thread Information Block (readable on the X86 CPU family using @code{$fs}
+selector for 32-bit programs and @code{$gs} for 64-bit programs).
+
@kindex info dll
@item info dll
This is a Cygwin-specific alias of @code{info shared}.
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
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.
+* Auto-loading:: Automatically loading Python code.
@end menu
@node Python Commands
@menu
* Basic Python:: Basic Python Functions.
* Exception Handling::
-* Auto-loading:: Automatically loading Python code.
* Values From Inferior::
-* Types In Python:: Python representation of types.
-* Pretty Printing:: Pretty-printing values.
+* Types In Python:: Python representation of types.
+* 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.
+* Progspaces In Python:: Program spaces.
* Objfiles In Python:: Object files.
* 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
@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
+@defun breakpoints
+Return a sequence holding all of @value{GDBN}'s breakpoints.
+@xref{Breakpoints In Python}, for more information.
@end defun
@findex gdb.parameter
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
Python statement closest to where the @value{GDBN} error occured as the
traceback.
-@node Auto-loading
-@subsubsection Auto-loading
-@cindex auto-loading, Python
-
-When a new object file is read (for example, due to the @code{file}
-command, or because the inferior has loaded a shared library),
-@value{GDBN} will look for a file named @file{@var{objfile}-gdb.py},
-where @var{objfile} is the object file's real name, formed by ensuring
-that the file name is absolute, following all symlinks, and resolving
-@code{.} and @code{..} components. If this file exists and is
-readable, @value{GDBN} will evaluate it as a Python script.
-
-If this file does not exist, and if the parameter
-@code{debug-file-directory} is set (@pxref{Separate Debug Files}),
-then @value{GDBN} will use for its each separated directory component
-@code{component} the file named @file{@code{component}/@var{real-name}}, where
-@var{real-name} is the object file's real name, as described above.
-
-Finally, if this file does not exist, then @value{GDBN} will look for
-a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where
-@var{data-directory} is @value{GDBN}'s data directory (available via
-@code{show data-directory}, @pxref{Data Files}), and @var{real-name}
-is the object file's real name, as described above.
-
-When reading an auto-loaded file, @value{GDBN} sets the ``current
-objfile''. This is available via the @code{gdb.current_objfile}
-function (@pxref{Objfiles In Python}). This can be useful for
-registering objfile-specific pretty-printers.
-
-The auto-loading feature is useful for supplying application-specific
-debugging commands and scripts. You can enable or disable this
-feature, and view its current state.
-
-@table @code
-@kindex maint set python auto-load
-@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
-Show whether Python auto-loading is enabled or disabled.
-@end table
-
-@value{GDBN} does not track which files it has already auto-loaded.
-So, your @samp{-gdb.py} file should take care to ensure that it may be
-evaluated multiple times without error.
+@findex gdb.GdbError
+When implementing @value{GDBN} commands in Python via @code{gdb.Command},
+it is useful to be able to throw an exception that doesn't cause a
+traceback to be printed. For example, the user may have invoked the
+command incorrectly. Use the @code{gdb.GdbError} exception
+to handle this case. Example:
+
+@smallexample
+(gdb) python
+>class HelloWorld (gdb.Command):
+> """Greet the whole world."""
+> def __init__ (self):
+> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
+> def invoke (self, args, from_tty):
+> argv = gdb.string_to_argv (args)
+> if len (argv) != 0:
+> raise gdb.GdbError ("hello-world takes no arguments")
+> print "Hello, World!"
+>HelloWorld ()
+>end
+(gdb) hello-world 42
+hello-world takes no arguments
+@end smallexample
@node Values From Inferior
@subsubsection Values From Inferior
convenience functions.
@end table
-@node Pretty Printing
-@subsubsection Pretty Printing
+@node Pretty Printing API
+@subsubsection Pretty Printing API
-@value{GDBN} provides a mechanism to allow pretty-printing of values
-using Python code. The pretty-printer API allows application-specific
-code to greatly simplify the display of complex objects. This
-mechanism works for both MI and the CLI.
-
-For example, here is how a C@t{++} @code{std::string} looks without a
-pretty-printer:
-
-@smallexample
-(@value{GDBP}) print s
-$1 = @{
- static npos = 4294967295,
- _M_dataplus = @{
- <std::allocator<char>> = @{
- <__gnu_cxx::new_allocator<char>> = @{<No data fields>@}, <No data fields>@},
- members of std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_Alloc_hider:
- _M_p = 0x804a014 "abcd"
- @}
-@}
-@end smallexample
-
-After a pretty-printer for @code{std::string} has been installed, only
-the contents are printed:
-
-@smallexample
-(@value{GDBP}) print s
-$2 = "abcd"
-@end smallexample
+An example output is provided (@pxref{Pretty Printing}).
A pretty-printer is just an object that holds a value and implements a
specific interface, defined here.
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
@subsubsection Selecting Pretty-Printers
The Python list @code{gdb.pretty_printers} contains an array of
-functions that have been registered via addition as a pretty-printer.
+functions or callable objects 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.
A function on one of these lists is passed a single @code{gdb.Value}
argument and should return a pretty-printer object conforming to the
-interface definition above (@pxref{Pretty Printing}). If a function
+interface definition above (@pxref{Pretty Printing API}). If a function
cannot create a pretty-printer for the value, it should return
@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 enabled function (@pxref{Disabling Pretty-Printers})
+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 enabled 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
+@code{gdb.pretty_printers} list, again calling each enabled function until an
object is returned.
The order in which the objfiles are searched is not specified. For a
printers for the specific version of the library used by each
inferior.
-To continue the @code{std::string} example (@pxref{Pretty Printing}),
+To continue the @code{std::string} example (@pxref{Pretty Printing API}),
this code might appear in @code{gdb.libstdcxx.v6}:
@smallexample
gdb.libstdcxx.v6.register_printers (gdb.current_objfile ())
@end smallexample
+@node Disabling Pretty-Printers
+@subsubsection Disabling Pretty-Printers
+@cindex disabling pretty-printers
+
+For various reasons a pretty-printer may not work.
+For example, the underlying data structure may have changed and
+the pretty-printer is out of date.
+
+The consequences of a broken pretty-printer are severe enough that
+@value{GDBN} provides support for enabling and disabling individual
+printers. For example, if @code{print frame-arguments} is on,
+a backtrace can become highly illegible if any argument is printed
+with a broken printer.
+
+Pretty-printers are enabled and disabled by attaching an @code{enabled}
+attribute to the registered function or callable object. If this attribute
+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
If this method throws an exception, it is turned into a @value{GDBN}
@code{error} call. Otherwise, the return value is ignored.
+
+@findex gdb.string_to_argv
+To break @var{argument} up into an argv-like string use
+@code{gdb.string_to_argv}. This function behaves identically to
+@value{GDBN}'s internal argument lexer @code{buildargv}.
+It is recommended to use this for consistency.
+Arguments are separated by spaces and may be quoted.
+Example:
+
+@smallexample
+print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
+['1', '2 "3', '4 "5', "6 '7"]
+@end smallexample
+
@end defmethod
@cindex completion of Python commands
Python code is read into @value{GDBN}, you may need to import the
@code{gdb} module explicitly.
+@node Parameters In Python
+@subsubsection Parameters In Python
+
+@cindex parameters in python
+@cindex python parameters
+@tindex gdb.Parameter
+@tindex Parameter
+You can implement new @value{GDBN} parameters using Python. A new
+parameter is implemented as an instance of the @code{gdb.Parameter}
+class.
+
+Parameters are exposed to the user via the @code{set} and
+@code{show} commands. @xref{Help}.
+
+There are many parameters that already exist and can be set in
+@value{GDBN}. Two examples are: @code{set follow fork} and
+@code{set charset}. Setting these parameters influences certain
+behavior in @value{GDBN}. Similarly, you can define parameters that
+can be used to influence behavior in custom Python scripts and commands.
+
+@defmethod Parameter __init__ name @var{command-class} @var{parameter-class} @r{[}@var{enum-sequence}@r{]}
+The object initializer for @code{Parameter} registers the new
+parameter with @value{GDBN}. This initializer is normally invoked
+from the subclass' own @code{__init__} method.
+
+@var{name} is the name of the new parameter. If @var{name} consists
+of multiple words, then the initial words are looked for as prefix
+parameters. An example of this can be illustrated with the
+@code{set print} set of parameters. If @var{name} is
+@code{print foo}, then @code{print} will be searched as the prefix
+parameter. In this case the parameter can subsequently be accessed in
+@value{GDBN} as @code{set print foo}.
+
+If @var{name} consists of multiple words, and no prefix parameter group
+can be found, an exception is raised.
+
+@var{command-class} should be one of the @samp{COMMAND_} constants
+(@pxref{Commands In Python}). This argument tells @value{GDBN} how to
+categorize the new parameter in the help system.
+
+@var{parameter-class} should be one of the @samp{PARAM_} constants
+defined below. This argument tells @value{GDBN} the type of the new
+parameter; this information is used for input validation and
+completion.
+
+If @var{parameter-class} is @code{PARAM_ENUM}, then
+@var{enum-sequence} must be a sequence of strings. These strings
+represent the possible values for the parameter.
+
+If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
+of a fourth argument will cause an exception to be thrown.
+
+The help text for the new parameter is taken from the Python
+documentation string for the parameter's class, if there is one. If
+there is no documentation string, a default value is used.
+@end defmethod
+
+@defivar Parameter set_doc
+If this attribute exists, and is a string, then its value is used as
+the help text for this parameter's @code{set} command. The value is
+examined when @code{Parameter.__init__} is invoked; subsequent changes
+have no effect.
+@end defivar
+
+@defivar Parameter show_doc
+If this attribute exists, and is a string, then its value is used as
+the help text for this parameter's @code{show} command. The value is
+examined when @code{Parameter.__init__} is invoked; subsequent changes
+have no effect.
+@end defivar
+
+@defivar Parameter value
+The @code{value} attribute holds the underlying value of the
+parameter. It can be read and assigned to just as any other
+attribute. @value{GDBN} does validation when assignments are made.
+@end defivar
+
+
+When a new parameter is defined, its type must be specified. The
+available types are represented by constants defined in the @code{gdb}
+module:
+
+@table @code
+@findex PARAM_BOOLEAN
+@findex gdb.PARAM_BOOLEAN
+@item PARAM_BOOLEAN
+The value is a plain boolean. The Python boolean values, @code{True}
+and @code{False} are the only valid values.
+
+@findex PARAM_AUTO_BOOLEAN
+@findex gdb.PARAM_AUTO_BOOLEAN
+@item PARAM_AUTO_BOOLEAN
+The value has three possible states: true, false, and @samp{auto}. In
+Python, true and false are represented using boolean constants, and
+@samp{auto} is represented using @code{None}.
+
+@findex PARAM_UINTEGER
+@findex gdb.PARAM_UINTEGER
+@item PARAM_UINTEGER
+The value is an unsigned integer. The value of 0 should be
+interpreted to mean ``unlimited''.
+
+@findex PARAM_INTEGER
+@findex gdb.PARAM_INTEGER
+@item PARAM_INTEGER
+The value is a signed integer. The value of 0 should be interpreted
+to mean ``unlimited''.
+
+@findex PARAM_STRING
+@findex gdb.PARAM_STRING
+@item PARAM_STRING
+The value is a string. When the user modifies the string, any escape
+sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
+translated into corresponding characters and encoded into the current
+host charset.
+
+@findex PARAM_STRING_NOESCAPE
+@findex gdb.PARAM_STRING_NOESCAPE
+@item PARAM_STRING_NOESCAPE
+The value is a string. When the user modifies the string, escapes are
+passed through untranslated.
+
+@findex PARAM_OPTIONAL_FILENAME
+@findex gdb.PARAM_OPTIONAL_FILENAME
+@item PARAM_OPTIONAL_FILENAME
+The value is a either a filename (a string), or @code{None}.
+
+@findex PARAM_FILENAME
+@findex gdb.PARAM_FILENAME
+@item PARAM_FILENAME
+The value is a filename. This is just like
+@code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
+
+@findex PARAM_ZINTEGER
+@findex gdb.PARAM_ZINTEGER
+@item PARAM_ZINTEGER
+The value is an integer. This is like @code{PARAM_INTEGER}, except 0
+is interpreted as itself.
+
+@findex PARAM_ENUM
+@findex gdb.PARAM_ENUM
+@item PARAM_ENUM
+The value is a string, which must be one of a collection string
+constants provided when the parameter is created.
+@end table
+
@node Functions In Python
@subsubsection Writing new convenience functions
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 API}, for more
+information.
+@end defivar
+
@node Objfiles In Python
@subsubsection Objfiles In Python
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
+which is used to format the value. @xref{Pretty Printing API}, for more
information.
@end defivar
@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.
writable.
@end defivar
+@node Auto-loading
+@subsection Auto-loading
+@cindex auto-loading, Python
+
+When a new object file is read (for example, due to the @code{file}
+command, or because the inferior has loaded a shared library),
+@value{GDBN} will look for Python support scripts in several ways:
+@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
+
+@menu
+* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
+* .debug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
+* Which flavor to choose?::
+@end menu
+
+The auto-loading feature is useful for supplying application-specific
+debugging commands and scripts.
+
+Auto-loading can be enabled or disabled.
+
+@table @code
+@kindex maint set python auto-load
+@item maint set python auto-load [yes|no]
+Enable or disable the Python auto-loading feature.
+
+@kindex maint show python auto-load
+@item maint show python auto-load
+Show whether Python auto-loading is enabled or disabled.
+@end table
+
+When reading an auto-loaded file, @value{GDBN} sets the
+@dfn{current objfile}. This is available via the @code{gdb.current_objfile}
+function (@pxref{Objfiles In Python}). This can be useful for
+registering objfile-specific pretty-printers.
+
+@node objfile-gdb.py file
+@subsubsection The @file{@var{objfile}-gdb.py} file
+@cindex @file{@var{objfile}-gdb.py}
+
+When a new object file is read, @value{GDBN} looks for
+a file named @file{@var{objfile}-gdb.py},
+where @var{objfile} is the object file's real name, formed by ensuring
+that the file name is absolute, following all symlinks, and resolving
+@code{.} and @code{..} components. If this file exists and is
+readable, @value{GDBN} will evaluate it as a Python script.
+
+If this file does not exist, and if the parameter
+@code{debug-file-directory} is set (@pxref{Separate Debug Files}),
+then @value{GDBN} will look for @var{real-name} in all of the
+directories mentioned in the value of @code{debug-file-directory}.
+
+Finally, if this file does not exist, then @value{GDBN} will look for
+a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where
+@var{data-directory} is @value{GDBN}'s data directory (available via
+@code{show data-directory}, @pxref{Data Files}), and @var{real-name}
+is the object file's real name, as described above.
+
+@value{GDBN} does not track which files it has already auto-loaded this way.
+@value{GDBN} will load the associated script every time the corresponding
+@var{objfile} is opened.
+So your @file{-gdb.py} file should be careful to avoid errors if it
+is evaluated more than once.
+
+@node .debug_gdb_scripts section
+@subsubsection The @code{.debug_gdb_scripts} section
+@cindex @code{.debug_gdb_scripts} section
+
+For systems using file formats like ELF and COFF,
+when @value{GDBN} loads a new object file
+it will look for a special section named @samp{.debug_gdb_scripts}.
+If this section exists, its contents is a list of names of scripts to load.
+
+@value{GDBN} will look for each specified script file first in the
+current directory and then along the source search path
+(@pxref{Source Path, ,Specifying Source Directories}),
+except that @file{$cdir} is not searched, since the compilation
+directory is not relevant to scripts.
+
+Entries can be placed in section @code{.debug_gdb_scripts} with,
+for example, this GCC macro:
+
+@example
+/* Note: The "MS" section flags are to remote duplicates. */
+#define DEFINE_GDB_SCRIPT(script_name) \
+ asm("\
+.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
+.byte 1\n\
+.asciz \"" script_name "\"\n\
+.popsection \n\
+");
+@end example
+
+@noindent
+Then one can reference the macro in a header or source file like this:
+
+@example
+DEFINE_GDB_SCRIPT ("my-app-scripts.py")
+@end example
+
+The script name may include directories if desired.
+
+If the macro is put in a header, any application or library
+using this header will get a reference to the specified script.
+
+@node Which flavor to choose?
+@subsubsection Which flavor to choose?
+
+Given the multiple ways of auto-loading Python scripts, it might not always
+be clear which one to choose. This section provides some guidance.
+
+Benefits of the @file{-gdb.py} way:
+
+@itemize @bullet
+@item
+Can be used with file formats that don't support multiple sections.
+
+@item
+Ease of finding scripts for public libraries.
+
+Scripts specified in the @code{.debug_gdb_scripts} section are searched for
+in the source search path.
+For publicly installed libraries, e.g., @file{libstdc++}, there typically
+isn't a source directory in which to find the script.
+
+@item
+Doesn't require source code additions.
+@end itemize
+
+Benefits of the @code{.debug_gdb_scripts} way:
+
+@itemize @bullet
+@item
+Works with static linking.
+
+Scripts for libraries done the @file{-gdb.py} way require an objfile to
+trigger their loading. When an application is statically linked the only
+objfile available is the executable, and it is cumbersome to attach all the
+scripts from all the input libraries to the executable's @file{-gdb.py} script.
+
+@item
+Works with classes that are entirely inlined.
+
+Some classes can be entirely inlined, and thus there may not be an associated
+shared library to attach a @file{-gdb.py} script to.
+
+@item
+Scripts needn't be copied out of the source tree.
+
+In some circumstances, apps can be built out of large collections of internal
+libraries, and the build infrastructure necessary to install the
+@file{-gdb.py} scripts in a place where @value{GDBN} can find them is
+cumbersome. It may be easier to specify the scripts in the
+@code{.debug_gdb_scripts} section as relative paths, and add a path to the
+top of the source tree to the source search path.
+@end itemize
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
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
@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
@item displayhint
A dynamic varobj can supply a display hint to the front end. The
value comes directly from the Python pretty-printer object's
-@code{display_hint} method. @xref{Pretty Printing}.
+@code{display_hint} method. @xref{Pretty Printing API}.
@end table
Typical output will look like this:
@item displayhint
A dynamic varobj can supply a display hint to the front end. The
value comes directly from the Python pretty-printer object's
-@code{display_hint} method. @xref{Pretty Printing}.
+@code{display_hint} method. @xref{Pretty Printing API}.
@item has_more
This is an integer attribute which is nonzero if there are children
the varobj @var{name} as an argument (this is done so that the same
Python pretty-printing code can be used for both the CLI and MI).
When called, this object must return an object which conforms to the
-pretty-printing interface (@pxref{Pretty Printing}).
+pretty-printing interface (@pxref{Pretty Printing API}).
The pre-defined function @code{gdb.default_visualizer} may be used to
select a visualizer by following the built-in process
@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
+
+@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}.
+
+@table @samp
+
+@item none
+No parameters are required. Stops examining trace frames.
+
+@item frame-number
+An integer is required as parameter. Selects tracepoint frame with
+that index.
+
+@item tracepoint-number
+An integer is required as parameter. Finds next
+trace frame that corresponds to tracepoint with the specified number.
+
+@item pc
+An address is required as parameter. Finds
+next trace frame that corresponds to any tracepoint at the specified
+address.
+
+@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.
+
+@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.
+
+@item line
+Line specification is required as parameter. @xref{Specify Location}.
+Finds next trace frame that corresponds to a tracepoint at
+the specified location.
+
+@end table
+
+If @samp{none} was passed as @var{mode}, the response does not
+have fields. Otherwise, the response may have the following fields:
+
+@table @samp
+@item found
+This field has either @samp{0} or @samp{1} as the value, depending
+on whether a matching tracepoint was found.
+
+@item traceframe
+The index of the found traceframe. This field is present iff
+the @samp{found} field has value of @samp{1}.
+
+@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
+
+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.
-@c @subheading -trace-actions
+@subsubheading @value{GDBN} Command
-@c @subheading -trace-delete
+The corresponding @value{GDBN} command is @samp{tstart}.
-@c @subheading -trace-disable
+@subheading -trace-status
+@findex -trace-status
-@c @subheading -trace-dump
+@subsubheading Synopsis
+
+@smallexample
+ -trace-status
+@end smallexample
+
+Obtains the status of a tracing experiment. The result may include
+the following fields:
+
+@table @samp
-@c @subheading -trace-enable
+@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.
-@c @subheading -trace-exists
+@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.
-@c @subheading -trace-find
+@end table
-@c @subheading -trace-frame-number
+@subsubheading @value{GDBN} Command
-@c @subheading -trace-info
+The corresponding @value{GDBN} command is @samp{tstatus}.
-@c @subheading -trace-insert
+@subheading -trace-stop
+@findex -trace-stop
-@c @subheading -trace-list
+@subsubheading Synopsis
-@c @subheading -trace-pass-count
+@smallexample
+ -trace-stop
+@end smallexample
-@c @subheading -trace-save
+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.
-@c @subheading -trace-start
+@subsubheading @value{GDBN} Command
-@c @subheading -trace-stop
+The corresponding @value{GDBN} command is @samp{tstop}.
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
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}.
command prints its name, address in memory, and all of its psymtabs
and symtabs.
+@kindex maint print section-scripts
+@cindex info for known .debug_gdb_scripts-loaded scripts
+@item maint print section-scripts [@var{regexp}]
+Print a dump of scripts specified in the @code{.debug_gdb_section} section.
+If @var{regexp} is specified, only print scripts loaded by object files
+matching @var{regexp}.
+For each script, this command prints its name as specified in the objfile,
+and the full path if known.
+@xref{.debug_gdb_scripts section}.
+
@kindex maint print statistics
@cindex bcache statistics
@item maint print statistics
a recursive definition of the data type as stored in @value{GDBN}'s
data structures, including its flags and contained types.
+@kindex maint set dwarf2 always-disassemble
+@kindex maint show dwarf2 always-disassemble
+@item maint set dwarf2 always-disassemble
+@item maint show dwarf2 always-disassemble
+Control the behavior of @code{info address} when using DWARF debugging
+information.
+
+The default is @code{off}, which means that @value{GDBN} should try to
+describe a variable's location in an easily readable format. When
+@code{on}, @value{GDBN} will instead display the DWARF location
+expression in an assembly-like format. Note that some locations are
+too complex for @value{GDBN} to describe simply; in this case you will
+always see the disassembly form.
+
+Here is an example of the resulting disassembly:
+
+@smallexample
+(gdb) info addr argc
+Symbol "argc" is a complex DWARF expression:
+ 1: DW_OP_fbreg 0
+@end smallexample
+
+For more information on these expressions, see
+@uref{http://www.dwarfstd.org/, the DWARF standard}.
+
@kindex maint set dwarf2 max-cache-age
@kindex maint show dwarf2 max-cache-age
@item maint set dwarf2 max-cache-age
removes a hardware breakpoint or watchpoint, and when the inferior
triggers a hardware-assisted breakpoint or watchpoint.
+@kindex maint set show-all-tib
+@kindex maint show show-all-tib
+@item maint set show-all-tib
+@itemx maint show show-all-tib
+Control whether to show all non zero areas within a 1k block starting
+at thread local base, when using the @samp{info w32 thread-information-block}
+command.
+
@kindex maint space
@cindex memory used by commands
@item maint space
@table @samp
+@item QAllow:@var{op}:@var{val}@dots{}
+@cindex @samp{QAllow} packet
+Specify which operations @value{GDBN} expects to request of the
+target, as a semicolon-separated list of operation name and value
+pairs. Possible values for @var{op} include @samp{WriteReg},
+@samp{WriteMem}, @samp{InsertBreak}, @samp{InsertTrace},
+@samp{InsertFastTrace}, and @samp{Stop}. @var{val} is either 0,
+indicating that @value{GDBN} will not request the operation, or 1,
+indicating that it may. (The target can then use this to set up its
+own internals optimally, for instance if the debugger never expects to
+insert breakpoints, it may not need to install its own trap handler.)
+
@item qC
@cindex current thread, remote request
@cindex @samp{qC} packet
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.
An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
@end table
+@item qGetTIBAddr:@var{thread-id}
+@cindex get thread information block address
+@cindex @samp{qGetTIBAddr} packet
+Fetch address of the Windows OS specific Thread Information Block.
+
+@var{thread-id} is the thread ID associated with the thread.
+
+Reply:
+@table @samp
+@item @var{XX}@dots{}
+Hex encoded (big endian) bytes representing the linear address of the
+thread information block.
+
+@item E @var{nn}
+An error occured. This means that either the thread was not found, or the
+address could not be retrieved.
+
+@item
+An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub.
+@end table
+
@item qL @var{startflag} @var{threadcount} @var{nextthread}
Obtain thread information from RTOS. Where: @var{startflag} (one hex
digit) is one to indicate the first query and zero to indicate a
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.
+
+@item qRelocInsn
+This feature indicates whether @value{GDBN} supports the
+@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate
+instruction reply packet}).
@end table
Stubs should ignore any unknown values for
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:sdata:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:spu:read}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{TracepointSource}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{QAllow}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
The remote stub understands the @samp{qXfer: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}).
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.
+
+@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::
@end table
@item qTBuffer
+@item QTBuffer
@item QTDisconnected
@itemx QTDP
+@itemx QTDPsrc
@itemx QTDV
@itemx qTfP
@itemx qTfV
@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
@table @samp
@item OK
The packet was understood and carried out.
+@item qRelocInsn
+@xref{Tracepoint Packets,,Relocate instruction reply packet}.
@item
The packet was not recognized.
@end table
@table @samp
@item OK
The packet was understood and carried out.
+@item qRelocInsn
+@xref{Tracepoint Packets,,Relocate instruction reply packet}.
@item
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
frame @emph{outside} the given range of addresses (exclusive).
@item QTStart
-Begin the tracepoint experiment. Begin collecting data from tracepoint
-hits in the trace frame buffer.
+Begin the tracepoint experiment. Begin collecting data from
+tracepoint hits in the trace frame buffer. This packet supports the
+@samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate
+instruction reply packet}).
@item QTStop
End the tracepoint experiment. Stop collecting trace frames.
@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}
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
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
+
+@subsection Relocate instruction reply packet
+When installing fast tracepoints in memory, the target may need to
+relocate the instruction currently at the tracepoint address to a
+different address in memory. For most instructions, a simple copy is
+enough, but, for example, call instructions that implicitly push the
+return address on the stack, and relative branches or other
+PC-relative instructions require offset adjustment, so that the effect
+of executing the instruction at a different address is the same as if
+it had executed in the original location.
+
+In response to several of the tracepoint packets, the target may also
+respond with a number of intermediate @samp{qRelocInsn} request
+packets before the final result packet, to have @value{GDBN} handle
+this relocation operation. If a packet supports this mechanism, its
+documentation will explicitly say so. See for example the above
+descriptions for the @samp{QTStart} and @samp{QTDP} packets. The
+format of the request is:
+
+@table @samp
+@item qRelocInsn:@var{from};@var{to}
+
+This requests @value{GDBN} to copy instruction at address @var{from}
+to address @var{to}, possibly adjusted so that executing the
+instruction at @var{to} has the same effect as executing it at
+@var{from}. @value{GDBN} writes the adjusted instruction to target
+memory starting at @var{to}.
+@end table
+
+Replies:
+@table @samp
+@item qRelocInsn:@var{adjusted_size}
+Informs the stub the relocation is complete. @var{adjusted_size} is
+the length in bytes of resulting relocated instruction sequence.
+@item E @var{NN}
+A badly formed request was detected, or an error was encountered while
+relocating the instruction.
@end table
@node Host I/O Packets
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}.
@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