From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eli Zaretskii To: gdb-patches@sources.redhat.com Subject: [PATCH] Add tracepoints documentation to the manual Date: Sun, 01 Apr 2001 01:20:00 -0000 Message-id: X-SW-Source: 2001-04/msg00002.html I've just committed the patches below which document the tracepoint facilities. While at that, I also updated the Contributors section and added the description of the jewel called "info scope". Thanks to Elena for producing tracepoints docs I used as a basis for writing this up, and to Michael Snyder for clearing up related aspects. 2001-04-01 Eli Zaretskii * gdb.texinfo (Symbols): Document "info scope". (Tracepoints): New chapter. (Contributors): Update for v5.1. : Change "C++" to "C@t{++}". --- gdb/doc/gdb.t~5 Sun Mar 25 22:23:14 2001 +++ gdb/doc/gdb.texinfo Sat Mar 31 23:37:26 2001 @@ -125,6 +125,7 @@ * Stack:: Examining the stack * Source:: Examining source files * Data:: Examining data +* Tracepoints:: Debugging remote targets non-intrusively * Languages:: Using @value{GDBN} with different languages @@ -159,7 +160,7 @@ This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. -This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version +This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version @value{GDBVN}. Copyright (C) 1988-2000 Free Software Foundation, Inc. @@ -292,7 +293,7 @@ So that they may not regard their many labors as thankless, we particularly thank those who shepherded @value{GDBN} through major releases: -Andrew Cagney (release 5.0); +Andrew Cagney (releases 5.0 and 5.1); Jim Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs (release 4.14); @@ -305,13 +306,13 @@ Richard Stallman, assisted at various times by Peter TerMaat, Chris Hanson, and Richard Mlynarik, handled releases through 2.8. -Michael Tiemann is the author of most of the @sc{gnu} C++ support in -@value{GDBN}, with significant additional contributions from Per -Bothner. James Clark wrote the @sc{gnu} C++ demangler. Early work on -C++ was by Peter TerMaat (who also did much general update work leading -to release 3.0). +Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support +in @value{GDBN}, with significant additional contributions from Per +Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} +demangler. Early work on C@t{++} was by Peter TerMaat (who also did +much general update work leading to release 3.0). -@value{GDBN} 4 uses the BFD subroutine library to examine multiple +@value{GDBN} uses the BFD subroutine library to examine multiple object-file formats; BFD was a joint project of David V. Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. @@ -359,7 +360,7 @@ Modula-2 support, and contributed the Languages chapter of this manual. Fred Fish wrote most of the support for Unix System Vr4. -He also enhanced the command-completion support to cover C++ overloaded +He also enhanced the command-completion support to cover C@t{++} overloaded symbols. Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and @@ -387,12 +388,15 @@ The following people at the Hewlett-Packard Company contributed support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 -(narrow mode), HP's implementation of kernel threads, HP's aC++ +(narrow mode), HP's implementation of kernel threads, HP's aC@t{++} compiler, and the terminal user interface: Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific information in this manual. +DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. +Robert Hoehne made significant contributions to the DJGPP port. + Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its development since 1991. Cygnus engineers who have worked on @value{GDBN} fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin @@ -992,7 +996,7 @@ MS-DOS/MS-Windows supports this mode of operation, but the event loop is suspended when the debuggee runs.}, so you don't need to wait for control to return to @value{GDBN} before you type the next command. -(@emph{Note:} as of version 5.0, the target side of the asynchronous +(@emph{Note:} as of version 5.1, the target side of the asynchronous operation is not yet in place, so @samp{-async} does not work fully yet.) @c FIXME: when the target side of the event loop is done, the above NOTE @@ -1243,7 +1247,7 @@ command. If you just want to see the list of alternatives in the first place, you -can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} +can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} means @kbd{@key{META} ?}. You can type this either by holding down a key designated as the @key{META} shift on your keyboard (if there is one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. @@ -1257,16 +1261,16 @@ @value{GDBN} commands. The most likely situation where you might need this is in typing the -name of a C++ function. This is because C++ allows function overloading -(multiple definitions of the same function, distinguished by argument -type). For example, when you want to set a breakpoint you may need to -distinguish whether you mean the version of @code{name} that takes an -@code{int} parameter, @code{name(int)}, or the version that takes a -@code{float} parameter, @code{name(float)}. To use the word-completion -facilities in this situation, type a single quote @code{'} at the -beginning of the function name. This alerts @value{GDBN} that it may need to -consider more information than usual when you press @key{TAB} or -@kbd{M-?} to request word completion: +name of a C@t{++} function. This is because C@t{++} allows function +overloading (multiple definitions of the same function, distinguished +by argument type). For example, when you want to set a breakpoint you +may need to distinguish whether you mean the version of @code{name} +that takes an @code{int} parameter, @code{name(int)}, or the version +that takes a @code{float} parameter, @code{name(float)}. To use the +word-completion facilities in this situation, type a single quote +@code{'} at the beginning of the function name. This alerts +@value{GDBN} that it may need to consider more information than usual +when you press @key{TAB} or @kbd{M-?} to request word completion: @example (@value{GDBP}) b 'bubble( @kbd{M-?} @@ -1291,9 +1295,9 @@ completion on an overloaded symbol. For more information about overloaded functions, see @ref{C plus plus -expressions, ,C++ expressions}. You can use the command @code{set +expressions, ,C@t{++} expressions}. You can use the command @code{set overload-resolution off} to disable overload resolution; -see @ref{Debugging C plus plus, ,@value{GDBN} features for C++}. +see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}. @node Help @@ -1376,7 +1380,8 @@ apropos reload @end smallexample -@noindent results in: +@noindent +results in: @smallexample @c @group @@ -2266,7 +2271,7 @@ @cindex catchpoints @cindex breakpoint on events A @dfn{catchpoint} is another special breakpoint that stops your program -when a certain kind of event occurs, such as the throwing of a C++ +when a certain kind of event occurs, such as the throwing of a C@t{++} exception or the loading of a library. As with watchpoints, you use a different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting catchpoints}), but aside from that, you can manage a catchpoint like any @@ -2327,7 +2332,7 @@ @item break @var{function} Set a breakpoint at entry to function @var{function}. When using source languages that permit overloading of symbols, such as -C++, @var{function} may refer to more than one possible place to break. +C@t{++}, @var{function} may refer to more than one possible place to break. @xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation. @item break +@var{offset} @@ -2434,7 +2439,7 @@ @code{.*} leading and trailing the regular expression you supply, so to match only functions that begin with @code{foo}, use @code{^foo}. -When debugging C++ programs, @code{rbreak} is useful for setting +When debugging C@t{++} programs, @code{rbreak} is useful for setting breakpoints on overloaded functions that are not members of any special classes. @@ -2685,7 +2690,7 @@ @cindex event handling You can use @dfn{catchpoints} to cause the debugger to stop for certain -kinds of program events, such as C++ exceptions or the loading of a +kinds of program events, such as C@t{++} exceptions or the loading of a shared library. Use the @code{catch} command to set a catchpoint. @table @code @@ -2695,11 +2700,11 @@ @table @code @item throw @kindex catch throw -The throwing of a C++ exception. +The throwing of a C@t{++} exception. @item catch @kindex catch catch -The catching of a C++ exception. +The catching of a C@t{++} exception. @item exec @kindex catch exec @@ -2734,7 +2739,7 @@ Use the @code{info break} command to list the current catchpoints. -There are currently some limitations to C++ exception handling +There are currently some limitations to C@t{++} exception handling (@code{catch throw} and @code{catch catch}) in @value{GDBN}: @itemize @bullet @@ -2764,7 +2769,7 @@ out where the exception was raised. To stop just before an exception handler is called, you need some -knowledge of the implementation. In the case of @sc{gnu} C++, exceptions are +knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are raised by calling a library function named @code{__raise_exception} which has the following ANSI C interface: @@ -3107,7 +3112,7 @@ @cindex overloading @cindex symbol overloading -Some programming languages (notably C++) permit a single function name +Some programming languages (notably C@t{++}) permit a single function name to be defined several times, for application in different contexts. This is called @dfn{overloading}. When a function name is overloaded, @samp{break @var{function}} is not enough to tell @value{GDBN} where you want @@ -4467,9 +4472,9 @@ (@value{GDBP}) p 'f2.c'::x @end example -@cindex C++ scope resolution +@cindex C@t{++} scope resolution This use of @samp{::} is very rarely in conflict with the very similar -use of the same notation in C++. @value{GDBN} also supports use of the C++ +use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++} scope resolution operator in @value{GDBN} expressions. @c FIXME: Um, so what happens in one of those rare cases where it's in @c conflict?? --mew @@ -4508,7 +4513,7 @@ 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++ compiler usually +formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler usually supports the @samp{-gstabs} option. @samp{-gstabs} produces debug info in a format that is superior to formats such as COFF. You may be able to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for @@ -5121,56 +5126,56 @@ @need 1000 @noindent -These settings are of interest when debugging C++ programs: +These settings are of interest when debugging C@t{++} programs: @table @code @cindex demangling @kindex set print demangle @item set print demangle @itemx set print demangle on -Print C++ names in their source form rather than in the encoded +Print C@t{++} names in their source form rather than in the encoded (``mangled'') form passed to the assembler and linker for type-safe linkage. The default is on. @kindex show print demangle @item show print demangle -Show whether C++ names are printed in mangled or demangled form. +Show whether C@t{++} names are printed in mangled or demangled form. @kindex set print asm-demangle @item set print asm-demangle @itemx set print asm-demangle on -Print C++ names in their source form rather than their mangled form, even +Print C@t{++} names in their source form rather than their mangled form, even in assembler code printouts such as instruction disassemblies. The default is off. @kindex show print asm-demangle @item show print asm-demangle -Show whether C++ names in assembly listings are printed in mangled +Show whether C@t{++} names in assembly listings are printed in mangled or demangled form. @kindex set demangle-style -@cindex C++ symbol decoding style -@cindex symbol decoding style, C++ +@cindex C@t{++} symbol decoding style +@cindex symbol decoding style, C@t{++} @item set demangle-style @var{style} Choose among several encoding schemes used by different compilers to -represent C++ names. The choices for @var{style} are currently: +represent C@t{++} names. The choices for @var{style} are currently: @table @code @item auto Allow @value{GDBN} to choose a decoding style by inspecting your program. @item gnu -Decode based on the @sc{gnu} C++ compiler (@code{g++}) encoding algorithm. +Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm. This is the default. @item hp -Decode based on the HP ANSI C++ (@code{aCC}) encoding algorithm. +Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm. @item lucid -Decode based on the Lucid C++ compiler (@code{lcc}) encoding algorithm. +Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm. @item arm -Decode using the algorithm in the @cite{C++ Annotated Reference Manual}. +Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}. @strong{Warning:} this setting alone is not sufficient to allow debugging @code{cfront}-generated executables. @value{GDBN} would require further enhancement to permit that. @@ -5180,7 +5185,7 @@ @kindex show demangle-style @item show demangle-style -Display the encoding style currently in use for decoding C++ symbols. +Display the encoding style currently in use for decoding C@t{++} symbols. @kindex set print object @item set print object @@ -5200,29 +5205,29 @@ @kindex set print static-members @item set print static-members @itemx set print static-members on -Print static members when displaying a C++ object. The default is on. +Print static members when displaying a C@t{++} object. The default is on. @item set print static-members off -Do not print static members when displaying a C++ object. +Do not print static members when displaying a C@t{++} object. @kindex show print static-members @item show print static-members -Show whether C++ static members are printed, or not. +Show whether C@t{++} static members are printed, or not. @c These don't work with HP ANSI C++ yet. @kindex set print vtbl @item set print vtbl @itemx set print vtbl on -Pretty print C++ virtual function tables. The default is off. +Pretty print C@t{++} virtual function tables. The default is off. (The @code{vtbl} commands do not work on programs compiled with the HP -ANSI C++ compiler (@code{aCC}).) +ANSI C@t{++} compiler (@code{aCC}).) @item set print vtbl off -Do not pretty print C++ virtual function tables. +Do not pretty print C@t{++} virtual function tables. @kindex show print vtbl @item show print vtbl -Show whether C++ virtual function tables are pretty printed, or not. +Show whether C@t{++} virtual function tables are pretty printed, or not. @end table @node Value History @@ -5634,6 +5639,623 @@ @c @item noverify (default) @c @end table +@node Tracepoints +@chapter Tracepoints +@c This chapter is based on the documentation written by Michael +@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni. + +@cindex tracepoints +In some applications, it is not feasible for the debugger to interrupt +the program's execution long enough for the developer to learn +anything helpful about its behavior. If the program's correctness +depends on its real-time behavior, delays introduced by a debugger +might cause the program to change its behavior drastically, or perhaps +fail, even when the code itself is correct. It is useful to be able +to observe the program's behavior without interrupting it. + +Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can +specify locations in the program, called @dfn{tracepoints}, and +arbitrary expressions to evaluate when those tracepoints are reached. +Later, using the @code{tfind} command, you can examine the values +those expressions had when the program hit the tracepoints. The +expressions may also denote objects in memory---structures or arrays, +for example---whose values @value{GDBN} should record; while visiting +a particular tracepoint, you may inspect those objects as if they were +in memory at that moment. However, because @value{GDBN} records these +values without interacting with you, it can do so quickly and +unobtrusively, hopefully not disturbing the program's behavior. + +The tracepoint facility is currently available only for remote +targets. @xref{Targets}. + +This chapter describes the tracepoint commands and features. + +@menu +* Set Tracepoints:: +* Analyze Collected Data:: +* Tracepoint Variables:: +@end menu + +@node Set Tracepoints +@section Commands to Set Tracepoints + +Before running such a @dfn{trace experiment}, an arbitrary number of +tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a +tracepoint has a number assigned to it by @value{GDBN}. Like with +breakpoints, tracepoint numbers are successive integers starting from +one. Many of the commands associated with tracepoints take the +tracepoint number as their argument, to identify which tracepoint to +work on. + +For each tracepoint, you can specify, in advance, some arbitrary set +of data that you want the target to collect in the trace buffer when +it hits that tracepoint. The collected data can include registers, +local variables, or global data. Later, you can use @value{GDBN} +commands to examine the values these data had at the time the +tracepoint was hit. + +This section describes commands to set tracepoints and associated +conditions and actions. + +@menu +* Create and Delete Tracepoints:: +* Enable and Disable Tracepoints:: +* Tracepoint Passcounts:: +* Tracepoint Actions:: +* Listing Tracepoints:: +* Starting and Stopping Trace Experiment:: +@end menu + +@node Create and Delete Tracepoints +@subsection Create and Delete Tracepoints + +@table @code +@cindex set tracepoint +@kindex trace +@item trace +The @code{trace} command is very similar to the @code{break} command. +Its argument can be a source line, a function name, or an address in +the target program. @xref{Set Breaks}. The @code{trace} command +defines a tracepoint, which is a point in the target program where the +debugger will briefly stop, collect some data, and then allow the +program to continue. Setting a tracepoint or changing its commands +doesn't take effect until the next @code{tstart} command; thus, you +cannot change the tracepoint attributes once a trace experiment is +running. + +Here are some examples of using the @code{trace} command: + +@smallexample +(@value{GDBP}) @b{trace foo.c:121} // a source file and line number + +(@value{GDBP}) @b{trace +2} // 2 lines forward + +(@value{GDBP}) @b{trace my_function} // first source line of function + +(@value{GDBP}) @b{trace *my_function} // EXACT start address of function + +(@value{GDBP}) @b{trace *0x2117c4} // an address +@end smallexample + +@noindent +You can abbreviate @code{trace} as @code{tr}. + +@vindex $tpnum +@cindex last tracepoint number +@cindex recent tracepoint number +@cindex tracepoint number +The convenience variable @code{$tpnum} records the tracepoint number +of the most recently set tracepoint. + +@kindex delete tracepoint +@cindex tracepoint deletion +@item delete tracepoint @r{[}@var{num}@r{]} +Permanently delete one or more tracepoints. With no argument, the +default is to delete all tracepoints. + +Examples: + +@smallexample +(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints + +(@value{GDBP}) @b{delete trace} // remove all tracepoints +@end smallexample + +@noindent +You can abbreviate this command as @code{del tr}. +@end table + +@node Enable and Disable Tracepoints +@subsection Enable and Disable Tracepoints + +@table @code +@kindex disable tracepoint +@item disable tracepoint @r{[}@var{num}@r{]} +Disable tracepoint @var{num}, or all tracepoints if no argument +@var{num} is given. A disabled tracepoint will have no effect during +the next trace experiment, but it is not forgotten. You can re-enable +a disabled tracepoint using the @code{enable tracepoint} command. + +@kindex enable tracepoint +@item enable tracepoint @r{[}@var{num}@r{]} +Enable tracepoint @var{num}, or all tracepoints. The enabled +tracepoints will become effective the next time a trace experiment is +run. +@end table + +@node Tracepoint Passcounts +@subsection Tracepoint Passcounts + +@table @code +@kindex passcount +@cindex tracepoint pass count +@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]} +Set the @dfn{passcount} of a tracepoint. The passcount is a way to +automatically stop a trace experiment. If a tracepoint's passcount is +@var{n}, then the trace experiment will be automatically stopped on +the @var{n}'th time that tracepoint is hit. If the tracepoint number +@var{num} is not specified, the @code{passcount} command sets the +passcount of the most recently defined tracepoint. If no passcount is +given, the trace experiment will run until stopped explicitly by the +user. + +Examples: + +@smallexample +(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of tracepoint 2 + +(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the + // most recently defined tracepoint. +(@value{GDBP}) @b{trace foo} +(@value{GDBP}) @b{pass 3} +(@value{GDBP}) @b{trace bar} +(@value{GDBP}) @b{pass 2} +(@value{GDBP}) @b{trace baz} +(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been + // executed 3 times OR when bar has + // been executed 2 times + // OR when baz has been executed 1 time. +@end smallexample +@end table + +@node Tracepoint Actions +@subsection Tracepoint Action Lists + +@table @code +@kindex actions +@cindex tracepoint actions +@item actions @r{[}@var{num}@r{]} +This command will prompt for a list of actions to be taken when the +tracepoint is hit. If the tracepoint number @var{num} is not +specified, this command sets the actions for the one that was most +recently defined (so that you can define a tracepoint and then say +@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 +@code{while-stepping}. + +@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}. + +@smallexample +(@value{GDBP}) @b{collect @var{data}} // collect some data + +(@value{GDBP}) @b{while-stepping 5} // single-step 5 times and collect data + +(@value{GDBP}) @b{end} // signals the end of actions. +@end smallexample + +In the following example, the action list begins with @code{collect} +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. + +@smallexample +(@value{GDBP}) @b{trace foo} +(@value{GDBP}) @b{actions} +Enter actions for tracepoint 1, one per line: +> collect bar,baz +> collect $regs +> while-stepping 12 + > collect $fp, $sp + > end +end +@end smallexample + +@kindex collect @r{(tracepoints)} +@item collect @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 +special arguments are supported: + +@table @code +@item $regs +collect all registers + +@item $args +collect all function arguments + +@item $locals +collect all local variables. +@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. + +@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): + +@smallexample +> while-stepping 12 + > collect $regs, myglobal + > end +> +@end smallexample + +@noindent +You may abbreviate @code{while-stepping} as @code{ws} or +@code{stepping}. +@end table + +@node Listing Tracepoints +@subsection Listing Tracepoints + +@table @code +@kindex info tracepoints +@cindex information about tracepoints +@item info tracepoints @r{[}@var{num}@r{]} +Display information the tracepoint @var{num}. If you don't specify a +tracepoint number displays information about all the tracepoints +defined so far. For each tracepoint, the following information is +shown: + +@itemize @bullet +@item +its number +@item +whether it is enabled or disabled +@item +its address +@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 +where in the source files is the tracepoint set +@item +its action list as given by the @code{actions} command +@end itemize + +@smallexample +(@value{GDBP}) @b{info trace} +Num Enb Address PassC StepC What +1 y 0x002117c4 0 0 +2 y 0x0020dc64 0 0 in gdb_test at gdb_test.c:375 +3 y 0x0020b1f4 0 0 in collect_data at ../foo.c:1741 +(@value{GDBP}) +@end smallexample + +@noindent +This command can be abbreviated @code{info tp}. +@end table + +@node Starting and Stopping Trace Experiment +@subsection Starting and Stopping Trace Experiment + +@table @code +@kindex tstart +@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 +@cindex stop a running trace experiment +@item tstop +This command takes no arguments. It ends the trace experiment, and +stops collecting data. + +@strong{Note:} a trace experiment and data collection may stop +automatically if any tracepoint's passcount is reached +(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full. + +@kindex tstatus +@cindex status of trace data collection +@cindex trace experiment, status of +@item tstatus +This command displays the status of the current trace data +collection. +@end table + +Here is an example of the commands we described so far: + +@smallexample +(@value{GDBP}) @b{trace gdb_c_test} +(@value{GDBP}) @b{actions} +Enter actions for tracepoint #1, one per line. +> collect $regs,$locals,$args +> while-stepping 11 + > collect $regs + > end +> end +(@value{GDBP}) @b{tstart} + [time passes @dots{}] +(@value{GDBP}) @b{tstop} +@end smallexample + + +@node Analyze Collected Data +@section Using the collected data + +After the tracepoint experiment ends, you use @value{GDBN} commands +for examining the trace data. The basic idea is that each tracepoint +collects a trace @dfn{snapshot} every time it is hit and another +snapshot every time it single-steps. All these snapshots are +consecutively numbered from zero and go into a buffer, and you can +examine them later. The way you examine them is to @dfn{focus} on a +specific trace snapshot. When the remote stub is focused on a trace +snapshot, it will respond to all @value{GDBN} requests for memory and +registers by reading from the buffer which belongs to that snapshot, +rather than from @emph{real} memory or registers of the program being +debugged. This means that @strong{all} @value{GDBN} commands +(@code{print}, @code{info registers}, @code{backtrace}, etc.) will +behave as if we were currently debugging the program state as it was +when the tracepoint occurred. Any requests for data that are not in +the buffer will fail. + +@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 +@end menu + +@node tfind +@subsection @code{tfind @var{n}} + +@kindex tfind +@cindex select trace snapshot +@cindex find trace snapshot +The basic command for selecting a trace snapshot from the buffer is +@code{tfind @var{n}}, which finds trace snapshot number @var{n}, +counting from zero. If no argument @var{n} is given, the next +snapshot is selected. + +Here are the various forms of using the @code{tfind} command. + +@table @code +@item tfind start +Find the first snapshot in the buffer. This is a synonym for +@code{tfind 0} (since 0 is the number of the first snapshot). + +@item tfind none +Stop debugging trace snapshots, resume @emph{live} debugging. + +@item tfind end +Same as @samp{tfind none}. + +@item tfind +No argument means find the next trace snapshot. + +@item tfind - +Find the previous trace snapshot before the current one. This permits +retracing earlier steps. + +@item tfind tracepoint @var{num} +Find the next snapshot associated with tracepoint @var{num}. Search +proceeds forward from the last examined trace snapshot. If no +argument @var{num} is given, it means find the next snapshot collected +for the same tracepoint as the current snapshot. + +@item tfind pc @var{addr} +Find the next snapshot associated with the value @var{addr} of the +program counter. Search proceeds forward from the last examined trace +snapshot. If no argument @var{addr} is given, it means find the next +snapshot with the same value of PC as the current snapshot. + +@item tfind outside @var{addr1}, @var{addr2} +Find the next snapshot whose PC is outside the given range of +addresses. + +@item tfind range @var{addr1}, @var{addr2} +Find the next snapshot whose PC is between @var{addr1} and +@var{addr2}. @c FIXME: Is the range inclusive or exclusive? + +@item tfind line @r{[}@var{file}:@r{]}@var{n} +Find the next snapshot associated with the source line @var{n}. If +the optional argument @var{file} is given, refer to line @var{n} in +that source file. Search proceeds forward from the last examined +trace snapshot. If no argument @var{n} is given, it means find the +next line other than the one currently being examined; thus saying +@code{tfind line} repeatedly can appear to have the same effect as +stepping from line to line in a @emph{live} debugging session. +@end table + +The default arguments for the @code{tfind} commands are specifically +designed to make it easy to scan through the trace buffer. For +instance, @code{tfind} with no argument selects the next trace +snapshot, and @code{tfind -} with no argument selects the previous +trace snapshot. So, by giving one @code{tfind} command, and then +simply hitting @key{RET} repeatedly you can examine all the trace +snapshots in order. Or, by saying @code{tfind -} and then hitting +@key{RET} repeatedly you can examine the snapshots in reverse order. +The @code{tfind line} command with no argument selects the snapshot +for the next source line executed. The @code{tfind pc} command with +no argument selects the next snapshot with the same program counter +(PC) as the current frame. The @code{tfind tracepoint} command with +no argument selects the next trace snapshot collected by the same +tracepoint as the current one. + +In addition to letting you scan through the trace buffer manually, +these commands make it easy to construct @value{GDBN} scripts that +scan through the trace buffer and print out whatever collected data +you are interested in. Thus, if we want to examine the PC, FP, and SP +registers from each trace frame in the buffer, we can say this: + +@smallexample +(@value{GDBP}) @b{tfind start} +(@value{GDBP}) @b{while ($trace_frame != -1)} +> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ + $trace_frame, $pc, $sp, $fp +> tfind +> end + +Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 +Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 +Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 +Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 +Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 +Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 +Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 +Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 +Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 +Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 +Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 +@end smallexample + +Or, if we want to examine the variable @code{X} at each source line in +the buffer: + +@smallexample +(@value{GDBP}) @b{tfind start} +(@value{GDBP}) @b{while ($trace_frame != -1)} +> printf "Frame %d, X == %d\n", $trace_frame, X +> tfind line +> end + +Frame 0, X = 1 +Frame 7, X = 2 +Frame 13, X = 255 +@end smallexample + +@node tdump +@subsection @code{tdump} +@kindex tdump +@cindex dump all data collected at tracepoint +@cindex tracepoint data, display + +This command takes no arguments. It prints all the data collected at +the current trace snapshot. + +@smallexample +(@value{GDBP}) @b{trace 444} +(@value{GDBP}) @b{actions} +Enter actions for tracepoint #2, one per line: +> collect $regs, $locals, $args, gdb_long_test +> end + +(@value{GDBP}) @b{tstart} + +(@value{GDBP}) @b{tfind line 444} +#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) +at gdb_test.c:444 +444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) + +(@value{GDBP}) @b{tdump} +Data collected at tracepoint 2, trace frame 1: +d0 0xc4aa0085 -995491707 +d1 0x18 24 +d2 0x80 128 +d3 0x33 51 +d4 0x71aea3d 119204413 +d5 0x22 34 +d6 0xe0 224 +d7 0x380035 3670069 +a0 0x19e24a 1696330 +a1 0x3000668 50333288 +a2 0x100 256 +a3 0x322000 3284992 +a4 0x3000698 50333336 +a5 0x1ad3cc 1758156 +fp 0x30bf3c 0x30bf3c +sp 0x30bf34 0x30bf34 +ps 0x0 0 +pc 0x20b2c8 0x20b2c8 +fpcontrol 0x0 0 +fpstatus 0x0 0 +fpiaddr 0x0 0 +p = 0x20e5b4 "gdb-test" +p1 = (void *) 0x11 +p2 = (void *) 0x22 +p3 = (void *) 0x33 +p4 = (void *) 0x44 +p5 = (void *) 0x55 +p6 = (void *) 0x66 +gdb_long_test = 17 '\021' + +(@value{GDBP}) +@end smallexample + +@node save-tracepoints +@subsection @code{save-tracepoints @var{filename}} +@kindex save-tracepoints +@cindex save tracepoints for future sessions + +This command saves all current tracepoint definitions together with +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}). + +@node Tracepoint Variables +@section Convenience Variables for Tracepoints +@cindex tracepoint variables +@cindex convenience variables for tracepoints + +@table @code +@vindex $trace_frame +@item (int) $trace_frame +The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no +snapshot is selected. + +@vindex $tracepoint +@item (int) $tracepoint +The tracepoint for the current trace snapshot. + +@vindex $trace_line +@item (int) $trace_line +The line number for the current trace snapshot. + +@vindex $trace_file +@item (char []) $trace_file +The source file for the current trace snapshot. + +@vindex $trace_func +@item (char []) $trace_func +The name of the function containing @code{$tracepoint}. +@end table + +Note: @code{$trace_file} is not suitable for use in @code{printf}, +use @code{output} instead. + +Here's a simple example of using these convenience variables for +stepping through all the trace snapshots and printing some of their +data. + +@smallexample +(@value{GDBP}) @b{tfind start} + +(@value{GDBP}) @b{while $trace_frame != -1} +> output $trace_file +> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint +> tfind +> end +@end smallexample + @node Languages @chapter Using @value{GDBN} with Different Languages @cindex languages @@ -5675,7 +6297,7 @@ file formats, the compiler might indicate which language a particular source file is in. However, most of the time @value{GDBN} infers the language from the name of the file. The language of a source file -controls whether C++ names are demangled---this way @code{backtrace} can +controls whether C@t{++} names are demangled---this way @code{backtrace} can show each frame appropriately for its own language. There is no way to set the language of a source file from within @value{GDBN}, but you can set the language associated with a filename extension. @xref{Show, , @@ -5711,7 +6333,7 @@ @itemx .cpp @itemx .cxx @itemx .c++ -C++ source file +C@t{++} source file @item .f @itemx .F @@ -5993,7 +6615,7 @@ @node Support @section Supported languages -@value{GDBN} supports C, C++, Fortran, Java, Chill, assembly, and Modula-2. +@value{GDBN} supports C, C@t{++}, Fortran, Java, Chill, assembly, and Modula-2. @c This is false ... Some @value{GDBN} features may be used in expressions regardless of the language you use: the @value{GDBN} @code{@@} and @code{::} operators, @@ -6010,62 +6632,62 @@ language reference or tutorial. @menu -* C:: C and C++ +* C:: C and C@t{++} * Modula-2:: Modula-2 * Chill:: Chill @end menu @node C -@subsection C and C++ +@subsection C and C@t{++} -@cindex C and C++ -@cindex expressions in C or C++ +@cindex C and C@t{++} +@cindex expressions in C or C@t{++} -Since C and C++ are so closely related, many features of @value{GDBN} apply +Since C and C@t{++} are so closely related, many features of @value{GDBN} apply to both languages. Whenever this is the case, we discuss those languages together. @cindex C@t{++} @cindex @code{g++}, @sc{gnu} C@t{++} compiler -@cindex @sc{gnu} C++ -The C++ debugging facilities are jointly implemented by the C++ -compiler and @value{GDBN}. Therefore, to debug your C++ code -effectively, you must compile your C++ programs with a supported -C++ compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C++ +@cindex @sc{gnu} C@t{++} +The C@t{++} debugging facilities are jointly implemented by the C@t{++} +compiler and @value{GDBN}. Therefore, to debug your C@t{++} code +effectively, you must compile your C@t{++} programs with a supported +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++, use the stabs debugging +For best results when using @sc{gnu} C@t{++}, use the stabs debugging format. You can select that format explicitly with the @code{g++} command-line options @samp{-gstabs} or @samp{-gstabs+}. See @ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more information. @menu -* C Operators:: C and C++ operators -* C Constants:: C and C++ constants -* C plus plus expressions:: C++ expressions -* C Defaults:: Default settings for C and C++ -* C Checks:: C and C++ type and range checks +* C Operators:: C and C@t{++} operators +* C Constants:: C and C@t{++} constants +* C plus plus expressions:: C@t{++} expressions +* C Defaults:: Default settings for C and C@t{++} +* C Checks:: C and C@t{++} type and range checks * Debugging C:: @value{GDBN} and C -* Debugging C plus plus:: @value{GDBN} features for C++ +* Debugging C plus plus:: @value{GDBN} features for C@t{++} @end menu @node C Operators -@subsubsection C and C++ operators +@subsubsection C and C@t{++} operators -@cindex C and C++ operators +@cindex C and C@t{++} operators Operators must be defined on values of specific types. For instance, @code{+} is defined on numbers, but not on structures. Operators are often defined on groups of types. -For the purposes of C and C++, the following definitions hold: +For the purposes of C and C@t{++}, the following definitions hold: @itemize @bullet @item @emph{Integral types} include @code{int} with any of its storage-class -specifiers; @code{char}; @code{enum}; and, for C++, @code{bool}. +specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}. @item @emph{Floating-point types} include @code{float}, @code{double}, and @@ -6157,10 +6779,10 @@ @item & Address operator. Defined on variables. Same precedence as @code{++}. -For debugging C++, @value{GDBN} implements a use of @samp{&} beyond what is -allowed in the C++ language itself: you can use @samp{&(&@var{ref})} +For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is +allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})} (or, if you prefer, simply @samp{&&@var{ref}}) to examine the address -where a C++ reference variable (declared with @samp{&@var{ref}}) is +where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is stored. @item - @@ -6193,7 +6815,7 @@ Function parameter list. Same precedence as @code{->}. @item :: -C++ scope resolution operator. Defined on @code{struct}, @code{union}, +C@t{++} scope resolution operator. Defined on @code{struct}, @code{union}, and @code{class} types. @item :: @@ -6211,11 +6833,11 @@ @end menu @node C Constants -@subsubsection C and C++ constants +@subsubsection C and C@t{++} constants -@cindex C and C++ constants +@cindex C and C@t{++} constants -@value{GDBN} allows you to express the constants of C and C++ in the +@value{GDBN} allows you to express the constants of C and C@t{++} in the following ways: @itemize @bullet @@ -6279,32 +6901,32 @@ @end menu @node C plus plus expressions -@subsubsection C++ expressions +@subsubsection C@t{++} expressions -@cindex expressions in C++ -@value{GDBN} expression handling can interpret most C++ expressions. +@cindex expressions in C@t{++} +@value{GDBN} expression handling can interpret most C@t{++} expressions. -@cindex C++ support, not in @sc{coff} -@cindex @sc{coff} versus C++ -@cindex C++ and object formats -@cindex object formats and C++ -@cindex a.out and C++ -@cindex @sc{ecoff} and C++ -@cindex @sc{xcoff} and C++ -@cindex @sc{elf}/stabs and C++ -@cindex @sc{elf}/@sc{dwarf} and C++ +@cindex C@t{++} support, not in @sc{coff} +@cindex @sc{coff} versus C@t{++} +@cindex C@t{++} and object formats +@cindex object formats and C@t{++} +@cindex a.out and C@t{++} +@cindex @sc{ecoff} and C@t{++} +@cindex @sc{xcoff} and C@t{++} +@cindex @sc{elf}/stabs and C@t{++} +@cindex @sc{elf}/@sc{dwarf} and C@t{++} @c FIXME!! GDB may eventually be able to debug C++ using DWARF; check @c periodically whether this has happened... @quotation -@emph{Warning:} @value{GDBN} can only debug C++ code if you use the -proper compiler. Typically, C++ debugging depends on the use of +@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the +proper compiler. Typically, C@t{++} debugging depends on the use of additional debugging information in the symbol table, and thus requires special support. In particular, if your compiler generates a.out, MIPS @sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the symbol table, these facilities are all available. (With @sc{gnu} CC, you can use the @samp{-gstabs} option to request stabs debugging extensions explicitly.) Where the object code format is standard -@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C++ +@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++} support in @value{GDBN} does @emph{not} work. @end quotation @@ -6319,16 +6941,16 @@ @end example @vindex this@r{, inside C@t{++} member functions} -@cindex namespace in C++ +@cindex namespace in C@t{++} @item 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++. +pointer @code{this} following the same rules as C@t{++}. @cindex call overloaded functions @cindex overloaded functions, calling -@cindex type conversions in C++ +@cindex type conversions in C@t{++} @item You can call overloaded functions; @value{GDBN} resolves the function call to the right definition, with some restrictions. @value{GDBN} does not @@ -6345,7 +6967,7 @@ Overload resolution is always performed, unless you have specified @code{set overload-resolution off}. @xref{Debugging C plus plus, -,@value{GDBN} features for C++}. +,@value{GDBN} features for C@t{++}}. You must specify @code{set overload-resolution off} in order to use an explicit function signature to call an overloaded function, as in @@ -6358,8 +6980,8 @@ @cindex reference declarations @item -@value{GDBN} understands variables declared as C++ references; you can use -them in expressions just as you do in C++ source---they are automatically +@value{GDBN} understands variables declared as C@t{++} references; you can use +them in expressions just as you do in C@t{++} source---they are automatically dereferenced. In the parameter list shown when @value{GDBN} displays a frame, the values of @@ -6369,34 +6991,34 @@ you have specified @samp{set print address off}. @item -@value{GDBN} supports the C++ name resolution operator @code{::}---your +@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your expressions can use it just as expressions in your program do. Since one scope may be defined in another, you can use @code{::} repeatedly if necessary, for example in an expression like @samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows -resolving name scope by reference to source files, in both C and C++ +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++ compiler, @value{GDBN} supports +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. @node C Defaults -@subsubsection C and C++ defaults +@subsubsection C and C@t{++} defaults -@cindex C and C++ defaults +@cindex C and C@t{++} defaults If you allow @value{GDBN} to set type and range checking automatically, they both default to @code{off} whenever the working language changes to -C or C++. This happens regardless of whether you or @value{GDBN} +C or C@t{++}. This happens regardless of whether you or @value{GDBN} selects the working language. If you allow @value{GDBN} to set the language automatically, it recognizes source files whose names end with @file{.c}, @file{.C}, or @file{.cc}, etc, and when @value{GDBN} enters code compiled from one of -these files, it sets the working language to C or C++. +these files, it sets the working language to C or C@t{++}. @xref{Automatically, ,Having @value{GDBN} infer the source language}, for further details. @@ -6405,11 +7027,11 @@ @c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93. @node C Checks -@subsubsection C and C++ type and range checks +@subsubsection C and C@t{++} type and range checks -@cindex C and C++ checks +@cindex C and C@t{++} checks -By default, when @value{GDBN} parses C or C++ expressions, type checking +By default, when @value{GDBN} parses C or C@t{++} expressions, type checking is not used. However, if you turn type checking on, @value{GDBN} considers two variables type equivalent if: @@ -6453,12 +7075,12 @@ @end menu @node Debugging C plus plus -@subsubsection @value{GDBN} features for C++ +@subsubsection @value{GDBN} features for C@t{++} -@cindex commands for C++ +@cindex commands for C@t{++} -Some @value{GDBN} commands are particularly useful with C++, and some are -designed specifically for use with C++. Here is a summary: +Some @value{GDBN} commands are particularly useful with C@t{++}, and some are +designed specifically for use with C@t{++}. Here is a summary: @table @code @cindex break in overloaded functions @@ -6467,17 +7089,17 @@ @value{GDBN} breakpoint menus help you specify which function definition you want. @xref{Breakpoint Menus,,Breakpoint menus}. -@cindex overloading in C++ +@cindex overloading in C@t{++} @item rbreak @var{regex} Setting breakpoints using regular expressions is helpful for setting breakpoints on overloaded functions that are not members of any special classes. @xref{Set Breaks, ,Setting breakpoints}. -@cindex C++ exception handling +@cindex C@t{++} exception handling @item catch throw @itemx catch catch -Debug C++ exception handling using these commands. @xref{Set +Debug C@t{++} exception handling using these commands. @xref{Set Catchpoints, , Setting catchpoints}. @cindex inheritance @@ -6486,13 +7108,13 @@ @var{typename}. @xref{Symbols, ,Examining the Symbol Table}. -@cindex C++ symbol display +@cindex C@t{++} symbol display @item set print demangle @itemx show print demangle @itemx set print asm-demangle @itemx show print asm-demangle -Control whether C++ symbols display in their source form, both when -displaying code as C++ source and when displaying disassemblies. +Control whether C@t{++} symbols display in their source form, both when +displaying code as C@t{++} source and when displaying disassemblies. @xref{Print Settings, ,Print settings}. @item set print object @@ -6505,20 +7127,20 @@ Control the format for printing virtual function tables. @xref{Print Settings, ,Print settings}. (The @code{vtbl} commands do not work on programs compiled with the HP -ANSI C++ compiler (@code{aCC}).) +ANSI C@t{++} compiler (@code{aCC}).) @kindex set overload-resolution @cindex overloaded functions, overload resolution @item set overload-resolution on -Enable overload resolution for C++ expression evaluation. The default +Enable overload resolution for C@t{++} expression evaluation. The default is on. For overloaded functions, @value{GDBN} evaluates the arguments and searches for a function whose signature matches the argument types, -using the standard C++ conversion rules (see @ref{C plus plus expressions, ,C++ +using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++} expressions}, for details). If it cannot find a match, it emits a message. @item set overload-resolution off -Disable overload resolution for C++ expression evaluation. For +Disable overload resolution for C@t{++} expression evaluation. For overloaded functions that are not class member functions, @value{GDBN} chooses the first function of the specified name that it finds in the symbol table, whether or not its arguments are of the correct type. For @@ -6528,7 +7150,7 @@ @item @r{Overloaded symbol names} You can specify a particular definition of an overloaded symbol, using -the same notation that is used to declare such symbols in C++: type +the same notation that is used to declare such symbols in C@t{++}: type @code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can also use the @value{GDBN} command-line word completion facilities to list the available choices, or to finish the type list for you. @@ -6827,7 +7449,7 @@ String constants consist of a sequence of characters enclosed by a pair of like quotes, either single (@code{'}) or double (@code{"}). Escape sequences in the style of C are also allowed. @xref{C -Constants, ,C and C++ constants}, for a brief explanation of escape +Constants, ,C and C@t{++} constants}, for a brief explanation of escape sequences. @item @@ -6961,15 +7583,15 @@ Some @value{GDBN} commands have little use when debugging Modula-2 programs. Five subcommands of @code{set print} and @code{show print} apply -specifically to C and C++: @samp{vtbl}, @samp{demangle}, +specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle}, @samp{asm-demangle}, @samp{object}, and @samp{union}. The first four -apply to C++, and the last to the C @code{union} type, which has no direct +apply to C@t{++}, and the last to the C @code{union} type, which has no direct analogue in Modula-2. The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available with any language, is not useful with Modula-2. Its intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be -created in Modula-2 as they can in C or C++. However, because an +created in Modula-2 as they can in C or C@t{++}. However, because an address can be specified by an integral constant, the construct @samp{@{@var{type}@}@var{adrexp}} is still useful. @@ -7263,7 +7885,7 @@ @item @emph{Set Literals} are defined by a name which was specified in a set mode. The value delivered by a Set Literal is the set value. This is -comparable to an enumeration in C/C++ language. +comparable to an enumeration in C/C@t{++} language. @item @emph{Emptiness Literal} is predefined by @code{NULL}. The value of the emptiness literal delivers either the empty reference value, the empty @@ -7508,6 +8130,7 @@ @table @code @kindex info address +@cindex address of a symbol @item info address @var{symbol} Describe where the data for @var{symbol} is stored. For a register variable, this says which register it is kept in. For a non-register @@ -7519,6 +8142,7 @@ the exact address of the current instantiation of the variable. @kindex info symbol +@cindex symbol from address @item info symbol @var{addr} Print the name of a symbol which is stored at the address @var{addr}. If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the @@ -7595,6 +8219,26 @@ @code{whatis}, it does not print a detailed description; second, it lists all source files where a type is defined. +@kindex info scope +@cindex local variables +@item info scope @var{addr} +List all the variables local to a particular scope. This command +accepts a location---a function name, a source line, or an address +preceded by a @samp{*}, and prints all the variables local to the +scope defined by that location. For example: + +@smallexample +(@value{GDBP}) @b{info scope command_line_handler} +Scope for command_line_handler: +Symbol rl is an argument at stack/frame offset 8, length 4. +Symbol linebuffer is in static storage at address 0x150a18, length 4. +Symbol linelength is in static storage at address 0x150a1c, length 4. +Symbol p is a local variable in register $esi, length 4. +Symbol p1 is a local variable in register $ebx, length 4. +Symbol nline is a local variable in register $edx, length 4. +Symbol repeat is a local variable at frame offset -8, length 4. +@end smallexample + @kindex info source @item info source Show the name of the current source file---that is, the source file for @@ -7634,9 +8278,9 @@ @item info methods @itemx info methods @var{regexp} The @code{info methods} command permits the user to examine all defined -methods within C++ program, or (with the @var{regexp} argument) a -specific set of methods found in the various C++ classes. Many -C++ classes provide a large number of methods. Thus, the output +methods within C@t{++} program, or (with the @var{regexp} argument) a +specific set of methods found in the various C@t{++} classes. Many +C@t{++} classes provide a large number of methods. Thus, the output from the @code{ptype} command can be overwhelming and hard to use. The @code{info-methods} command filters the methods, printing only those which match the regular-expression @var{regexp}. @@ -8382,7 +9026,7 @@ @value{GDBN} could not find the full definition for a struct or class. @item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} -The symbol information for a C++ member function is missing some +The symbol information for a C@t{++} member function is missing some information that recent versions of the compiler should have output for it. @@ -11865,12 +12509,12 @@ debugging info. @kindex set debug overload @item set debug overload -Turns on or off display of @value{GDBN} C++ overload debugging +Turns on or off display of @value{GDBN} C@t{++} overload debugging info. This includes info such as ranking of functions, etc. The default is off. @kindex show debug overload @item show debug overload -Displays the current state of displaying @value{GDBN} C++ overload +Displays the current state of displaying @value{GDBN} C@t{++} overload debugging info. @kindex set debug remote @cindex packets, reporting on stdout