\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
-@c 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-@c 2010, 2011 Free Software Foundation, Inc.
+@c Copyright (C) 1988-1996, 1998-2012 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
Activate the @dfn{Text User Interface} when starting. The Text User
Interface manages several text windows on the terminal, showing
source, assembly, registers and @value{GDBN} command outputs
-(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the
-Text User Interface can be enabled by invoking the program
-@samp{@value{GDBTUI}}. Do not use this option if you run @value{GDBN} from
-Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
+(@pxref{TUI, ,@value{GDBN} Text User Interface}). Do not use this
+option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
+Using @value{GDBN} under @sc{gnu} Emacs}).
@c @item -xdb
@c @cindex @code{--xdb}
@table @code
@kindex shell
+@kindex !
@cindex shell escape
-@item shell @var{command string}
-Invoke a standard shell to execute @var{command string}.
+@item shell @var{command-string}
+@itemx !@var{command-string}
+Invoke a standard shell to execute @var{command-string}.
+Note that no space is needed between @code{!} and @var{command-string}.
If it exists, the environment variable @code{SHELL} determines which
shell to run. Otherwise @value{GDBN} uses the default shell
(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
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.
@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
@item @var{filename}:@var{linenum}
Specifies the line @var{linenum} in the source file @var{filename}.
+If @var{filename} is a relative file name, then it will match any
+source file name with the same trailing components. For example, if
+@var{filename} is @samp{gcc/expr.c}, then it will match source file
+name of @file{/build/trunk/gcc/expr.c}, but not
+@file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
@item @var{function}
Specifies the line that begins the body of the function @var{function}.
in this file. But it is possible to have more than one such variable or
function with the same name (in different source files). If that
happens, referring to that name has unpredictable effects. If you wish,
-you can specify a static variable in a particular function or file,
+you can specify a static variable in a particular function or file by
using the colon-colon (@code{::}) notation:
@cindex colon-colon, context for variables/functions
(@value{GDBP}) p 'f2.c'::x
@end smallexample
+The @code{::} notation is normally used for referring to
+static variables, since you typically disambiguate uses of local variables
+in functions by selecting the appropriate frame and using the
+simple name of the variable. However, you may also use this notation
+to refer to local variables in frames enclosing the selected frame:
+
+@smallexample
+void
+foo (int a)
+@{
+ if (a < 10)
+ bar (a);
+ else
+ process (a); /* Stop here */
+@}
+
+int
+bar (int a)
+@{
+ foo (a + 5);
+@}
+@end smallexample
+
+@noindent
+For example, if there is a breakpoint at the commented line,
+here is what you might see
+when the program stops after executing the call @code{bar(0)}:
+
+@smallexample
+(@value{GDBP}) p a
+$1 = 10
+(@value{GDBP}) p bar::a
+$2 = 5
+(@value{GDBP}) up 2
+#2 0x080483d0 in foo (a=5) at foobar.c:12
+(@value{GDBP}) p a
+$3 = 5
+(@value{GDBP}) p bar::a
+$4 = 0
+@end smallexample
+
@cindex C@t{++} scope resolution
-This use of @samp{::} is very rarely in conflict with the very similar
+These uses of @samp{::} are very rarely in conflict with the very similar
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
If remote stub doesn't support the @samp{InstallInTrace} feature, all
these changes don't take effect until the next @code{tstart}
command, and once a trace experiment is running, further changes will
-not have any effect until the next trace experiment starts.
+not have any effect until the next trace experiment starts. In addition,
+@value{GDBN} supports @dfn{pending tracepoints}---tracepoints whose
+address is not yet resolved. (This is similar to pending breakpoints.)
+Pending tracepoints are not downloaded to the target and not installed
+until they are resolved. The resolution of pending tracepoints requires
+@value{GDBN} support---when debugging with the remote target, and
+@value{GDBN} disconnects from the remote stub (@pxref{disconnected
+tracing}), pending tracepoints can not be resolved (and downloaded to
+the remote stub) while @value{GDBN} is disconnected.
Here are some examples of using the @code{trace} command:
@subsection Starting and Stopping Trace Experiments
@table @code
-@kindex tstart
+@kindex tstart [ @var{notes} ]
@cindex start a new trace experiment
@cindex collected data discarded
@item tstart
-This command takes no arguments. It starts the trace experiment, and
-begins collecting data. This has the side effect of discarding all
-the data collected in the trace buffer during the previous trace
-experiment.
-
-@kindex tstop
+This command starts the trace experiment, and begins collecting data.
+It has the side effect of discarding all the data collected in the
+trace buffer during the previous trace experiment. If any arguments
+are supplied, they are taken as a note and stored with the trace
+experiment's state. The notes may be arbitrary text, and are
+especially useful with disconnected tracing in a multi-user context;
+the notes can explain what the trace is doing, supply user contact
+information, and so forth.
+
+@kindex tstop [ @var{notes} ]
@cindex stop a running trace experiment
@item tstop
-This command takes no arguments. It ends the trace experiment, and
-stops collecting data.
+This command stops the trace experiment. If any arguments are
+supplied, they are recorded with the experiment as a note. This is
+useful if you are stopping a trace started by someone else, for
+instance if the trace is interfering with the system's behavior and
+needs to be stopped quickly.
@strong{Note}: a trace experiment and data collection may stop
automatically if any tracepoint's passcount is reached
@end table
+@table @code
+@item set trace-user @var{text}
+@kindex set trace-user
+
+@item show trace-user
+@kindex show trace-user
+
+@item set trace-notes @var{text}
+@kindex set trace-notes
+Set the trace run's notes.
+
+@item show trace-notes
+@kindex show trace-notes
+Show the trace run's notes.
+
+@item set trace-stop-notes @var{text}
+@kindex set trace-stop-notes
+Set the trace run's stop notes. The handling of the note is as for
+@code{tstop} arguments; the set command is convenient way to fix a
+stop note that is mistaken or incomplete.
+
+@item show trace-stop-notes
+@kindex show trace-stop-notes
+Show the trace run's stop notes.
+
+@end table
+
@node Tracepoint Restrictions
@subsection Tracepoint Restrictions
@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
target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
@end smallexample
-@var{comm} is either a device name (to use a serial line) or a TCP
-hostname and portnumber. For example, to debug Emacs with the argument
+@var{comm} is either a device name (to use a serial line), or a TCP
+hostname and portnumber, or @code{-} or @code{stdio} to use
+stdin/stdout of @code{gdbserver}.
+For example, to debug Emacs with the argument
@samp{foo.txt} and communicate with @value{GDBN} over the serial port
@file{/dev/com1}:
and exits.} You must use the same port number with the host @value{GDBN}
@code{target remote} command.
+The @code{stdio} connection is useful when starting @code{gdbserver}
+with ssh:
+
+@smallexample
+(gdb) target remote | ssh -T hostname gdbserver - hello
+@end smallexample
+
+The @samp{-T} option to ssh is provided because we don't need a remote pty,
+and we don't want escape-character handling. Ssh does this by default when
+a command is provided, the flag is provided to make it explicit.
+You could elide it if you want to.
+
+Programs started with stdio-connected gdbserver have @file{/dev/null} for
+@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for
+display through a pipe connected to gdbserver.
+Both @code{stdout} and @code{stderr} use the same pipe.
+
@subsubsection Attaching to a Running Program
@cindex attach to a program, @code{gdbserver}
@cindex @option{--attach}, @code{gdbserver} option
@tab @code{vFile:unlink}
@tab @code{remote delete}
+@item @code{hostio-readlink-packet}
+@tab @code{vFile:readlink}
+@tab Host I/O
+
@item @code{noack-packet}
@tab @code{QStartNoAckMode}
@tab Packet acknowledgment
@findex set_debug_traps
@cindex remote serial stub, initialization
This routine arranges for @code{handle_exception} to run when your
-program stops. You must call this subroutine explicitly near the
-beginning of your program.
+program stops. You must call this subroutine explicitly in your
+program's startup code.
@item handle_exception
@findex handle_exception
@end display
@item
-Insert these lines near the top of your program:
+Insert these lines in your program's startup code, before the main
+procedure is called:
@smallexample
set_debug_traps();
breakpoint();
@end smallexample
+On some machines, when a breakpoint trap is raised, the hardware
+automatically makes the PC point to the instruction after the
+breakpoint. If your machine doesn't do that, you may need to adjust
+@code{handle_exception} to arrange for it to return to the instruction
+after the breakpoint on this first invocation, so that your program
+doesn't keep hitting the initial breakpoint instead of making
+progress.
+
@item
For the 680x0 stub only, you need to provide a variable called
@code{exceptionHook}. Normally you just use:
23
@end smallexample
-@kindex maint set python print-stack
-@item maint set python print-stack
-This command is now deprecated. Instead use @code{set python
-print-stack}
-
@kindex set python print-stack
@item set python print-stack
-By default, @value{GDBN} will not print a stack trace when an error
-occurs in a Python script. This can be controlled using @code{set
-python print-stack}: if @code{on}, then Python stack printing is
-enabled; if @code{off}, the default, then Python stack printing is
-disabled.
+By default, @value{GDBN} will print only the message component of a
+Python exception when an error occurs in a Python script. This can be
+controlled using @code{set python print-stack}: if @code{full}, then
+full Python stack printing is enabled; if @code{none}, then Python stack
+and message printing is disabled; if @code{message}, the default, only
+the message component of the error is printed.
@end table
It is also possible to execute a Python script from the @value{GDBN}
* Symbol Tables In Python:: Python representation of symbol tables.
* Lazy Strings In Python:: Python representation of lazy strings.
* Breakpoints In Python:: Manipulating breakpoints using Python.
+* Finish Breakpoints in Python:: Setting Breakpoints on function return
+ using Python.
@end menu
@node Basic Python
@smallexample
def register_printers(objfile):
- objfile.pretty_printers.add(str_lookup_function)
+ objfile.pretty_printers.append(str_lookup_function)
@end smallexample
@noindent
attribute is @code{None}. This attribute is not writable.
@end defvar
+@node Finish Breakpoints in Python
+@subsubsection Finish Breakpoints
+
+@cindex python finish breakpoints
+@tindex gdb.FinishBreakpoint
+
+A finish breakpoint is a temporary breakpoint set at the return address of
+a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint}
+extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled
+and deleted when the execution will run out of the breakpoint scope (i.e.@:
+@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
+Finish breakpoints are thread specific and must be create with the right
+thread selected.
+
+@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
+Create a finish breakpoint at the return address of the @code{gdb.Frame}
+object @var{frame}. If @var{frame} is not provided, this defaults to the
+newest frame. The optional @var{internal} argument allows the breakpoint to
+become invisible to the user. @xref{Breakpoints In Python}, for further
+details about this argument.
+@end defun
+
+@defun FinishBreakpoint.out_of_scope (self)
+In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN}
+@code{return} command, @dots{}), a function may not properly terminate, and
+thus never hit the finish breakpoint. When @value{GDBN} notices such a
+situation, the @code{out_of_scope} callback will be triggered.
+
+You may want to sub-class @code{gdb.FinishBreakpoint} and override this
+method:
+
+@smallexample
+class MyFinishBreakpoint (gdb.FinishBreakpoint)
+ def stop (self):
+ print "normal finish"
+ return True
+
+ def out_of_scope ():
+ print "abnormal finish"
+@end smallexample
+@end defun
+
+@defvar FinishBreakpoint.return_value
+When @value{GDBN} is stopped at a finish breakpoint and the frame
+used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
+attribute will contain a @code{gdb.Value} object corresponding to the return
+value of the function. The value will be @code{None} if the function return
+type is @code{void} or if the return value was not computable. This attribute
+is not writable.
+@end defvar
+
@node Lazy Strings In Python
@subsubsection Python representation of lazy strings.
regular expressions.
@xref{Writing a Pretty-Printer}, for an example.
+@item FlagEnumerationPrinter (@var{name})
+A pretty-printer which handles printing of @code{enum} values. Unlike
+@value{GDBN}'s built-in @code{enum} printing, this printer attempts to
+work properly when there is some overlap between the enumeration
+constants. @var{name} is the name of the printer and also the name of
+the @code{enum} type to look up.
+
@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
Register @var{printer} with the pretty-printer list of @var{obj}.
If @var{replace} is @code{True} then any existing copy of the printer
on platforms where a suitable version of the @code{curses} library
is available.
-@pindex @value{GDBTUI}
The TUI mode is enabled by default when you invoke @value{GDBN} as
-either @samp{@value{GDBTUI}} or @samp{@value{GDBP} -tui}.
+@samp{@value{GDBP} -tui}.
You can also switch in and out of TUI mode while @value{GDBN} runs by
using various TUI commands and key bindings, such as @kbd{C-x C-a}.
@xref{TUI Keys, ,TUI Key Bindings}.
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
* Declarations:: Relevant C struct declarations
* Registering Code:: Steps to register code
* Unregistering Code:: Steps to unregister code
+* Custom Debug Info:: Emit debug information in a custom format
@end menu
@node Declarations
If the JIT frees or recompiles code without unregistering it, then @value{GDBN}
and the JIT will leak the memory used for the associated symbol files.
+@node Custom Debug Info
+@section Custom Debug Info
+@cindex custom JIT debug info
+@cindex JIT debug info reader
+
+Generating debug information in platform-native file formats (like ELF
+or COFF) may be an overkill for JIT compilers; especially if all the
+debug info is used for is displaying a meaningful backtrace. The
+issue can be resolved by having the JIT writers decide on a debug info
+format and also provide a reader that parses the debug info generated
+by the JIT compiler. This section gives a brief overview on writing
+such a parser. More specific details can be found in the source file
+@file{gdb/jit-reader.in}, which is also installed as a header at
+@file{@var{includedir}/gdb/jit-reader.h} for easy inclusion.
+
+The reader is implemented as a shared object (so this functionality is
+not available on platforms which don't allow loading shared objects at
+runtime). Two @value{GDBN} commands, @code{jit-reader-load} and
+@code{jit-reader-unload} are provided, to be used to load and unload
+the readers from a preconfigured directory. Once loaded, the shared
+object is used the parse the debug information emitted by the JIT
+compiler.
+
+@menu
+* Using JIT Debug Info Readers:: How to use supplied readers correctly
+* Writing JIT Debug Info Readers:: Creating a debug-info reader
+@end menu
+
+@node Using JIT Debug Info Readers
+@subsection Using JIT Debug Info Readers
+@kindex jit-reader-load
+@kindex jit-reader-unload
+
+Readers can be loaded and unloaded using the @code{jit-reader-load}
+and @code{jit-reader-unload} commands.
+
+@table @code
+@item jit-reader-load @var{reader-name}
+Load the JIT reader named @var{reader-name}. On a UNIX system, this
+will usually load @file{@var{libdir}/gdb/@var{reader-name}}, where
+@var{libdir} is the system library directory, usually
+@file{/usr/local/lib}. Only one reader can be active at a time;
+trying to load a second reader when one is already loaded will result
+in @value{GDBN} reporting an error. A new JIT reader can be loaded by
+first unloading the current one using @code{jit-reader-load} and then
+invoking @code{jit-reader-load}.
+
+@item jit-reader-unload
+Unload the currently loaded JIT reader.
+
+@end table
+
+@node Writing JIT Debug Info Readers
+@subsection Writing JIT Debug Info Readers
+@cindex writing JIT debug info readers
+
+As mentioned, a reader is essentially a shared object conforming to a
+certain ABI. This ABI is described in @file{jit-reader.h}.
+
+@file{jit-reader.h} defines the structures, macros and functions
+required to write a reader. It is installed (along with
+@value{GDBN}), in @file{@var{includedir}/gdb} where @var{includedir} is
+the system include directory.
+
+Readers need to be released under a GPL compatible license. A reader
+can be declared as released under such a license by placing the macro
+@code{GDB_DECLARE_GPL_COMPATIBLE_READER} in a source file.
+
+The entry point for readers is the symbol @code{gdb_init_reader},
+which is expected to be a function with the prototype
+
+@findex gdb_init_reader
+@smallexample
+extern struct gdb_reader_funcs *gdb_init_reader (void);
+@end smallexample
+
+@cindex @code{struct gdb_reader_funcs}
+
+@code{struct gdb_reader_funcs} contains a set of pointers to callback
+functions. These functions are executed to read the debug info
+generated by the JIT compiler (@code{read}), to unwind stack frames
+(@code{unwind}) and to create canonical frame IDs
+(@code{get_Frame_id}). It also has a callback that is called when the
+reader is being unloaded (@code{destroy}). The struct looks like this
+
+@smallexample
+struct gdb_reader_funcs
+@{
+ /* Must be set to GDB_READER_INTERFACE_VERSION. */
+ int reader_version;
+
+ /* For use by the reader. */
+ void *priv_data;
+
+ gdb_read_debug_info *read;
+ gdb_unwind_frame *unwind;
+ gdb_get_frame_id *get_frame_id;
+ gdb_destroy_reader *destroy;
+@};
+@end smallexample
+
+@cindex @code{struct gdb_symbol_callbacks}
+@cindex @code{struct gdb_unwind_callbacks}
+
+The callbacks are provided with another set of callbacks by
+@value{GDBN} to do their job. For @code{read}, these callbacks are
+passed in a @code{struct gdb_symbol_callbacks} and for @code{unwind}
+and @code{get_frame_id}, in a @code{struct gdb_unwind_callbacks}.
+@code{struct gdb_symbol_callbacks} has callbacks to create new object
+files and new symbol tables inside those object files. @code{struct
+gdb_unwind_callbacks} has callbacks to read registers off the current
+frame and to write out the values of the registers in the previous
+frame. Both have a callback (@code{target_read}) to read bytes off the
+target's address space.
+
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
@cindex bugs in @value{GDBN}
@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
* 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::
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}).
conventions above. Please don't use this packet as a model for new
packets.)
+@item QTNotes
+@item qTP
@item QTSave
@item qTsP
@item qTsV
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 tnotrun:0
No trace has been run yet.
-@item tstop:0
-The trace was stopped by a user-originated stop command.
+@item tstop[:@var{text}]:0
+The trace was stopped by a user-originated stop command. The optional
+@var{text} field is a user-supplied string supplied as part of the
+stop command (for instance, an explanation of why the trace was
+stopped manually). It is hex-encoded.
@item tfull:0
The trace stopped because the trace buffer filled up.
@end table
+@item qTP:@var{tp}:@var{addr}
+@cindex tracepoint status, remote request
+@cindex @samp{qTP} packet
+Ask the stub for the current state of tracepoint number @var{tp} at
+address @var{addr}.
+
+Replies:
+@table @samp
+@item V@var{hits}:@var{usage}
+The tracepoint has been hit @var{hits} times so far during the trace
+run, and accounts for @var{usage} in the trace buffer. Note that
+@code{while-stepping} steps are not counted as separate hits, but the
+steps' space consumption is added into the usage number.
+
+@end table
+
@item qTV:@var{var}
@cindex trace state variable value, remote request
@cindex @samp{qTV} packet
This packet directs the target to use a circular trace buffer if
@var{value} is 1, or a linear buffer if the value is 0.
+@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{}
+This packet adds optional textual notes to the trace run. Allowable
+types include @code{user}, @code{notes}, and @code{tstop}, the
+@var{text} fields are arbitrary strings, hex-encoded.
+
@end table
@subsection Relocate instruction reply packet
Delete the file at @var{pathname} on the target. Return 0,
or -1 if an error occurs. @var{pathname} is a string.
+@item vFile:readlink: @var{filename}
+Read value of symbolic link @var{filename} on the target. Return
+the number of bytes read, or -1 if an error occurs.
+
+The data read should be returned as a binary attachment on success.
+If zero bytes were read, the response should include an empty binary
+attachment (i.e.@: a trailing semicolon). The return value is the
+number of target bytes read; the binary attachment may be longer if
+some characters were escaped.
+
@end table
@node Interrupts
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
projects / deliverable / binutils-gdb.git / blobdiff