the "ambiguous linespec" series

[deliverable/binutils-gdb.git] / gdb / doc / gdb.texinfo

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 0aa90eb49584fa7ef699f130c170617aadbcbab0..50c299e480d0723b81d97cc888500117829576f7 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1347,9 +1347,12 @@ just use the @code{shell} command.
 
 @table @code
 @kindex shell
 
 @table @code
 @kindex shell

+@kindex !

 @cindex shell escape
 @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.).
 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.).


@@ -1873,14 +1876,18 @@ format; if your @sc{gnu} C compiler has this option, do not use it.
 @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
 @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
 
 @need 2000
 @node Starting


@@ -3216,6 +3223,8 @@ running or not, what process it is, and why it stopped.
 @menu
 * Breakpoints::                 Breakpoints, watchpoints, and catchpoints
 * Continuing and Stepping::     Resuming execution
 @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
 * Signals::                     Signals
 * Thread Stops::                Stopping and starting multi-thread programs
 @end menu


@@ -3512,6 +3521,9 @@ It is possible that a breakpoint corresponds to several locations
 in your program.  Examples of this situation are:
 
 @itemize @bullet
 in your program.  Examples of this situation are:
 
 @itemize @bullet

+@item
+Multiple functions in the program may have the same name.
+

 @item
 For a C@t{++} constructor, the @value{NGCC} compiler generates several
 instances of the function body, used in different cases.
 @item
 For a C@t{++} constructor, the @value{NGCC} compiler generates several
 instances of the function body, used in different cases.


@@ -3526,11 +3538,7 @@ several places where that function is inlined.
 @end itemize
 
 In all those cases, @value{GDBN} will insert a breakpoint at all
 @end itemize
 
 In all those cases, @value{GDBN} will insert a breakpoint at all

-the relevant locations@footnote{
-As of this writing, multiple-location breakpoints work only if there's
-line number information for all the locations.  This means that they
-will generally not work in system libraries, unless you have debug
-info with line numbers for them.}.
+the relevant locations.

 
 A breakpoint with multiple locations is displayed in the breakpoint
 table using several rows---one header row, followed by one row for
 
 A breakpoint with multiple locations is displayed in the breakpoint
 table using several rows---one header row, followed by one row for


@@ -4854,6 +4862,111 @@ proceed until the function returns.
 An argument is a repeat count, as in @code{next}.
 @end table
 
 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
 @node Signals
 @section Signals
 @cindex signals


@@ -7262,15 +7375,9 @@ No symbol "foo" in current context.
 
 To solve such problems, either recompile without optimizations, or use a
 different debug info format, if the compiler supports several such
 
 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
 
 If you ask to print an object whose contents are unknown to
 @value{GDBN}, e.g., because its data type is not completely specified


@@ -8265,7 +8372,10 @@ Display the encoding style currently in use for decoding C@t{++} symbols.
 @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
 @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
 
 @item set print object off
 Display only the declared type of objects, without reference to the


@@ -9903,9 +10013,12 @@ can be any string of tokens.
 @cindex macro definition, showing
 @cindex definition of a macro, showing
 @cindex macros, from debug info
 @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}
 
 @kindex info macros
 @item info macros @var{linespec}


@@ -9913,12 +10026,6 @@ Show all macro definitions that are in effect at the location specified
 by @var{linespec},  and describe the source location or compiler
 command-line where those definitions were established.
 
 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
 @kindex macro define
 @cindex user-defined macros
 @cindex defining macros interactively


@@ -9976,9 +10083,12 @@ $ cat sample.h
 $
 @end smallexample
 
 $
 @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
 information.
 
 @smallexample


@@ -10223,9 +10333,21 @@ an address in the target program.  @xref{Specify Location}.  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
 @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
 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:
 
 
 Here are some examples of using the @code{trace} command:
 


@@ -10266,6 +10388,23 @@ message.
 @value{GDBN} handles arguments to @code{ftrace} exactly as for
 @code{trace}.
 
 @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
 @item strace @var{location} [ if @var{cond} ]
 @cindex set static tracepoint
 @cindex static tracepoints, setting


@@ -10561,7 +10700,7 @@ end
 @end smallexample
 
 @kindex collect @r{(tracepoints)}
 @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
 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


@@ -10607,6 +10746,15 @@ 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.
 
 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.
 
 The command @code{info scope} (@pxref{Symbols, info scope}) is
 particularly useful for figuring out what data to collect.
 


@@ -10753,20 +10901,27 @@ Cnt ID         Enb Address            What
 @subsection Starting and Stopping Trace Experiments
 
 @table @code
 @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
 @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
 @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
 
 @strong{Note}: a trace experiment and data collection may stop
 automatically if any tracepoint's passcount is reached


@@ -10870,6 +11025,33 @@ for instance if you are looking at frames from a trace file.
 
 @end table
 
 
 @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
 
 @node Tracepoint Restrictions
 @subsection Tracepoint Restrictions
 


@@ -12057,13 +12239,6 @@ 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}).
 
 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
 @menu
 * C Operators::                 C and C@t{++} operators
 * C Constants::                 C and C@t{++} constants


@@ -12273,6 +12448,11 @@ of the character's ordinal value; or of the form @samp{\@var{x}}, where
 @samp{@var{x}} is a predefined special character---for example,
 @samp{\n} for newline.
 
 @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
 @item
 String constants are a sequence of character constants surrounded by
 double quotes (@code{"}).  Any valid character constant (as described


@@ -12280,6 +12460,10 @@ above) may appear.  Double quotes within the string must be preceded by
 a backslash, so for instance @samp{"a\"b'c"} is a string of five
 characters.
 
 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{&}.
 @item
 Pointer constants are an integral value.  You can also write pointers
 to constants using the C operator @samp{&}.


@@ -12302,16 +12486,14 @@ and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
 @cindex debug formats and C@t{++}
 @cindex @value{NGCC} and C@t{++}
 @quotation
 @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
 @end quotation
 
 @enumerate


@@ -12330,7 +12512,8 @@ count = aml->GetOriginal(x, y)
 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
 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
 
 @cindex call overloaded functions
 @cindex overloaded functions, calling


@@ -12382,12 +12565,11 @@ 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@t{++}
 debugging (@pxref{Variables, ,Program Variables}).
 @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
 
 @node C Defaults
 @subsubsection C and C@t{++} Defaults


@@ -15564,6 +15746,33 @@ This is the default.
 @end table
 @end table
 
 @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
 
 @node Separate Debug Files
 @section Debugging Information in Separate Files


@@ -17200,6 +17409,10 @@ are:
 @tab @code{qXfer:traceframe-info:read}
 @tab 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}
 @item @code{disable-randomization}
 @tab @code{QDisableRandomization}
 @tab @code{set disable-randomization}


@@ -19724,7 +19937,6 @@ default).
 @item n64
 @item eabi32
 @item eabi64
 @item n64
 @item eabi32
 @item eabi64

-@item auto

 @end table
 
 @item show mips abi
 @end table
 
 @item show mips abi


@@ -21681,6 +21893,21 @@ that includes @acronym{RTTI} for the object in question.  Otherwise,
 it will just return the static type of the value as in @kbd{ptype foo}
 (@pxref{Symbols, ptype}).
 @end defvar
 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:
 @end table
 
 The following methods are provided:


@@ -21814,6 +22041,19 @@ fetched and encoded to the length of characters specified.  If
 the @var{length} argument is not provided, the string will be fetched
 and encoded until a null of appropriate width is found.
 @end defun
 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
 @end table
 
 @node Types In Python


@@ -22350,7 +22590,7 @@ this code might appear in @code{gdb.libstdcxx.v6}:
 
 @smallexample
 def register_printers(objfile):
 
 @smallexample
 def register_printers(objfile):

-    objfile.pretty_printers.add(str_lookup_function)
+    objfile.pretty_printers.append(str_lookup_function)

 @end smallexample
 
 @noindent
 @end smallexample
 
 @noindent


@@ -22752,7 +22992,7 @@ You can implement new @value{GDBN} CLI commands in Python.  A CLI
 command is implemented using an instance of the @code{gdb.Command}
 class, most commonly using a subclass.
 
 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.
 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.


@@ -23445,6 +23685,19 @@ 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_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
 @end table
 
 @end defun


@@ -23549,6 +23802,27 @@ attribute is not writable.
 The block containing this block.  If this parent block does not exist,
 this attribute holds @code{None}.  This attribute is not writable.
 @end defvar
 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
 @end table
 
 @node Symbols In Python


@@ -24375,6 +24649,35 @@ Return @code{True} if @var{type}, assumed to be a type with fields
 
 @item make_enum_dict (@var{enum_type})
 Return a Python @code{dictionary} type produced from @var{enum_type}.
 
 @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 table
 
 @node gdb.prompt


@@ -25868,6 +26171,25 @@ The inferior exited.
 The inferior exited normally.
 @item signal-received 
 A signal was received by the inferior.
 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
 @end table
 
 The @var{id} field identifies the thread that directly caused the stop


@@ -31505,6 +31827,7 @@ out about additional code.
 * Declarations::                Relevant C struct declarations
 * Registering Code::            Steps to register code
 * Unregistering Code::          Steps to unregister code
 * 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
 @end menu
 
 @node Declarations


@@ -31601,6 +31924,121 @@ Set @code{action_flag} to @code{JIT_UNREGISTER} and call
 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.
 
 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}
 @node GDB Bugs
 @chapter Reporting Bugs in @value{GDBN}
 @cindex bugs in @value{GDBN}


@@ -32009,7 +32447,8 @@ Remote protocol memory maps (@pxref{Memory Map Format})
 @item
 Target descriptions (@pxref{Target Descriptions})
 @item
 @item
 Target descriptions (@pxref{Target Descriptions})
 @item

-Remote shared library lists (@pxref{Library List Format})
+Remote shared library lists (@xref{Library List Format},
+or alternatively @pxref{Library List Format for SVR4 Targets})

 @item
 MS-Windows shared libraries (@pxref{Shared Libraries})
 @item
 @item
 MS-Windows shared libraries (@pxref{Shared Libraries})
 @item


@@ -32784,13 +33223,16 @@ switch (@pxref{Mode Options}).
 @kindex maint time
 @cindex time of command execution
 @item maint time
 @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.
 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}).
 
 This can also be requested by invoking @value{GDBN} with the
 @option{--statistics} command-line switch (@pxref{Mode Options}).
 


@@ -32843,6 +33285,7 @@ Show the current setting of the target wait timeout.
 * Examples::
 * File-I/O Remote Protocol Extension::
 * Library List Format::
 * Examples::
 * File-I/O Remote Protocol Extension::
 * Library List Format::

+* Library List Format for SVR4 Targets::

 * Memory Map Format::
 * Thread List Format::
 * Traceframe Info Format::
 * Memory Map Format::
 * Thread List Format::
 * Traceframe Info Format::


@@ -34511,6 +34954,11 @@ These are the currently defined stub features and their properties:
 @tab @samp{-}
 @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:
 @end multitable
 
 These are the currently defined stub features, in more detail:


@@ -34539,6 +34987,10 @@ The remote stub understands the @samp{qXfer:features:read} packet
 The remote stub understands the @samp{qXfer:libraries:read} packet
 (@pxref{qXfer library list read}).
 
 The remote stub understands the @samp{qXfer:libraries:read} packet
 (@pxref{qXfer library list read}).
 

+@item qXfer:libraries-svr4:read
+The remote stub understands the @samp{qXfer:libraries-svr4:read} packet
+(@pxref{qXfer svr4 library list read}).
+

 @item qXfer:memory-map:read
 The remote stub understands the @samp{qXfer:memory-map:read} packet
 (@pxref{qXfer memory map read}).
 @item qXfer:memory-map:read
 The remote stub understands the @samp{qXfer:memory-map:read} packet
 (@pxref{qXfer memory map read}).


@@ -34630,11 +35082,20 @@ The remote stub understands the @samp{QDisableRandomization} packet.
 @cindex static tracepoints, in remote protocol
 The remote stub supports static tracepoints.
 
 @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 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::
 @end table
 
 @item qSymbol::


@@ -34683,6 +35144,8 @@ encoded).  @value{GDBN} will continue to supply the values of symbols
 @itemx qTfP
 @itemx qTfV
 @itemx QTFrame
 @itemx qTfP
 @itemx qTfV
 @itemx QTFrame

+@itemx qTMinFTPILen
+

 @xref{Tracepoint Packets}.
 
 @item qThreadExtraInfo,@var{thread-id}
 @xref{Tracepoint Packets}.
 
 @item qThreadExtraInfo,@var{thread-id}


@@ -34710,6 +35173,8 @@ the command by a @samp{,}, not a @samp{:}, contrary to the naming
 conventions above.  Please don't use this packet as a model for new
 packets.)
 
 conventions above.  Please don't use this packet as a model for new
 packets.)
 

+@item QTNotes
+@item qTP

 @item QTSave
 @item qTsP
 @item qTsV
 @item QTSave
 @item qTsP
 @item qTsV


@@ -34771,6 +35236,18 @@ the operating system manages the list of loaded libraries.
 This packet is not probed by default; the remote stub must request it,
 by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
 
 This packet is not probed by default; the remote stub must request it,
 by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
 

+@item qXfer:libraries-svr4:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer svr4 library list read}
+Access the target's list of loaded libraries when the target is an SVR4
+platform.  @xref{Library List Format for SVR4 Targets}.  The annex part
+of the generic @samp{qXfer} packet must be empty (@pxref{qXfer read}).
+
+This packet is optional for better performance on SVR4 targets.  
+@value{GDBN} uses memory read packets to read the SVR4 library list otherwise.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+

 @item qXfer:memory-map:read::@var{offset},@var{length}
 @anchor{qXfer memory map read}
 Access the target's @dfn{memory-map}.  @xref{Memory Map Format}.  The
 @item qXfer:memory-map:read::@var{offset},@var{length}
 @anchor{qXfer memory map read}
 Access the target's @dfn{memory-map}.  @xref{Memory Map Format}.  The


@@ -35206,6 +35683,30 @@ numbers.
 Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
 frame @emph{outside} the given range of addresses (exclusive).
 
 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 QTStart
 Begin the tracepoint experiment.  Begin collecting data from
 tracepoint hits in the trace frame buffer.  This packet supports the


@@ -35268,8 +35769,11 @@ explanations as one of the optional fields:
 @item tnotrun:0
 No trace has been run yet.
 
 @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.
 
 @item tfull:0
 The trace stopped because the trace buffer filled up.


@@ -35325,6 +35829,22 @@ that the trace run will stop.
 
 @end table
 
 
 @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
 @item qTV:@var{var}
 @cindex trace state variable value, remote request
 @cindex @samp{qTV} packet


@@ -35418,6 +35938,11 @@ available.
 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.
 
 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
 @end table
 
 @subsection Relocate instruction reply packet


@@ -37034,6 +37559,68 @@ In addition, segments and section descriptors cannot be mixed within a
 single library element, and you must supply at least one segment or
 section for each library.
 
 single library element, and you must supply at least one segment or
 section for each library.
 

+@node Library List Format for SVR4 Targets
+@section Library List Format for SVR4 Targets
+@cindex library list format, remote protocol
+
+On SVR4 platforms @value{GDBN} can use the symbol table of a dynamic loader
+(e.g.@: @file{ld.so}) and normal memory operations to maintain a list of
+shared libraries.  Still a special library list provided by this packet is
+more efficient for the @value{GDBN} remote protocol.
+
+The @samp{qXfer:libraries-svr4:read} packet returns an XML document which lists
+loaded libraries and their SVR4 linker parameters.  For each library on SVR4
+target, the following parameters are reported:
+
+@itemize @minus
+@item
+@code{name}, the absolute file name from the @code{l_name} field of
+@code{struct link_map}.
+@item
+@code{lm} with address of @code{struct link_map} used for TLS
+(Thread Local Storage) access.
+@item
+@code{l_addr}, the displacement as read from the field @code{l_addr} of
+@code{struct link_map}.  For prelinked libraries this is not an absolute
+memory address.  It is a displacement of absolute memory address against
+address the file was prelinked to during the library load.
+@item
+@code{l_ld}, which is memory address of the @code{PT_DYNAMIC} segment
+@end itemize
+
+Additionally the single @code{main-lm} attribute specifies address of
+@code{struct link_map} used for the main executable.  This parameter is used
+for TLS access and its presence is optional.
+
+@value{GDBN} must be linked with the Expat library to support XML
+SVR4 library lists.  @xref{Expat}.
+
+A simple memory map, with two loaded libraries (which do not use prelink),
+looks like this:
+
+@smallexample
+<library-list-svr4 version="1.0" main-lm="0xe4f8f8">
+  <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
+           l_ld="0xe4eefc"/>
+  <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
+           l_ld="0x152350"/>
+</library-list-svr>
+@end smallexample
+
+The format of an SVR4 library list is described by this DTD:
+
+@smallexample
+<!-- library-list-svr4: Root element with versioning -->
+<!ELEMENT library-list-svr4  (library)*>
+<!ATTLIST library-list-svr4  version CDATA   #FIXED  "1.0">
+<!ATTLIST library-list-svr4  main-lm CDATA   #IMPLIED>
+<!ELEMENT library            EMPTY>
+<!ATTLIST library            name    CDATA   #REQUIRED>
+<!ATTLIST library            lm      CDATA   #REQUIRED>
+<!ATTLIST library            l_addr  CDATA   #REQUIRED>
+<!ATTLIST library            l_ld    CDATA   #REQUIRED>
+@end smallexample
+

 @node Memory Map Format
 @section Memory Map Format
 @cindex memory map format
 @node Memory Map Format
 @section Memory Map Format
 @cindex memory map format