@table @code
@kindex shell
+@kindex !
@cindex shell escape
-@item shell @var{command string}
-Invoke a standard shell to execute @var{command string}.
+@item shell @var{command-string}
+@itemx !@var{command-string}
+Invoke a standard shell to execute @var{command-string}.
+Note that no space is needed between @code{!} and @var{command-string}.
If it exists, the environment variable @code{SHELL} determines which
shell to run. Otherwise @value{GDBN} uses the default shell
(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
@value{GDBN} knows about preprocessor macros and can show you their
expansion (@pxref{Macros}). Most compilers do not include information
about preprocessor macros in the debugging information if you specify
-the @option{-g} flag alone, because this information is rather large.
-Version 3.1 and later of @value{NGCC}, the @sc{gnu} C compiler,
-provides macro information if you specify the options
-@option{-gdwarf-2} and @option{-g3}; the former option requests
-debugging information in the Dwarf 2 format, and the latter requests
-``extra information''. In the future, we hope to find more compact
-ways to represent macro information, so that it can be included with
-@option{-g} alone.
+the @option{-g} flag alone. Version 3.1 and later of @value{NGCC},
+the @sc{gnu} C compiler, provides macro information if you are using
+the DWARF debugging format, and specify the option @option{-g3}.
+
+@xref{Debugging Options,,Options for Debugging Your Program or GCC,
+gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}, for more
+information on @value{NGCC} options affecting debug information.
+
+You will have the best debugging experience if you use the latest
+version of the DWARF debugging format that your compiler supports.
+DWARF is currently the most expressive and best supported debugging
+format in @value{GDBN}.
@need 2000
@node Starting
is useful for multiple debugging sessions to make the execution better
reproducible and memory addresses reusable across debugging sessions.
-This feature is implemented only on @sc{gnu}/Linux. You can get the same
-behavior using
+This feature is implemented only on certain targets, including @sc{gnu}/Linux.
+On @sc{gnu}/Linux you can get the same behavior using
@smallexample
(@value{GDBP}) set exec-wrapper setarch `uname -m` -R
as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set
disable-randomization off} to try to reproduce such elusive bugs.
-The virtual address space randomization is implemented only on @sc{gnu}/Linux.
-It protects the programs against some kinds of security attacks. In these
+On targets where it is available, virtual address space randomization
+protects the programs against certain kinds of security attacks. In these
cases the attacker needs to know the exact location of a concrete executable
code. Randomizing its location makes it impossible to inject jumps misusing
a code at its expected addresses.
@menu
* Breakpoints:: Breakpoints, watchpoints, and catchpoints
* Continuing and Stepping:: Resuming execution
+* Skipping Over Functions and Files::
+ Skipping over functions and files
* Signals:: Signals
* Thread Stops:: Stopping and starting multi-thread programs
@end menu
An argument is a repeat count, as in @code{next}.
@end table
+@node Skipping Over Functions and Files
+@section Skipping Over Functions and Files
+@cindex skipping over functions and files
+
+The program you are debugging may contain some functions which are
+uninteresting to debug. The @code{skip} comand lets you tell @value{GDBN} to
+skip a function or all functions in a file when stepping.
+
+For example, consider the following C function:
+
+@smallexample
+101 int func()
+102 @{
+103 foo(boring());
+104 bar(boring());
+105 @}
+@end smallexample
+
+@noindent
+Suppose you wish to step into the functions @code{foo} and @code{bar}, but you
+are not interested in stepping through @code{boring}. If you run @code{step}
+at line 103, you'll enter @code{boring()}, but if you run @code{next}, you'll
+step over both @code{foo} and @code{boring}!
+
+One solution is to @code{step} into @code{boring} and use the @code{finish}
+command to immediately exit it. But this can become tedious if @code{boring}
+is called from many places.
+
+A more flexible solution is to execute @kbd{skip boring}. This instructs
+@value{GDBN} never to step into @code{boring}. Now when you execute
+@code{step} at line 103, you'll step over @code{boring} and directly into
+@code{foo}.
+
+You can also instruct @value{GDBN} to skip all functions in a file, with, for
+example, @code{skip file boring.c}.
+
+@table @code
+@kindex skip function
+@item skip @r{[}@var{linespec}@r{]}
+@itemx skip function @r{[}@var{linespec}@r{]}
+After running this command, the function named by @var{linespec} or the
+function containing the line named by @var{linespec} will be skipped over when
+stepping. @xref{Specify Location}.
+
+If you do not specify @var{linespec}, the function you're currently debugging
+will be skipped.
+
+(If you have a function called @code{file} that you want to skip, use
+@kbd{skip function file}.)
+
+@kindex skip file
+@item skip file @r{[}@var{filename}@r{]}
+After running this command, any function whose source lives in @var{filename}
+will be skipped over when stepping.
+
+If you do not specify @var{filename}, functions whose source lives in the file
+you're currently debugging will be skipped.
+@end table
+
+Skips can be listed, deleted, disabled, and enabled, much like breakpoints.
+These are the commands for managing your list of skips:
+
+@table @code
+@kindex info skip
+@item info skip @r{[}@var{range}@r{]}
+Print details about the specified skip(s). If @var{range} is not specified,
+print a table with details about all functions and files marked for skipping.
+@code{info skip} prints the following information about each skip:
+
+@table @emph
+@item Identifier
+A number identifying this skip.
+@item Type
+The type of this skip, either @samp{function} or @samp{file}.
+@item Enabled or Disabled
+Enabled skips are marked with @samp{y}. Disabled skips are marked with @samp{n}.
+@item Address
+For function skips, this column indicates the address in memory of the function
+being skipped. If you've set a function skip on a function which has not yet
+been loaded, this field will contain @samp{<PENDING>}. Once a shared library
+which has the function is loaded, @code{info skip} will show the function's
+address here.
+@item What
+For file skips, this field contains the filename being skipped. For functions
+skips, this field contains the function name and its line number in the file
+where it is defined.
+@end table
+
+@kindex skip delete
+@item skip delete @r{[}@var{range}@r{]}
+Delete the specified skip(s). If @var{range} is not specified, delete all
+skips.
+
+@kindex skip enable
+@item skip enable @r{[}@var{range}@r{]}
+Enable the specified skip(s). If @var{range} is not specified, enable all
+skips.
+
+@kindex skip disable
+@item skip disable @r{[}@var{range}@r{]}
+Disable the specified skip(s). If @var{range} is not specified, disable all
+skips.
+
+@end table
+
@node Signals
@section Signals
@cindex signals
To solve such problems, either recompile without optimizations, or use a
different debug info format, if the compiler supports several such
-formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler,
-usually supports the @option{-gstabs+} option. @option{-gstabs+}
-produces debug info in a format that is superior to formats such as
-COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also
-an effective form for debug info. @xref{Debugging Options,,Options
-for Debugging Your Program or GCC, gcc.info, Using the @sc{gnu}
-Compiler Collection (GCC)}.
-@xref{C, ,C and C@t{++}}, for more information about debug info formats
-that are best suited to C@t{++} programs.
+formats. @xref{Compilation}, for more information on choosing compiler
+options. @xref{C, ,C and C@t{++}}, for more information about debug
+info formats that are best suited to C@t{++} programs.
If you ask to print an object whose contents are unknown to
@value{GDBN}, e.g., because its data type is not completely specified
by the debug information, @value{GDBN} will say @samp{<incomplete
type>}. @xref{Symbols, incomplete type}, for more about this.
+If you append @kbd{@@entry} string to a function parameter name you get its
+value at the time the function got called. If the value is not available an
+error message is printed. Entry values are available only with some compilers.
+Entry values are normally also printed at the function parameter list according
+to @ref{set print entry-values}.
+
+@smallexample
+Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29
+29 i++;
+(gdb) next
+30 e (i);
+(gdb) print i
+$1 = 31
+(gdb) print i@@entry
+$2 = 30
+@end smallexample
+
Strings are identified as arrays of @code{char} values without specified
signedness. Arrays of either @code{signed char} or @code{unsigned char} get
printed as arrays of 1 byte sized integers. @code{-fsigned-char} or
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
+@anchor{set print entry-values}
+@item set print entry-values @var{value}
+@kindex set print entry-values
+Set printing of frame argument values at function entry. In some cases
+@value{GDBN} can determine the value of function argument which was passed by
+the function caller, even if the value was modified inside the called function
+and therefore is different. With optimized code, the current value could be
+unavailable, but the entry value may still be known.
+
+The default value is @code{default} (see below for its description). Older
+@value{GDBN} behaved as with the setting @code{no}. Compilers not supporting
+this feature will behave in the @code{default} setting the same way as with the
+@code{no} setting.
+
+This functionality is currently supported only by DWARF 2 debugging format and
+the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With
+@value{NGCC}, you need to specify @option{-O -g} during compilation, to get
+this information.
+
+The @var{value} parameter can be one of the following:
+
+@table @code
+@item no
+Print only actual parameter values, never print values from function entry
+point.
+@smallexample
+#0 equal (val=5)
+#0 different (val=6)
+#0 lost (val=<optimized out>)
+#0 born (val=10)
+#0 invalid (val=<optimized out>)
+@end smallexample
+
+@item only
+Print only parameter values from function entry point. The actual parameter
+values are never printed.
+@smallexample
+#0 equal (val@@entry=5)
+#0 different (val@@entry=5)
+#0 lost (val@@entry=5)
+#0 born (val@@entry=<optimized out>)
+#0 invalid (val@@entry=<optimized out>)
+@end smallexample
+
+@item preferred
+Print only parameter values from function entry point. If value from function
+entry point is not known while the actual value is known, print the actual
+value for such parameter.
+@smallexample
+#0 equal (val@@entry=5)
+#0 different (val@@entry=5)
+#0 lost (val@@entry=5)
+#0 born (val=10)
+#0 invalid (val@@entry=<optimized out>)
+@end smallexample
+
+@item if-needed
+Print actual parameter values. If actual parameter value is not known while
+value from function entry point is known, print the entry point value for such
+parameter.
+@smallexample
+#0 equal (val=5)
+#0 different (val=6)
+#0 lost (val@@entry=5)
+#0 born (val=10)
+#0 invalid (val=<optimized out>)
+@end smallexample
+
+@item both
+Always print both the actual parameter value and its value from function entry
+point, even if values of one or both are not available due to compiler
+optimizations.
+@smallexample
+#0 equal (val=5, val@@entry=5)
+#0 different (val=6, val@@entry=5)
+#0 lost (val=<optimized out>, val@@entry=5)
+#0 born (val=10, val@@entry=<optimized out>)
+#0 invalid (val=<optimized out>, val@@entry=<optimized out>)
+@end smallexample
+
+@item compact
+Print the actual parameter value if it is known and also its value from
+function entry point if it is known. If neither is known, print for the actual
+value @code{<optimized out>}. If not in MI mode (@pxref{GDB/MI}) and if both
+values are known and identical, print the shortened
+@code{param=param@@entry=VALUE} notation.
+@smallexample
+#0 equal (val=val@@entry=5)
+#0 different (val=6, val@@entry=5)
+#0 lost (val@@entry=5)
+#0 born (val=10)
+#0 invalid (val=<optimized out>)
+@end smallexample
+
+@item default
+Always print the actual parameter value. Print also its value from function
+entry point, but only if it is known. If not in MI mode (@pxref{GDB/MI}) and
+if both values are known and identical, print the shortened
+@code{param=param@@entry=VALUE} notation.
+@smallexample
+#0 equal (val=val@@entry=5)
+#0 different (val=6, val@@entry=5)
+#0 lost (val=<optimized out>, val@@entry=5)
+#0 born (val=10)
+#0 invalid (val=<optimized out>)
+@end smallexample
+@end table
+
+For analysis messages on possible failures of frame argument values at function
+entry resolution see @ref{set debug entry-values}.
+
+@item show print entry-values
+Show the method being used for printing of frame argument values at function
+entry.
+
@item set print repeats
@cindex repeated array elements
Set the threshold for suppressing display of repeated array
@cindex display derived types
When displaying a pointer to an object, identify the @emph{actual}
(derived) type of the object rather than the @emph{declared} type, using
-the virtual function table.
+the virtual function table. Note that the virtual function table is
+required---this feature can only work for objects that have run-time
+type identification; a single virtual method in the object's declared
+type is sufficient.
@item set print object off
Display only the declared type of objects, without reference to the
@menu
* Inline Functions:: How @value{GDBN} presents inlining
+* Tail Call Frames:: @value{GDBN} analysis of jumps to functions
@end menu
@node Inline Functions
@end itemize
+@node Tail Call Frames
+@section Tail Call Frames
+@cindex tail call frames, debugging
+
+Function @code{B} can call function @code{C} in its very last statement. In
+unoptimized compilation the call of @code{C} is immediately followed by return
+instruction at the end of @code{B} code. Optimizing compiler may replace the
+call and return in function @code{B} into one jump to function @code{C}
+instead. Such use of a jump instruction is called @dfn{tail call}.
+
+During execution of function @code{C}, there will be no indication in the
+function call stack frames that it was tail-called from @code{B}. If function
+@code{A} regularly calls function @code{B} which tail-calls function @code{C},
+then @value{GDBN} will see @code{A} as the caller of @code{C}. However, in
+some cases @value{GDBN} can determine that @code{C} was tail-called from
+@code{B}, and it will then create fictitious call frame for that, with the
+return address set up as if @code{B} called @code{C} normally.
+
+This functionality is currently supported only by DWARF 2 debugging format and
+the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With
+@value{NGCC}, you need to specify @option{-O -g} during compilation, to get
+this information.
+
+@kbd{info frame} command (@pxref{Frame Info}) will indicate the tail call frame
+kind by text @code{tail call frame} such as in this sample @value{GDBN} output:
+
+@smallexample
+(gdb) x/i $pc - 2
+ 0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)>
+(gdb) info frame
+Stack level 1, frame at 0x7fffffffda30:
+ rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
+ tail call frame, caller of frame at 0x7fffffffda30
+ source language c++.
+ Arglist at unknown address.
+ Locals at unknown address, Previous frame's sp is 0x7fffffffda30
+@end smallexample
+
+The detection of all the possible code path executions can find them ambiguous.
+There is no execution history stored (possible @ref{Reverse Execution} is never
+used for this purpose) and the last known caller could have reached the known
+callee by multiple different jump sequences. In such case @value{GDBN} still
+tries to show at least all the unambiguous top tail callers and all the
+unambiguous bottom tail calees, if any.
+
+@table @code
+@anchor{set debug entry-values}
+@item set debug entry-values
+@kindex set debug entry-values
+When set to on, enables printing of analysis messages for both frame argument
+values at function entry and tail calls. It will show all the possible valid
+tail calls code paths it has considered. It will also print the intersection
+of them with the final unambiguous (possibly partial or even empty) code path
+result.
+
+@item show debug entry-values
+@kindex show debug entry-values
+Show the current state of analysis messages printing for both frame argument
+values at function entry and tail calls.
+@end table
+
+The analysis messages for tail calls can for example show why the virtual tail
+call frame for function @code{c} has not been recognized (due to the indirect
+reference by variable @code{x}):
+
+@smallexample
+static void __attribute__((noinline, noclone)) c (void);
+void (*x) (void) = c;
+static void __attribute__((noinline, noclone)) a (void) @{ x++; @}
+static void __attribute__((noinline, noclone)) c (void) @{ a (); @}
+int main (void) @{ x (); return 0; @}
+
+Breakpoint 1, DW_OP_GNU_entry_value resolving cannot find
+DW_TAG_GNU_call_site 0x40039a in main
+a () at t.c:3
+3 static void __attribute__((noinline, noclone)) a (void) @{ x++; @}
+(gdb) bt
+#0 a () at t.c:3
+#1 0x000000000040039a in main () at t.c:5
+@end smallexample
+
+Another possibility is an ambiguous virtual tail call frames resolution:
+
+@smallexample
+int i;
+static void __attribute__((noinline, noclone)) f (void) @{ i++; @}
+static void __attribute__((noinline, noclone)) e (void) @{ f (); @}
+static void __attribute__((noinline, noclone)) d (void) @{ f (); @}
+static void __attribute__((noinline, noclone)) c (void) @{ d (); @}
+static void __attribute__((noinline, noclone)) b (void)
+@{ if (i) c (); else e (); @}
+static void __attribute__((noinline, noclone)) a (void) @{ b (); @}
+int main (void) @{ a (); return 0; @}
+
+tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d)
+tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e)
+tailcall: reduced: 0x4004d2(a) |
+(gdb) bt
+#0 f () at t.c:2
+#1 0x00000000004004d2 in a () at t.c:8
+#2 0x0000000000400395 in main () at t.c:9
+@end smallexample
+
+@set CALLSEQ1A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}c@value{ARROW}d@value{ARROW}f}
+@set CALLSEQ2A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}e@value{ARROW}f}
+
+@c Convert CALLSEQ#A to CALLSEQ#B depending on HAVE_MAKEINFO_CLICK.
+@ifset HAVE_MAKEINFO_CLICK
+@set ARROW @click{}
+@set CALLSEQ1B @clicksequence{@value{CALLSEQ1A}}
+@set CALLSEQ2B @clicksequence{@value{CALLSEQ2A}}
+@end ifset
+@ifclear HAVE_MAKEINFO_CLICK
+@set ARROW ->
+@set CALLSEQ1B @value{CALLSEQ1A}
+@set CALLSEQ2B @value{CALLSEQ2A}
+@end ifclear
+
+Frames #0 and #2 are real, #1 is a virtual tail call frame.
+The code can have possible execution paths @value{CALLSEQ1B} or
+@value{CALLSEQ2B}, @value{GDBN} cannot find which one from the inferior state.
+
+@code{initial:} state shows some random possible calling sequence @value{GDBN}
+has found. It then finds another possible calling sequcen - that one is
+prefixed by @code{compare:}. The non-ambiguous intersection of these two is
+printed as the @code{reduced:} calling sequence. That one could have many
+futher @code{compare:} and @code{reduced:} statements as long as there remain
+any non-ambiguous sequence entries.
+
+For the frame of function @code{b} in both cases there are different possible
+@code{$pc} values (@code{0x4004cc} or @code{0x4004ce}), therefore this frame is
+also ambigous. The only non-ambiguous frame is the one for function @code{a},
+therefore this one is displayed to the user while the ambiguous frames are
+omitted.
+
+There can be also reasons why printing of frame argument values at function
+entry may fail:
+
+@smallexample
+int v;
+static void __attribute__((noinline, noclone)) c (int i) @{ v++; @}
+static void __attribute__((noinline, noclone)) a (int i);
+static void __attribute__((noinline, noclone)) b (int i) @{ a (i); @}
+static void __attribute__((noinline, noclone)) a (int i)
+@{ if (i) b (i - 1); else c (0); @}
+int main (void) @{ a (5); return 0; @}
+
+(gdb) bt
+#0 c (i=i@@entry=0) at t.c:2
+#1 0x0000000000400428 in a (DW_OP_GNU_entry_value resolving has found
+function "a" at 0x400420 can call itself via tail calls
+i=<optimized out>) at t.c:6
+#2 0x000000000040036e in main () at t.c:7
+@end smallexample
+
+@value{GDBN} cannot find out from the inferior state if and how many times did
+function @code{a} call itself (via function @code{b}) as these calls would be
+tail calls. Such tail calls would modify thue @code{i} variable, therefore
+@value{GDBN} cannot be sure the value it knows would be right - @value{GDBN}
+prints @code{<optimized out>} instead.
@node Macros
@chapter C Preprocessor Macros
@cindex macro definition, showing
@cindex definition of a macro, showing
@cindex macros, from debug info
-@item info macro @var{macro}
-Show the current definition of the named @var{macro}, and describe the
-source location or compiler command-line where that definition was established.
+@item info macro [-a|-all] [--] @var{macro}
+Show the current definition or all definitions of the named @var{macro},
+and describe the source location or compiler command-line where that
+definition was established. The optional double dash is to signify the end of
+argument processing and the beginning of @var{macro} for non C-like macros where
+the macro may begin with a hyphen.
@kindex info macros
@item info macros @var{linespec}
by @var{linespec}, and describe the source location or compiler
command-line where those definitions were established.
-@kindex info definitions
-@item info definitions @var{macro}
-Show all definitions of the named @var{macro} that are defined in the current
-compilation unit, and describe the source location or compiler command-line
-where those definitions were established.
-
@kindex macro define
@cindex user-defined macros
@cindex defining macros interactively
$
@end smallexample
-Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}.
-We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the
-compiler includes information about preprocessor macros in the debugging
+Now, we compile the program using the @sc{gnu} C compiler,
+@value{NGCC}. We pass the @option{-gdwarf-2}@footnote{This is the
+minimum. Recent versions of @value{NGCC} support @option{-gdwarf-3}
+and @option{-gdwarf-4}; we recommend always choosing the most recent
+version of DWARF.} @emph{and} @option{-g3} flags to ensure the compiler
+includes information about preprocessor macros in the debugging
information.
@smallexample
@code{trace} command defines a tracepoint, which is a point in the
target program where the debugger will briefly stop, collect some
data, and then allow the program to continue. Setting a tracepoint or
-changing its actions doesn't take effect until the next @code{tstart}
+changing its actions takes effect immediately if the remote stub
+supports the @samp{InstallInTrace} feature (@pxref{install tracepoint
+in tracing}).
+If remote stub doesn't support the @samp{InstallInTrace} feature, all
+these changes don't take effect until the next @code{tstart}
command, and once a trace experiment is running, further changes will
-not have any effect until the next trace experiment starts.
+not have any effect until the next trace experiment starts. In addition,
+@value{GDBN} supports @dfn{pending tracepoints}---tracepoints whose
+address is not yet resolved. (This is similar to pending breakpoints.)
+Pending tracepoints are not downloaded to the target and not installed
+until they are resolved. The resolution of pending tracepoints requires
+@value{GDBN} support---when debugging with the remote target, and
+@value{GDBN} disconnects from the remote stub (@pxref{disconnected
+tracing}), pending tracepoints can not be resolved (and downloaded to
+the remote stub) while @value{GDBN} is disconnected.
Here are some examples of using the @code{trace} command:
@value{GDBN} handles arguments to @code{ftrace} exactly as for
@code{trace}.
+On 32-bit x86-architecture systems, fast tracepoints normally need to
+be placed at an instruction that is 5 bytes or longer, but can be
+placed at 4-byte instructions if the low 64K of memory of the target
+program is available to install trampolines. Some Unix-type systems,
+such as @sc{gnu}/Linux, exclude low addresses from the program's
+address space; but for instance with the Linux kernel it is possible
+to let @value{GDBN} use this area by doing a @command{sysctl} command
+to set the @code{mmap_min_addr} kernel parameter, as in
+
+@example
+sudo sysctl -w vm.mmap_min_addr=32768
+@end example
+
+@noindent
+which sets the low address to 32K, which leaves plenty of room for
+trampolines. The minimum address should be set to a page boundary.
+
@item strace @var{location} [ if @var{cond} ]
@cindex set static tracepoint
@cindex static tracepoints, setting
@end smallexample
@kindex collect @r{(tracepoints)}
-@item collect @var{expr1}, @var{expr2}, @dots{}
+@item collect@r{[}/@var{mods}@r{]} @var{expr1}, @var{expr2}, @dots{}
Collect values of the given expressions when the tracepoint is hit.
This command accepts a comma-separated list of any valid expressions.
In addition to global, static, or local variables, the following
@item $locals
Collect all local variables.
+@item $_ret
+Collect the return address. This is helpful if you want to see more
+of a backtrace.
+
@item $_sdata
@vindex $_sdata@r{, collect}
Collect static tracepoint marker specific data. Only available for
with a single argument, or one @code{collect} command with several
arguments separated by commas; the effect is the same.
+The optional @var{mods} changes the usual handling of the arguments.
+@code{s} requests that pointers to chars be handled as strings, in
+particular collecting the contents of the memory being pointed at, up
+to the first zero. The upper bound is by default the value of the
+@code{print elements} variable; if @code{s} is followed by a decimal
+number, that is the upper bound instead. So for instance
+@samp{collect/s25 mystr} collects as many as 25 characters at
+@samp{mystr}.
+
The command @code{info scope} (@pxref{Symbols, info scope}) is
particularly useful for figuring out what data to collect.
@subsection Starting and Stopping Trace Experiments
@table @code
-@kindex tstart
+@kindex tstart [ @var{notes} ]
@cindex start a new trace experiment
@cindex collected data discarded
@item tstart
-This command takes no arguments. It starts the trace experiment, and
-begins collecting data. This has the side effect of discarding all
-the data collected in the trace buffer during the previous trace
-experiment.
-
-@kindex tstop
+This command starts the trace experiment, and begins collecting data.
+It has the side effect of discarding all the data collected in the
+trace buffer during the previous trace experiment. If any arguments
+are supplied, they are taken as a note and stored with the trace
+experiment's state. The notes may be arbitrary text, and are
+especially useful with disconnected tracing in a multi-user context;
+the notes can explain what the trace is doing, supply user contact
+information, and so forth.
+
+@kindex tstop [ @var{notes} ]
@cindex stop a running trace experiment
@item tstop
-This command takes no arguments. It ends the trace experiment, and
-stops collecting data.
+This command stops the trace experiment. If any arguments are
+supplied, they are recorded with the experiment as a note. This is
+useful if you are stopping a trace started by someone else, for
+instance if the trace is interfering with the system's behavior and
+needs to be stopped quickly.
@strong{Note}: a trace experiment and data collection may stop
automatically if any tracepoint's passcount is reached
@end table
+@table @code
+@item set trace-user @var{text}
+@kindex set trace-user
+
+@item show trace-user
+@kindex show trace-user
+
+@item set trace-notes @var{text}
+@kindex set trace-notes
+Set the trace run's notes.
+
+@item show trace-notes
+@kindex show trace-notes
+Show the trace run's notes.
+
+@item set trace-stop-notes @var{text}
+@kindex set trace-stop-notes
+Set the trace run's stop notes. The handling of the note is as for
+@code{tstop} arguments; the set command is convenient way to fix a
+stop note that is mistaken or incomplete.
+
+@item show trace-stop-notes
+@kindex show trace-stop-notes
+Show the trace run's stop notes.
+
+@end table
+
@node Tracepoint Restrictions
@subsection Tracepoint Restrictions
@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}
+bytes from the stack pointer with something like @code{*(unsigned char *)$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
C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
compiler (@code{aCC}).
-For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging
-format; if it doesn't work on your system, try the stabs+ debugging
-format. You can select those formats explicitly with the @code{g++}
-command-line options @option{-gdwarf-2} and @option{-gstabs+}.
-@xref{Debugging Options,,Options for Debugging Your Program or GCC,
-gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}.
-
@menu
* C Operators:: C and C@t{++} operators
* C Constants:: C and C@t{++} constants
@samp{@var{x}} is a predefined special character---for example,
@samp{\n} for newline.
+Wide character constants can be written by prefixing a character
+constant with @samp{L}, as in C. For example, @samp{L'x'} is the wide
+form of @samp{x}. The target wide character set is used when
+computing the value of this constant (@pxref{Character Sets}).
+
@item
String constants are a sequence of character constants surrounded by
double quotes (@code{"}). Any valid character constant (as described
a backslash, so for instance @samp{"a\"b'c"} is a string of five
characters.
+Wide string constants can be written by prefixing a string constant
+with @samp{L}, as in C. The target wide character set is used when
+computing the value of this constant (@pxref{Character Sets}).
+
@item
Pointer constants are an integral value. You can also write pointers
to constants using the C operator @samp{&}.
@cindex debug formats and C@t{++}
@cindex @value{NGCC} and C@t{++}
@quotation
-@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
-proper compiler and the proper debug format. Currently, @value{GDBN}
-works best when debugging C@t{++} code that is compiled with
-@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
-@option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over
-stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or
-stabs+ as their default debug format, so you usually don't need to
-specify a debug format explicitly. Other compilers and/or debug formats
-are likely to work badly or not at all when using @value{GDBN} to debug
-C@t{++} code.
+@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use
+the proper compiler and the proper debug format. Currently,
+@value{GDBN} works best when debugging C@t{++} code that is compiled
+with the most recent version of @value{NGCC} possible. The DWARF
+debugging format is preferred; @value{NGCC} defaults to this on most
+popular platforms. Other compilers and/or debug formats are likely to
+work badly or not at all when using @value{GDBN} to debug C@t{++}
+code. @xref{Compilation}.
@end quotation
@enumerate
While a member function is active (in the selected stack frame), your
expressions have the same namespace available as the member function;
that is, @value{GDBN} allows implicit references to the class instance
-pointer @code{this} following the same rules as C@t{++}.
+pointer @code{this} following the same rules as C@t{++}. @code{using}
+declarations in the current scope are also respected by @value{GDBN}.
@cindex call overloaded functions
@cindex overloaded functions, calling
@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
resolving name scope by reference to source files, in both C and C@t{++}
debugging (@pxref{Variables, ,Program Variables}).
-@end enumerate
-In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports
-calling virtual functions correctly, printing out virtual bases of
-objects, calling functions in a base subobject, casting objects, and
-invoking user-defined operators.
+@item
+@value{GDBN} performs argument-dependent lookup, following the C@t{++}
+specification.
+@end enumerate
@node C Defaults
@subsubsection C and C@t{++} Defaults
@cindex dynamic linking
@item add-symbol-file @var{filename} @var{address}
@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]}
-@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
+@itemx add-symbol-file @var{filename} @var{address} -s @var{section} @var{address} @dots{}
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
when @var{filename} has been dynamically loaded (by some other means)
into the program that is running. @var{address} should be the memory
address at which the file has been loaded; @value{GDBN} cannot figure
this out for itself. You can additionally specify an arbitrary number
-of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit
+of @samp{-s @var{section} @var{address}} pairs, to give an explicit
section name and base address for that section. You can specify any
@var{address} as an expression.
@end table
@end table
+@cindex file name canonicalization
+@cindex base name differences
+When processing file names provided by the user, @value{GDBN}
+frequently needs to compare them to the file names recorded in the
+program's debug info. Normally, @value{GDBN} compares just the
+@dfn{base names} of the files as strings, which is reasonably fast
+even for very large programs. (The base name of a file is the last
+portion of its name, after stripping all the leading directories.)
+This shortcut in comparison is based upon the assumption that files
+cannot have more than one base name. This is usually true, but
+references to files that use symlinks or similar filesystem
+facilities violate that assumption. If your program records files
+using such facilities, or if you provide file names to @value{GDBN}
+using symlinks etc., you can set @code{basenames-may-differ} to
+@code{true} to instruct @value{GDBN} to completely canonicalize each
+pair of file names it needs to compare. This will make file-name
+comparisons accurate, but at a price of a significant slowdown.
+
+@table @code
+@item set basenames-may-differ
+@kindex set basenames-may-differ
+Set whether a source file may have multiple base names.
+
+@item show basenames-may-differ
+@kindex show basenames-may-differ
+Show whether a source file may have multiple base names.
+@end table
@node Separate Debug Files
@section Debugging Information in Separate Files
@item @code{traceframe-info}
@tab @code{qXfer:traceframe-info:read}
@tab Traceframe info
+
+@item @code{install-in-trace}
+@tab @code{InstallInTrace}
+@tab Install tracepoint in tracing
+
+@item @code{disable-randomization}
+@tab @code{QDisableRandomization}
+@tab @code{set disable-randomization}
@end multitable
@node Remote Stub
@item n64
@item eabi32
@item eabi64
-@item auto
@end table
@item show mips abi
@chapter Extending @value{GDBN}
@cindex extending GDB
-@value{GDBN} provides two mechanisms for extension. The first is based
-on composition of @value{GDBN} commands, and the second is based on the
-Python scripting language.
+@value{GDBN} provides three mechanisms for extension. The first is based
+on composition of @value{GDBN} commands, the second is based on the
+Python scripting language, and the third is for defining new aliases of
+existing commands.
-To facilitate the use of these extensions, @value{GDBN} is capable
+To facilitate the use of the first two extensions, @value{GDBN} is capable
of evaluating the contents of a file. When doing so, @value{GDBN}
can recognize which scripting language is being used by looking at
the filename extension. Files with an unrecognized filename extension
@menu
* Sequences:: Canned Sequences of Commands
* Python:: Scripting @value{GDBN} using Python
+* Aliases:: Creating new spellings of existing commands
@end menu
@node Sequences
it will just return the static type of the value as in @kbd{ptype foo}
(@pxref{Symbols, ptype}).
@end defvar
+
+@defvar Value.is_lazy
+The value of this read-only boolean attribute is @code{True} if this
+@code{gdb.Value} has not yet been fetched from the inferior.
+@value{GDBN} does not fetch values until necessary, for efficiency.
+For example:
+
+@smallexample
+myval = gdb.parse_and_eval ('somevar')
+@end smallexample
+
+The value of @code{somevar} is not fetched at this time. It will be
+fetched when the value is needed, or when the @code{fetch_lazy}
+method is invoked.
+@end defvar
@end table
The following methods are provided:
the @var{length} argument is not provided, the string will be fetched
and encoded until a null of appropriate width is found.
@end defun
+
+@defun Value.fetch_lazy ()
+If the @code{gdb.Value} object is currently a lazy value
+(@code{gdb.Value.is_lazy} is @code{True}), then the value is
+fetched from the inferior. Any errors that occur in the process
+will produce a Python exception.
+
+If the @code{gdb.Value} object is not a lazy value, this method
+has no effect.
+
+This method does not return a value.
+@end defun
+
@end table
@node Types In Python
If the named type cannot be found, it will throw an exception.
@end defun
+If the type is a structure or class type, or an enum type, the fields
+of that type can be accessed using the Python @dfn{dictionary syntax}.
+For example, if @code{some_type} is a @code{gdb.Type} instance holding
+a structure type, you can access its @code{foo} field with:
+
+@smallexample
+bar = some_type['foo']
+@end smallexample
+
+@code{bar} will be a @code{gdb.Field} object; see below under the
+description of the @code{Type.fields} method for a description of the
+@code{gdb.Field} class.
+
An instance of @code{Type} has the following attributes:
@table @code
represented as fields. If the type has no fields, or does not fit
into one of these categories, an empty sequence will be returned.
-Each field is an object, with some pre-defined attributes:
+Each field is a @code{gdb.Field} object, with some pre-defined attributes:
@table @code
@item bitpos
This attribute is not available for @code{static} fields (as in
@item events.exited
Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
-@code{events.ExitedEvent} has one optional attribute. This attribute
-will exist only in the case that the inferior exited with some
-status.
+@code{events.ExitedEvent} has two attributes:
@table @code
@defvar ExitedEvent.exit_code
-An integer representing the exit code which the inferior has returned.
+An integer representing the exit code, if available, which the inferior
+has returned. (The exit code could be unavailable if, for example,
+@value{GDBN} detaches from the inferior.) If the exit code is unavailable,
+the attribute does not exist.
+@end defvar
+@defvar ExitedEvent inferior
+A reference to the inferior which triggered the @code{exited} event.
@end defvar
@end table
@end defvar
@end table
+@item events.new_objfile
+Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
+been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
+
+@table @code
+@defvar NewObjFileEvent.new_objfile
+A reference to the object file (@code{gdb.Objfile}) which has been loaded.
+@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
+@end defvar
+@end table
+
@end table
@node Threads In Python
command is implemented using an instance of the @code{gdb.Command}
class, most commonly using a subclass.
-@defun Command.__init__ (name, @var{command_class} @r{[}, var{completer_class} @r{[}, var{prefix}@r{]]})
+@defun Command.__init__ (name, @var{command_class} @r{[}, @var{completer_class} @r{[}, @var{prefix}@r{]]})
The object initializer for @code{Command} registers the new command
with @value{GDBN}. This initializer is normally invoked from the
subclass' own @code{__init__} method.
A frame representing an inlined function. The function was inlined
into a @code{gdb.NORMAL_FRAME} that is older than this one.
+@item gdb.TAILCALL_FRAME
+A frame representing a tail call. @xref{Tail Call Frames}.
+
@item gdb.SIGTRAMP_FRAME
A signal trampoline frame. This is the frame created by the OS when
it calls into a signal handler.
Return an integer representing the reason why it's not possible to find
more frames toward the outermost frame. Use
@code{gdb.frame_stop_reason_string} to convert the value returned by this
-function to a string.
+function to a string. The value can be one of:
+
+@table @code
+@item gdb.FRAME_UNWIND_NO_REASON
+No particular reason (older frames should be available).
+
+@item gdb.FRAME_UNWIND_NULL_ID
+The previous frame's analyzer returns an invalid result.
+
+@item gdb.FRAME_UNWIND_OUTERMOST
+This frame is the outermost.
+
+@item gdb.FRAME_UNWIND_UNAVAILABLE
+Cannot unwind further, because that would require knowing the
+values of registers or memory that have not been collected.
+
+@item gdb.FRAME_UNWIND_INNER_ID
+This frame ID looks like it ought to belong to a NEXT frame,
+but we got it for a PREV frame. Normally, this is a sign of
+unwinder failure. It could also indicate stack corruption.
+
+@item gdb.FRAME_UNWIND_SAME_ID
+This frame has the same ID as the previous one. That means
+that unwinding further would almost certainly give us another
+frame with exactly the same ID, so break the chain. Normally,
+this is a sign of unwinder failure. It could also indicate
+stack corruption.
+
+@item gdb.FRAME_UNWIND_NO_SAVED_PC
+The frame unwinder did not find any saved PC, but we needed
+one to unwind further.
+
+@item gdb.FRAME_UNWIND_FIRST_ERROR
+Any stop reason greater or equal to this value indicates some kind
+of error. This special value facilitates writing code that tests
+for errors in unwinding in a way that will work correctly even if
+the list of the other values is modified in future @value{GDBN}
+versions. Using it, you could write:
+@smallexample
+reason = gdb.selected_frame().unwind_stop_reason ()
+reason_str = gdb.frame_stop_reason_string (reason)
+if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
+ print "An error occured: %s" % reason_str
+@end smallexample
+@end table
+
@end defun
@defun Frame.pc ()
The block containing this block. If this parent block does not exist,
this attribute holds @code{None}. This attribute is not writable.
@end defvar
+
+@defvar Block.global_block
+The global block associated with this block. This attribute is not
+writable.
+@end defvar
+
+@defvar Block.static_block
+The static block associated with this block. This attribute is not
+writable.
+@end defvar
+
+@defvar Block.is_global
+@code{True} if the @code{gdb.Block} object is a global block,
+@code{False} if not. This attribute is not
+writable.
+@end defvar
+
+@defvar Block.is_static
+@code{True} if the @code{gdb.Block} object is a static block,
+@code{False} if not. This attribute is not writable.
+@end defvar
@end table
@node Symbols In Python
if one of the methods returns @code{True} but the others return
@code{False}, the inferior will still be stopped.
+You should not alter the execution state of the inferior (i.e.@:, step,
+next, etc.), alter the current frame context (i.e.@:, change the current
+active frame), or alter, add or delete any breakpoint. As a general
+rule, you should not alter any data within @value{GDBN} or the inferior
+at this time.
+
Example @code{stop} implementation:
@smallexample
regular expressions.
@xref{Writing a Pretty-Printer}, for an example.
-@item register_pretty_printer (@var{obj}, @var{printer})
+@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
Register @var{printer} with the pretty-printer list of @var{obj}.
+If @var{replace} is @code{True} then any existing copy of the printer
+is replaced. Otherwise a @code{RuntimeError} exception is raised
+if a printer with the same name already exists.
@end table
@node gdb.types
@item make_enum_dict (@var{enum_type})
Return a Python @code{dictionary} type produced from @var{enum_type}.
+
+@item deep_items (@var{type})
+Returns a Python iterator similar to the standard
+@code{gdb.Type.iteritems} method, except that the iterator returned
+by @code{deep_items} will recursively traverse anonymous struct or
+union fields. For example:
+
+@smallexample
+struct A
+@{
+ int a;
+ union @{
+ int b0;
+ int b1;
+ @};
+@};
+@end smallexample
+
+@noindent
+Then in @value{GDBN}:
+@smallexample
+(@value{GDBP}) python import gdb.types
+(@value{GDBP}) python struct_a = gdb.lookup_type("struct A")
+(@value{GDBP}) python print struct_a.keys ()
+@{['a', '']@}
+(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)]
+@{['a', 'b0', 'b1']@}
+@end smallexample
+
@end table
@node gdb.prompt
@end smallexample
@end table
+@node Aliases
+@section Creating new spellings of existing commands
+@cindex aliases for commands
+
+It is often useful to define alternate spellings of existing commands.
+For example, if a new @value{GDBN} command defined in Python has
+a long name to type, it is handy to have an abbreviated version of it
+that involves less typing.
+
+@value{GDBN} itself uses aliases. For example @samp{s} is an alias
+of the @samp{step} command even though it is otherwise an ambiguous
+abbreviation of other commands like @samp{set} and @samp{show}.
+
+Aliases are also used to provide shortened or more common versions
+of multi-word commands. For example, @value{GDBN} provides the
+@samp{tty} alias of the @samp{set inferior-tty} command.
+
+You can define a new alias with the @samp{alias} command.
+
+@table @code
+
+@kindex alias
+@item alias [-a] [--] @var{ALIAS} = @var{COMMAND}
+
+@end table
+
+@var{ALIAS} specifies the name of the new alias.
+Each word of @var{ALIAS} must consist of letters, numbers, dashes and
+underscores.
+
+@var{COMMAND} specifies the name of an existing command
+that is being aliased.
+
+The @samp{-a} option specifies that the new alias is an abbreviation
+of the command. Abbreviations are not shown in command
+lists displayed by the @samp{help} command.
+
+The @samp{--} option specifies the end of options,
+and is useful when @var{ALIAS} begins with a dash.
+
+Here is a simple example showing how to make an abbreviation
+of a command so that there is less to type.
+Suppose you were tired of typing @samp{disas}, the current
+shortest unambiguous abbreviation of the @samp{disassemble} command
+and you wanted an even shorter version named @samp{di}.
+The following will accomplish this.
+
+@smallexample
+(gdb) alias -a di = disas
+@end smallexample
+
+Note that aliases are different from user-defined commands.
+With a user-defined command, you also need to write documentation
+for it with the @samp{document} command.
+An alias automatically picks up the documentation of the existing command.
+
+Here is an example where we make @samp{elms} an abbreviation of
+@samp{elements} in the @samp{set print elements} command.
+This is to show that you can make an abbreviation of any part
+of a command.
+
+@smallexample
+(gdb) alias -a set print elms = set print elements
+(gdb) alias -a show print elms = show print elements
+(gdb) set p elms 20
+(gdb) show p elms
+Limit on string chars or array elements to print is 200.
+@end smallexample
+
+Note that if you are defining an alias of a @samp{set} command,
+and you want to have an alias for the corresponding @samp{show}
+command, then you need to define the latter separately.
+
+Unambiguously abbreviated commands are allowed in @var{COMMAND} and
+@var{ALIAS}, just as they are normally.
+
+@smallexample
+(gdb) alias -a set pr elms = set p ele
+@end smallexample
+
+Finally, here is an example showing the creation of a one word
+alias for a more complex command.
+This creates alias @samp{spe} of the command @samp{set print elements}.
+
+@smallexample
+(gdb) alias spe = set print elements
+(gdb) spe 20
+@end smallexample
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
* GDB/MI Breakpoint Commands::
* GDB/MI Program Context::
* GDB/MI Thread Commands::
+* GDB/MI Ada Tasking Commands::
* GDB/MI Program Execution::
* GDB/MI Stack Manipulation::
* GDB/MI Variable Objects::
The inferior exited normally.
@item signal-received
A signal was received by the inferior.
+@item solib-event
+The inferior has stopped due to a library being loaded or unloaded.
+This can only happen when @code{stop-on-solib-events} (@pxref{Files})
+is set.
+@item fork
+The inferior has forked. This is reported when @code{catch fork}
+(@pxref{Set Catchpoints}) has been used.
+@item vfork
+The inferior has vforked. This is reported in when @code{catch vfork}
+(@pxref{Set Catchpoints}) has been used.
+@item syscall-entry
+The inferior entered a system call. This is reported when @code{catch
+syscall} (@pxref{Set Catchpoints}) has been used.
+@item syscall-entry
+The inferior returned from a system call. This is reported when
+@code{catch syscall} (@pxref{Set Catchpoints}) has been used.
+@item exec
+The inferior called @code{exec}. This is reported when @code{catch exec}
+(@pxref{Set Catchpoints}) has been used.
@end table
The @var{id} field identifies the thread that directly caused the stop
(gdb)
@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Ada Tasking Commands
+@section @sc{gdb/mi} Ada Tasking Commands
+
+@subheading The @code{-ada-task-info} Command
+@findex -ada-task-info
+
+@subsubheading Synopsis
+
+@smallexample
+ -ada-task-info [ @var{task-id} ]
+@end smallexample
+
+Reports information about either a specific Ada task, if the
+@var{task-id} parameter is present, or about all Ada tasks.
+
+@subsubheading @value{GDBN} Command
+
+The @samp{info tasks} command prints the same information
+about all Ada tasks (@pxref{Ada Tasks}).
+
+@subsubheading Result
+
+The result is a table of Ada tasks. The following columns are
+defined for each Ada task:
+
+@table @samp
+@item current
+This field exists only for the current thread. It has the value @samp{*}.
+
+@item id
+The identifier that @value{GDBN} uses to refer to the Ada task.
+
+@item task-id
+The identifier that the target uses to refer to the Ada task.
+
+@item thread-id
+The identifier of the thread corresponding to the Ada task.
+
+This field should always exist, as Ada tasks are always implemented
+on top of a thread. But if @value{GDBN} cannot find this corresponding
+thread for any reason, the field is omitted.
+
+@item parent-id
+This field exists only when the task was created by another task.
+In this case, it provides the ID of the parent task.
+
+@item priority
+The base priority of the task.
+
+@item state
+The current state of the task. For a detailed description of the
+possible states, see @ref{Ada Tasks}.
+
+@item name
+The name of the task.
+
+@end table
+
+@subsubheading Example
+
+@smallexample
+-ada-task-info
+^done,tasks=@{nr_rows="3",nr_cols="8",
+hdr=[@{width="1",alignment="-1",col_name="current",colhdr=""@},
+@{width="3",alignment="1",col_name="id",colhdr="ID"@},
+@{width="9",alignment="1",col_name="task-id",colhdr="TID"@},
+@{width="4",alignment="1",col_name="thread-id",colhdr=""@},
+@{width="4",alignment="1",col_name="parent-id",colhdr="P-ID"@},
+@{width="3",alignment="1",col_name="priority",colhdr="Pri"@},
+@{width="22",alignment="-1",col_name="state",colhdr="State"@},
+@{width="1",alignment="2",col_name="name",colhdr="Name"@}],
+body=[@{current="*",id="1",task-id=" 644010",thread-id="1",priority="48",
+state="Child Termination Wait",name="main_task"@}]@}
+(gdb)
+@end smallexample
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Execution
@section @sc{gdb/mi} Program Execution
@table @samp
@item frozen-varobjs
-Indicates presence of the @code{-var-set-frozen} command, as well
-as possible presense of the @code{frozen} field in the output
+Indicates support for the @code{-var-set-frozen} command, as well
+as possible presense of the @code{frozen} field in the output
of @code{-varobj-create}.
@item pending-breakpoints
-Indicates presence of the @option{-f} option to the @code{-break-insert} command.
+Indicates support for the @option{-f} option to the @code{-break-insert}
+command.
@item python
-Indicates presence of Python scripting support, Python-based
+Indicates Python scripting support, Python-based
pretty-printing commands, and possible presence of the
@samp{display_hint} field in the output of @code{-var-list-children}
@item thread-info
-Indicates presence of the @code{-thread-info} command.
+Indicates support for the @code{-thread-info} command.
@item data-read-memory-bytes
-Indicates presense of the @code{-data-read-memory-bytes} and the
+Indicates support for the @code{-data-read-memory-bytes} and the
@code{-data-write-memory-bytes} commands.
@item breakpoint-notifications
Indicates that changes to breakpoints and breakpoints created via the
CLI will be announced via async records.
-
+@item ada-task-info
+Indicates support for the @code{-ada-task-info} command.
@end table
@subheading The @code{-list-target-features} Command
* Declarations:: Relevant C struct declarations
* Registering Code:: Steps to register code
* Unregistering Code:: Steps to unregister code
+* Custom Debug Info:: Emit debug information in a custom format
@end menu
@node Declarations
If the JIT frees or recompiles code without unregistering it, then @value{GDBN}
and the JIT will leak the memory used for the associated symbol files.
+@node Custom Debug Info
+@section Custom Debug Info
+@cindex custom JIT debug info
+@cindex JIT debug info reader
+
+Generating debug information in platform-native file formats (like ELF
+or COFF) may be an overkill for JIT compilers; especially if all the
+debug info is used for is displaying a meaningful backtrace. The
+issue can be resolved by having the JIT writers decide on a debug info
+format and also provide a reader that parses the debug info generated
+by the JIT compiler. This section gives a brief overview on writing
+such a parser. More specific details can be found in the source file
+@file{gdb/jit-reader.in}, which is also installed as a header at
+@file{@var{includedir}/gdb/jit-reader.h} for easy inclusion.
+
+The reader is implemented as a shared object (so this functionality is
+not available on platforms which don't allow loading shared objects at
+runtime). Two @value{GDBN} commands, @code{jit-reader-load} and
+@code{jit-reader-unload} are provided, to be used to load and unload
+the readers from a preconfigured directory. Once loaded, the shared
+object is used the parse the debug information emitted by the JIT
+compiler.
+
+@menu
+* Using JIT Debug Info Readers:: How to use supplied readers correctly
+* Writing JIT Debug Info Readers:: Creating a debug-info reader
+@end menu
+
+@node Using JIT Debug Info Readers
+@subsection Using JIT Debug Info Readers
+@kindex jit-reader-load
+@kindex jit-reader-unload
+
+Readers can be loaded and unloaded using the @code{jit-reader-load}
+and @code{jit-reader-unload} commands.
+
+@table @code
+@item jit-reader-load @var{reader-name}
+Load the JIT reader named @var{reader-name}. On a UNIX system, this
+will usually load @file{@var{libdir}/gdb/@var{reader-name}}, where
+@var{libdir} is the system library directory, usually
+@file{/usr/local/lib}. Only one reader can be active at a time;
+trying to load a second reader when one is already loaded will result
+in @value{GDBN} reporting an error. A new JIT reader can be loaded by
+first unloading the current one using @code{jit-reader-load} and then
+invoking @code{jit-reader-load}.
+
+@item jit-reader-unload
+Unload the currently loaded JIT reader.
+
+@end table
+
+@node Writing JIT Debug Info Readers
+@subsection Writing JIT Debug Info Readers
+@cindex writing JIT debug info readers
+
+As mentioned, a reader is essentially a shared object conforming to a
+certain ABI. This ABI is described in @file{jit-reader.h}.
+
+@file{jit-reader.h} defines the structures, macros and functions
+required to write a reader. It is installed (along with
+@value{GDBN}), in @file{@var{includedir}/gdb} where @var{includedir} is
+the system include directory.
+
+Readers need to be released under a GPL compatible license. A reader
+can be declared as released under such a license by placing the macro
+@code{GDB_DECLARE_GPL_COMPATIBLE_READER} in a source file.
+
+The entry point for readers is the symbol @code{gdb_init_reader},
+which is expected to be a function with the prototype
+
+@findex gdb_init_reader
+@smallexample
+extern struct gdb_reader_funcs *gdb_init_reader (void);
+@end smallexample
+
+@cindex @code{struct gdb_reader_funcs}
+
+@code{struct gdb_reader_funcs} contains a set of pointers to callback
+functions. These functions are executed to read the debug info
+generated by the JIT compiler (@code{read}), to unwind stack frames
+(@code{unwind}) and to create canonical frame IDs
+(@code{get_Frame_id}). It also has a callback that is called when the
+reader is being unloaded (@code{destroy}). The struct looks like this
+
+@smallexample
+struct gdb_reader_funcs
+@{
+ /* Must be set to GDB_READER_INTERFACE_VERSION. */
+ int reader_version;
+
+ /* For use by the reader. */
+ void *priv_data;
+
+ gdb_read_debug_info *read;
+ gdb_unwind_frame *unwind;
+ gdb_get_frame_id *get_frame_id;
+ gdb_destroy_reader *destroy;
+@};
+@end smallexample
+
+@cindex @code{struct gdb_symbol_callbacks}
+@cindex @code{struct gdb_unwind_callbacks}
+
+The callbacks are provided with another set of callbacks by
+@value{GDBN} to do their job. For @code{read}, these callbacks are
+passed in a @code{struct gdb_symbol_callbacks} and for @code{unwind}
+and @code{get_frame_id}, in a @code{struct gdb_unwind_callbacks}.
+@code{struct gdb_symbol_callbacks} has callbacks to create new object
+files and new symbol tables inside those object files. @code{struct
+gdb_unwind_callbacks} has callbacks to read registers off the current
+frame and to write out the values of the registers in the previous
+frame. Both have a callback (@code{target_read}) to read bytes off the
+target's address space.
+
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
@cindex bugs in @value{GDBN}
@kindex maint time
@cindex time of command execution
@item maint time
-Control whether to display the execution time for each command. If
-set to a nonzero value, @value{GDBN} will display how much time it
+Control whether to display the execution time of @value{GDBN} for each command.
+If set to a nonzero value, @value{GDBN} will display how much time it
took to execute each command, following the command's own output.
-The time is not printed for the commands that run the target, since
-there's no mechanism currently to compute how much time was spend
-by @value{GDBN} and how much time was spend by the program been debugged.
-it's not possibly currently
+Both CPU time and wallclock time are printed.
+Printing both is useful when trying to determine whether the cost is
+CPU or, e.g., disk/network, latency.
+Note that the CPU time printed is for @value{GDBN} only, it does not include
+the execution time of the inferior because there's no mechanism currently
+to compute how much time was spent by @value{GDBN} and how much time was
+spent by the program been debugged.
This can also be requested by invoking @value{GDBN} with the
@option{--statistics} command-line switch (@pxref{Mode Options}).
The specified memory region's checksum is @var{crc32}.
@end table
+@item QDisableRandomization:@var{value}
+@cindex disable address space randomization, remote request
+@cindex @samp{QDisableRandomization} packet
+Some target operating systems will randomize the virtual address space
+of the inferior process as a security feature, but provide a feature
+to disable such randomization, e.g.@: to allow for a more deterministic
+debugging experience. On such systems, this packet with a @var{value}
+of 1 directs the target to disable address space randomization for
+processes subsequently started via @samp{vRun} packets, while a packet
+with a @var{value} of 0 tells the target to enable address space
+randomization.
+
+This packet is only available in extended mode (@pxref{extended mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+
+@item
+An empty reply indicates that @samp{QDisableRandomization} is not supported
+by the stub.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+This should only be done on targets that actually support disabling
+address space randomization.
+
@item qfThreadInfo
@itemx qsThreadInfo
@cindex list active threads, remote request
@tab @samp{-}
@tab No
+@item @samp{QDisableRandomization}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{EnableDisableTracepoints}
@tab No
@tab @samp{-}
@tab No
+@item @samp{tracenz}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
@item QAllow
The remote stub understands the @samp{QAllow} packet.
+@item QDisableRandomization
+The remote stub understands the @samp{QDisableRandomization} packet.
+
@item StaticTracepoint
@cindex static tracepoints, in remote protocol
The remote stub supports static tracepoints.
+@item InstallInTrace
+@anchor{install tracepoint in tracing}
+The remote stub supports installing tracepoint in tracing.
+
@item EnableDisableTracepoints
The remote stub supports the @samp{QTEnable} (@pxref{QTEnable}) and
@samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints
to be enabled and disabled while a trace experiment is running.
+@item tracenz
+@cindex string tracing, in remote protocol
+The remote stub supports the @samp{tracenz} bytecode for collecting strings.
+See @ref{Bytecode Descriptions} for details about the bytecode.
+
@end table
@item qSymbol::
@itemx qTfP
@itemx qTfV
@itemx QTFrame
+@itemx qTMinFTPILen
+
@xref{Tracepoint Packets}.
@item qThreadExtraInfo,@var{thread-id}
conventions above. Please don't use this packet as a model for new
packets.)
+@item QTNotes
+@item qTP
@item QTSave
@item qTsP
@item qTsV
Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
frame @emph{outside} the given range of addresses (exclusive).
+@item qTMinFTPILen
+This packet requests the minimum length of instruction at which a fast
+tracepoint (@pxref{Set Tracepoints}) may be placed. For instance, on
+the 32-bit x86 architecture, it is possible to use a 4-byte jump, but
+it depends on the target system being able to create trampolines in
+the first 64K of memory, which might or might not be possible for that
+system. So the reply to this packet will be 4 if it is able to
+arrange for that.
+
+Replies:
+
+@table @samp
+@item 0
+The minimum instruction length is currently unknown.
+@item @var{length}
+The minimum instruction length is @var{length}, where @var{length} is greater
+or equal to 1. @var{length} is a hexadecimal number. A reply of 1 means
+that a fast tracepoint may be placed on any instruction regardless of size.
+@item E
+An error has occurred.
+@item
+An empty reply indicates that the request is not supported by the stub.
+@end table
+
@item QTStart
Begin the tracepoint experiment. Begin collecting data from
tracepoint hits in the trace frame buffer. This packet supports the
@item tnotrun:0
No trace has been run yet.
-@item tstop:0
-The trace was stopped by a user-originated stop command.
+@item tstop[:@var{text}]:0
+The trace was stopped by a user-originated stop command. The optional
+@var{text} field is a user-supplied string supplied as part of the
+stop command (for instance, an explanation of why the trace was
+stopped manually). It is hex-encoded.
@item tfull:0
The trace stopped because the trace buffer filled up.
@end table
+@item qTP:@var{tp}:@var{addr}
+@cindex tracepoint status, remote request
+@cindex @samp{qTP} packet
+Ask the stub for the current state of tracepoint number @var{tp} at
+address @var{addr}.
+
+Replies:
+@table @samp
+@item V@var{hits}:@var{usage}
+The tracepoint has been hit @var{hits} times so far during the trace
+run, and accounts for @var{usage} in the trace buffer. Note that
+@code{while-stepping} steps are not counted as separate hits, but the
+steps' space consumption is added into the usage number.
+
+@end table
+
@item qTV:@var{var}
@cindex trace state variable value, remote request
@cindex @samp{qTV} packet
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.
+@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{}
+This packet adds optional textual notes to the trace run. Allowable
+types include @code{user}, @code{notes}, and @code{tstop}, the
+@var{text} fields are arbitrary strings, hex-encoded.
+
@end table
@subsection Relocate instruction reply packet