* GDB/MI:: @value{GDBN}'s Machine Interface.
* Annotations:: @value{GDBN}'s annotation interface.
* JIT Interface:: Using the JIT debugging interface.
+* In-Process Agent:: In-Process Agent
* GDB Bugs:: Reporting bugs in @value{GDBN}
-x setbreakpoints -ex 'run' a.out
@end smallexample
+@item -init-command @var{file}
+@itemx -ix @var{file}
+@cindex @code{--init-command}
+@cindex @code{-ix}
+Execute commands from file @var{file} before loading gdbinit files or the
+inferior.
+@xref{Startup}.
+
+@item -init-eval-command @var{command}
+@itemx -iex @var{command}
+@cindex @code{--init-eval-command}
+@cindex @code{-iex}
+Execute a single @value{GDBN} command before loading gdbinit files or the
+inferior.
+@xref{Startup}.
+
@item -directory @var{directory}
@itemx -d @var{directory}
@cindex @code{--directory}
This option causes @value{GDBN} to print its version number and
no-warranty blurb, and exit.
+@item -use-deprecated-index-sections
+@cindex @code{--use-deprecated-index-sections}
+This option causes @value{GDBN} to read and use deprecated
+@samp{.gdb_index} sections from symbol files. This can speed up
+startup, but may result in some functionality being lost.
+@xref{Index Section Format}.
+
@end table
@node Startup
Sets up the command interpreter as specified by the command line
(@pxref{Mode Options, interpreter}).
+@item
+Executes commands and command files specified by the @samp{-iex} and
+@samp{-ix} options in their specified order. Usually you should use the
+@samp{-ex} and @samp{-x} options instead, but this way you can apply
+settings before @value{GDBN} init files get executed and before inferior
+gets loaded.
+
@item
@cindex init file
Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was
you must do something like the following:
@smallexample
-$ gdb -ex "set auto-load-scripts off" -ex "file myprogram"
+$ gdb -iex "set auto-load-scripts off" myprogram
@end smallexample
-The following does not work because the auto-loading is turned off too late:
-
-@smallexample
-$ gdb -ex "set auto-load-scripts off" myprogram
-@end smallexample
+Option @samp{-ex} does not work because the auto-loading is then turned
+off too late.
@item
-Reads command files specified by the @samp{-x} option. @xref{Command
-Files}, for more details about @value{GDBN} command files.
+Executes commands and command files specified by the @samp{-ex} and
+@samp{-x} options in their specified order. @xref{Command Files}, for
+more details about @value{GDBN} command files.
@item
Reads the command history recorded in the @dfn{history file}.
@var{args}. It prints out all matches found. For example:
@smallexample
-apropos reload
+apropos alias
@end smallexample
@noindent
@smallexample
@c @group
-set symbol-reloading -- Set dynamic symbol table reloading
- multiple times in one run
-show symbol-reloading -- Show dynamic symbol table reloading
- multiple times in one run
+alias -- Define a new command that is an alias of an existing command
+aliases -- Aliases of other commands
+d -- Delete some breakpoints or auto-display expressions
+del -- Delete some breakpoints or auto-display expressions
+delete -- Delete some breakpoints or auto-display expressions
@c @end group
@end smallexample
@end table
@noindent
-If a breakpoint is conditional, @code{info break} shows the condition on
-the line following the affected breakpoint; breakpoint commands, if any,
-are listed after that. A pending breakpoint is allowed to have a condition
-specified for it. The condition is not parsed for validity until a shared
-library is loaded that allows the pending breakpoint to resolve to a
-valid location.
+If a breakpoint is conditional, there are two evaluation modes: ``host'' and
+``target''. If mode is ``host'', breakpoint condition evaluation is done by
+@value{GDBN} on the host's side. If it is ``target'', then the condition
+is evaluated by the target. The @code{info break} command shows
+the condition on the line following the affected breakpoint, together with
+its condition evaluation mode in between parentheses.
+
+Breakpoint commands, if any, are listed after that. A pending breakpoint is
+allowed to have a condition specified for it. The condition is not parsed for
+validity until a shared library is loaded that allows the pending
+breakpoint to resolve to a valid location.
@noindent
@code{info break} with a breakpoint
hits, look at the breakpoint info to see how many times the breakpoint
was hit, and then run again, ignoring one less than that number. This
will get you quickly to the last hit of that breakpoint.
+
+@noindent
+For a breakpoints with an enable count (xref) greater than 1,
+@code{info break} also displays that count.
+
@end table
@value{GDBN} allows you to set any number of breakpoints at the same place in
@code{breakpoint always-inserted} mode is off.
@end table
+@value{GDBN} handles conditional breakpoints by evaluating these conditions
+when a breakpoint breaks. If the condition is true, then the process being
+debugged stops, otherwise the process is resumed.
+
+If the target supports evaluating conditions on its end, @value{GDBN} may
+download the breakpoint, together with its conditions, to it.
+
+This feature can be controlled via the following commands:
+
+@kindex set breakpoint condition-evaluation
+@kindex show breakpoint condition-evaluation
+@table @code
+@item set breakpoint condition-evaluation host
+This option commands @value{GDBN} to evaluate the breakpoint
+conditions on the host's side. Unconditional breakpoints are sent to
+the target which in turn receives the triggers and reports them back to GDB
+for condition evaluation. This is the standard evaluation mode.
+
+@item set breakpoint condition-evaluation target
+This option commands @value{GDBN} to download breakpoint conditions
+to the target at the moment of their insertion. The target
+is responsible for evaluating the conditional expression and reporting
+breakpoint stop events back to @value{GDBN} whenever the condition
+is true. Due to limitations of target-side evaluation, some conditions
+cannot be evaluated there, e.g., conditions that depend on local data
+that is only known to the host. Examples include
+conditional expressions involving convenience variables, complex types
+that cannot be handled by the agent expression parser and expressions
+that are too long to be sent over to the target, specially when the
+target is a remote system. In these cases, the conditions will be
+evaluated by @value{GDBN}.
+
+@item set breakpoint condition-evaluation auto
+This is the default mode. If the target supports evaluating breakpoint
+conditions on its end, @value{GDBN} will download breakpoint conditions to
+the target (limitations mentioned previously apply). If the target does
+not support breakpoint condition evaluation, then @value{GDBN} will fallback
+to evaluating all these conditions on the host's side.
+@end table
+
+
@cindex negative breakpoint numbers
@cindex internal @value{GDBN} breakpoints
@value{GDBN} itself sometimes sets breakpoints in your program for
A call to @code{vfork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
+@item load @r{[}regexp@r{]}
+@itemx unload @r{[}regexp@r{]}
+The loading or unloading of a shared library. If @var{regexp} is
+given, then the catchpoint will stop only if the regular expression
+matches one of the affected libraries.
+
@end table
@item tcatch @var{event}
Disabling and enabling a breakpoint that has multiple locations
affects all of its locations.
-A breakpoint, watchpoint, or catchpoint can have any of four different
-states of enablement:
+A breakpoint, watchpoint, or catchpoint can have any of several
+different states of enablement:
@itemize @bullet
@item
Enabled once. The breakpoint stops your program, but then becomes
disabled.
@item
+Enabled for a count. The breakpoint stops your program for the next
+N times, then becomes disabled.
+@item
Enabled for deletion. The breakpoint stops your program, but
immediately after it does so it is deleted permanently. A breakpoint
set with the @code{tbreak} command starts out in this state.
Enable the specified breakpoints temporarily. @value{GDBN} disables any
of these breakpoints immediately after stopping your program.
+@item enable @r{[}breakpoints@r{]} count @var{count} @var{range}@dots{}
+Enable the specified breakpoints temporarily. @value{GDBN} records
+@var{count} with each of the specified breakpoints, and decrements a
+breakpoint's count when it is hit. When any count reaches 0,
+@value{GDBN} disables that breakpoint. If a breakpoint has an ignore
+count (@pxref{Conditions, ,Break Conditions}), that will be
+decremented to 0 before @var{count} is affected.
+
@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
Enable the specified breakpoints to work once, then die. @value{GDBN}
deletes any of these breakpoints as soon as your program stops there.
purpose of performing side effects when a breakpoint is reached
(@pxref{Break Commands, ,Breakpoint Command Lists}).
+Breakpoint conditions can also be evaluated on the target's side if
+the target supports it. Instead of evaluating the conditions locally,
+@value{GDBN} encodes the expression into an agent expression
+(@pxref{Agent Expressions}) suitable for execution on the target,
+independently of @value{GDBN}. Global variables become raw memory
+locations, locals become stack accesses, and so forth.
+
+In this case, @value{GDBN} will only be notified of a breakpoint trigger
+when its condition evaluates to true. This mechanism may provide faster
+response times depending on the performance characteristics of the target
+since it does not need to keep @value{GDBN} informed about
+every breakpoint trigger, even those with false conditions.
+
Break conditions can be specified when a breakpoint is set, by using
@samp{if} in the arguments to the @code{break} command. @xref{Set
Breaks, ,Setting Breakpoints}. They can also be changed at any time
line. These are all variables (declared either static or automatic)
accessible at the point of execution of the selected frame.
-@kindex info catch
-@cindex catch exceptions, list active handlers
-@cindex exception handlers, how to list
-@item info catch
-Print a list of all the exception handlers that are active in the
-current stack frame at the current point of execution. To see other
-exception handlers, visit the associated frame (using the @code{up},
-@code{down}, or @code{frame} commands); then type @code{info catch}.
-@xref{Set Catchpoints, , Setting Catchpoints}.
-
@end table
@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}.
function calls are the same as normal calls:
@itemize @bullet
-@item
-You cannot set breakpoints on inlined functions. @value{GDBN}
-either reports that there is no symbol with that name, or else sets the
-breakpoint only on non-inlined copies of the function. This limitation
-will be removed in a future version of @value{GDBN}; until then,
-set a breakpoint by line number on the first line of the inlined
-function instead.
-
@item
Setting breakpoints at the call site of an inlined function may not
work, because the call site does not contain any code. @value{GDBN}
@var{typename}.
@xref{Symbols, ,Examining the Symbol Table}.
+@item info vtbl @var{expression}.
+The @code{info vtbl} command can be used to display the virtual
+method tables of the object computed by @var{expression}. This shows
+one entry per virtual table; there may be multiple virtual tables when
+multiple inheritance is in use.
+
@cindex C@t{++} symbol display
@item set print demangle
@itemx show print demangle
which match the regular-expression @var{regexp}.
@end ignore
-@cindex reloading symbols
-Some systems allow individual object files that make up your program to
-be replaced without stopping and restarting your program. For example,
-in VxWorks you can simply recompile a defective object file and keep on
-running. If you are running on one of these systems, you can allow
-@value{GDBN} to reload the symbols for automatically relinked modules:
-
-@table @code
-@kindex set symbol-reloading
-@item set symbol-reloading on
-Replace symbol definitions for the corresponding source file when an
-object file with a particular name is seen again.
-
-@item set symbol-reloading off
-Do not replace symbol definitions when encountering object files of the
-same name more than once. This is the default state; if you are not
-running on a system that permits automatic relinking of modules, you
-should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
-may discard symbols when linking large programs, that may contain
-several modules (from different directories or libraries) with the same
-name.
-
-@kindex show symbol-reloading
-@item show symbol-reloading
-Show the current @code{on} or @code{off} setting.
-@end table
-
@cindex opaque data types
@kindex set opaque-type-resolution
@item set opaque-type-resolution on
@end table
Sometimes you may wish that @value{GDBN} stops and gives you control
-when any of shared library events happen. Use the @code{set
-stop-on-solib-events} command for this:
+when any of shared library events happen. The best way to do this is
+to use @code{catch load} and @code{catch unload} (@pxref{Set
+Catchpoints}).
+
+@value{GDBN} also supports the the @code{set stop-on-solib-events}
+command for this. This command exists for historical reasons. It is
+less useful than setting a catchpoint, because it does not allow for
+conditions or commands as a catchpoint does.
@table @code
@item set stop-on-solib-events
@tab @code{QPassSignals}
@tab @code{handle @var{signal}}
+@item @code{program-signals}
+@tab @code{QProgramSignals}
+@tab @code{handle @var{signal}}
+
@item @code{hostio-close-packet}
@tab @code{vFile:close}
@tab @code{remote get}, @code{remote put}
@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
@item @code{disable-randomization}
@tab @code{QDisableRandomization}
@tab @code{set disable-randomization}
+
+@item @code{conditional-breakpoints-packet}
+@tab @code{Z0 and Z1}
+@tab @code{Support for target-side breakpoint condition evaluation}
@end multitable
@node Remote Stub
@cindex MIPS boards
@value{GDBN} can use the MIPS remote debugging protocol to talk to a
MIPS board attached to a serial line. This is available when
-you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
+you configure @value{GDBN} with @samp{--target=mips-elf}.
@need 1000
Use these @value{GDBN} commands to specify the connection to your target board:
retransmit-timeout @var{seconds}} command. The default is 3 seconds.
You can inspect both values with @code{show timeout} and @code{show
retransmit-timeout}. (These commands are @emph{only} available when
-@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
+@value{GDBN} is configured for @samp{--target=mips-elf}.)
The timeout set by @code{set timeout} does not apply when @value{GDBN}
is waiting for your program to stop. In that case, @value{GDBN} waits
@kindex help user-defined
@item help user-defined
-List all user-defined commands, with the first line of the documentation
-(if any) for each.
+List all user-defined commands and all python commands defined in class
+COMAND_USER. The first line of the documentation or docstring is
+included (if any).
@kindex show user
@item show user
Display the @value{GDBN} commands used to define @var{commandname} (but
not its documentation). If no @var{commandname} is given, display the
definitions for all user-defined commands.
+This does not work for user-defined python commands.
@cindex infinite recursion in user-defined commands
@kindex show max-user-call-depth
The value of @code{max-user-call-depth} controls how many recursion
levels are allowed in user-defined commands before @value{GDBN} suspects an
infinite recursion and aborts the command.
+This does not apply to user-defined python commands.
@end table
In addition to the above commands, user-defined commands frequently
>class HelloWorld (gdb.Command):
> """Greet the whole world."""
> def __init__ (self):
-> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
+> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
> def invoke (self, args, from_tty):
> argv = gdb.string_to_argv (args)
> if len (argv) != 0:
The result @code{bar} will be a @code{gdb.Value} object holding the
value pointed to by @code{foo}.
+
+A similar function @code{Value.referenced_value} exists which also
+returns @code{gdb.Value} objects corresonding to the values pointed to
+by pointer values (and additionally, values referenced by reference
+values). However, the behavior of @code{Value.dereference}
+differs from @code{Value.referenced_value} by the fact that the
+behavior of @code{Value.dereference} is identical to applying the C
+unary operator @code{*} on a given value. For example, consider a
+reference to a pointer @code{ptrref}, declared in your C@t{++} program
+as
+
+@smallexample
+typedef int *intptr;
+...
+int val = 10;
+intptr ptr = &val;
+intptr &ptrref = ptr;
+@end smallexample
+
+Though @code{ptrref} is a reference value, one can apply the method
+@code{Value.dereference} to the @code{gdb.Value} object corresponding
+to it and obtain a @code{gdb.Value} which is identical to that
+corresponding to @code{val}. However, if you apply the method
+@code{Value.referenced_value}, the result would be a @code{gdb.Value}
+object identical to that corresponding to @code{ptr}.
+
+@smallexample
+py_ptrref = gdb.parse_and_eval ("ptrref")
+py_val = py_ptrref.dereference ()
+py_ptr = py_ptrref.referenced_value ()
+@end smallexample
+
+The @code{gdb.Value} object @code{py_val} is identical to that
+corresponding to @code{val}, and @code{py_ptr} is identical to that
+corresponding to @code{ptr}. In general, @code{Value.dereference} can
+be applied whenever the C unary operator @code{*} can be applied
+to the corresponding C value. For those cases where applying both
+@code{Value.dereference} and @code{Value.referenced_value} is allowed,
+the results obtained need not be identical (as we have seen in the above
+example). The results are however identical when applied on
+@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
+objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
+@end defun
+
+@defun Value.referenced_value ()
+For pointer or reference data types, this method returns a new
+@code{gdb.Value} object corresponding to the value referenced by the
+pointer/reference value. For pointer data types,
+@code{Value.dereference} and @code{Value.referenced_value} produce
+identical results. The difference between these methods is that
+@code{Value.dereference} cannot get the values referenced by reference
+values. For example, consider a reference to an @code{int}, declared
+in your C@t{++} program as
+
+@smallexample
+int val = 10;
+int &ref = val;
+@end smallexample
+
+@noindent
+then applying @code{Value.dereference} to the @code{gdb.Value} object
+corresponding to @code{ref} will result in an error, while applying
+@code{Value.referenced_value} will result in a @code{gdb.Value} object
+identical to that corresponding to @code{val}.
+
+@smallexample
+py_ref = gdb.parse_and_eval ("ref")
+er_ref = py_ref.dereference () # Results in error
+py_val = py_ref.referenced_value () # Returns the referenced value
+@end smallexample
+
+The @code{gdb.Value} object @code{py_val} is identical to that
+corresponding to @code{val}.
@end defun
@defun Value.dynamic_cast (type)
@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
commands in this category.
+@findex COMMAND_USER
+@findex gdb.COMMAND_USER
+@item gdb.COMMAND_USER
+The command is a general purpose command for the user, and typically
+does not fit in one of the other categories.
+Type @kbd{help user-defined} at the @value{GDBN} prompt to see
+a list of commands in this category, as well as the list of gdb macros
+(@pxref{Sequences}).
+
@findex COMMAND_OBSCURE
@findex gdb.COMMAND_OBSCURE
@item gdb.COMMAND_OBSCURE
"""Greet the whole world."""
def __init__ (self):
- super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
+ super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
def invoke (self, arg, from_tty):
print "Hello, World!"
detailed technical information on @value{GDBN}'s book-keeping of the
stack.
+A @code{gdb.Block} is iterable. The iterator returns the symbols
+(@pxref{Symbols In Python}) local to the block.
+
The following block-related functions are available in the @code{gdb}
module:
@code{False} if not. A block object can become invalid if the block it
refers to doesn't exist anymore in the inferior. All other
@code{gdb.Block} methods will throw an exception if it is invalid at
-the time the method is called. This method is also made available to
-the Python iterator object that @code{gdb.Block} provides in an iteration
-context and via the Python @code{iter} built-in function.
+the time the method is called. The block's validity is also checked
+during iteration over symbols of the block.
@end defun
@end table
Python}. This attribute is not writable.
@end defvar
+@defvar Symbol.line
+The line number in the source code at which the symbol was defined.
+This is an integer.
+@end defvar
+
@defvar Symbol.name
The name of the symbol as a string. This attribute is not writable.
@end defvar
@code{gdb} module and described later in this chapter.
@end defvar
+@defvar Symbol.needs_frame
+This is @code{True} if evaluating this symbol's value requires a frame
+(@pxref{Frames In Python}) and @code{False} otherwise. Typically,
+local variables will require a frame, but other symbols will not.
+@end defvar
+
@defvar Symbol.is_argument
@code{True} if the symbol is an argument of a function.
@end defvar
All other @code{gdb.Symbol} methods will throw an exception if it is
invalid at the time the method is called.
@end defun
+
+@defun Symbol.value (@r{[}frame@r{]})
+Compute the value of the symbol, as a @code{gdb.Value}. For
+functions, this computes the address of the function, cast to the
+appropriate type. If the symbol requires a frame in order to compute
+its value, then @var{frame} must be given. If @var{frame} is not
+given, or if @var{frame} is invalid, then this method will throw an
+exception.
+@end defun
@end table
The available domain categories in @code{gdb.Symbol} are represented
When a new object file is read (for example, due to the @code{file}
command, or because the inferior has loaded a shared library),
@value{GDBN} will look for Python support scripts in several ways:
-@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
-
-@menu
-* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
-* .debug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
-* Which flavor to choose?::
-@end menu
+@file{@var{objfile}-gdb.py} (@pxref{objfile-gdb.py file})
+and @code{.debug_gdb_scripts} section
+(@pxref{dotdebug_gdb_scripts section}).
The auto-loading feature is useful for supplying application-specific
debugging commands and scripts.
Also printed is the list of scripts that were mentioned in
the @code{.debug_gdb_scripts} section and were not found
-(@pxref{.debug_gdb_scripts section}).
+(@pxref{dotdebug_gdb_scripts section}).
This is useful because their names are not printed when @value{GDBN}
tries to load them and fails. There may be many of them, and printing
an error message for each one is problematic.
function (@pxref{Objfiles In Python}). This can be useful for
registering objfile-specific pretty-printers.
+@menu
+* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
+* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
+* Which flavor to choose?::
+@end menu
+
@node objfile-gdb.py file
@subsubsection The @file{@var{objfile}-gdb.py} file
@cindex @file{@var{objfile}-gdb.py}
directories mentioned in the value of @code{debug-file-directory}.
Finally, if this file does not exist, then @value{GDBN} will look for
-a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where
+a file named @file{@var{data-directory}/auto-load/@var{real-name}}, where
@var{data-directory} is @value{GDBN}'s data directory (available via
@code{show data-directory}, @pxref{Data Files}), and @var{real-name}
is the object file's real name, as described above.
So your @file{-gdb.py} file should be careful to avoid errors if it
is evaluated more than once.
-@node .debug_gdb_scripts section
+@node dotdebug_gdb_scripts section
@subsubsection The @code{.debug_gdb_scripts} section
@cindex @code{.debug_gdb_scripts} section
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.
+This can happen when @code{stop-on-solib-events} (@pxref{Files}) is
+set or when a @code{catch load} or @code{catch unload} catchpoint is
+in use (@pxref{Set Catchpoints}).
@item fork
The inferior has forked. This is reported when @code{catch fork}
(@pxref{Set Catchpoints}) has been used.
changed, then this will be the string @samp{true}; otherwise it will
be @samp{false}.
+When a varobj's type changes, its children are also likely to have
+become incorrect. Therefore, the varobj's children are automatically
+deleted when this attribute is @samp{true}. Also, the varobj's update
+range, when set using the @code{-var-set-update-range} command, is
+unset.
+
@item new_type
If the varobj's type changed, then this field will be present and will
hold the new type.
frame. Both have a callback (@code{target_read}) to read bytes off the
target's address space.
+@node In-Process Agent
+@chapter In-Process Agent
+@cindex debugging agent
+The traditional debugging model is conceptually low-speed, but works fine,
+because most bugs can be reproduced in debugging-mode execution. However,
+as multi-core or many-core processors are becoming mainstream, and
+multi-threaded programs become more and more popular, there should be more
+and more bugs that only manifest themselves at normal-mode execution, for
+example, thread races, because debugger's interference with the program's
+timing may conceal the bugs. On the other hand, 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 fail, even when the
+code itself is correct. It is useful to be able to observe the program's
+behavior without interrupting it.
+
+Therefore, traditional debugging model is too intrusive to reproduce
+some bugs. In order to reduce the interference with the program, we can
+reduce the number of operations performed by debugger. The
+@dfn{In-Process Agent}, a shared library, is running within the same
+process with inferior, and is able to perform some debugging operations
+itself. As a result, debugger is only involved when necessary, and
+performance of debugging can be improved accordingly. Note that
+interference with program can be reduced but can't be removed completely,
+because the in-process agent will still stop or slow down the program.
+
+The in-process agent can interpret and execute Agent Expressions
+(@pxref{Agent Expressions}) during performing debugging operations. The
+agent expressions can be used for different purposes, such as collecting
+data in tracepoints, and condition evaluation in breakpoints.
+
+@anchor{Control Agent}
+You can control whether the in-process agent is used as an aid for
+debugging with the following commands:
+
+@table @code
+@kindex set agent on
+@item set agent on
+Causes the in-process agent to perform some operations on behalf of the
+debugger. Just which operations requested by the user will be done
+by the in-process agent depends on the its capabilities. For example,
+if you request to evaluate breakpoint conditions in the in-process agent,
+and the in-process agent has such capability as well, then breakpoint
+conditions will be evaluated in the in-process agent.
+
+@kindex set agent off
+@item set agent off
+Disables execution of debugging operations by the in-process agent. All
+of the operations will be performed by @value{GDBN}.
+
+@kindex show agent
+@item show agent
+Display the current setting of execution of debugging operations by
+the in-process agent.
+@end table
+
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
@cindex bugs in @value{GDBN}
matching @var{regexp}.
For each script, this command prints its name as specified in the objfile,
and the full path if known.
-@xref{.debug_gdb_scripts section}.
+@xref{dotdebug_gdb_scripts section}.
@kindex maint print statistics
@cindex bcache statistics
signal @samp{0}, regardless of whether the target uses some other signal
as an implementation detail.
+The stub must support @samp{vCont} if it reports support for
+multiprocess extensions (@pxref{multiprocess extensions}). Note that in
+this case @samp{vCont} actions can be specified to apply to all threads
+in a process by using the @samp{p@var{pid}.-1} form of the
+@var{thread-id}.
+
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
stub is allowed to delay erase operation until the @samp{vFlashDone}
packet is received.
-The stub must support @samp{vCont} if it reports support for
-multiprocess extensions (@pxref{multiprocess extensions}). Note that in
-this case @samp{vCont} actions can be specified to apply to all threads
-in a process by using the @samp{p@var{pid}.-1} form of the
-@var{thread-id}.
-
Reply:
@table @samp
@item OK
be implemented in an idempotent way.}
@item z0,@var{addr},@var{kind}
-@itemx Z0,@var{addr},@var{kind}
+@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}
@cindex @samp{z0} packet
@cindex @samp{Z0} packet
Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
the breakpoint in bytes that should be inserted. E.g., the @sc{arm}
and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
architectures have additional meanings for @var{kind};
+@var{cond_list} is an optional list of conditional expressions in bytecode
+form that should be evaluated on the target's side. These are the
+conditions that should be taken into consideration when deciding if
+the breakpoint trigger should be reported back to @var{GDBN}.
+
+The @var{cond_list} parameter is comprised of a series of expressions,
+concatenated without separators. Each expression has the following form:
+
+@table @samp
+
+@item X @var{len},@var{expr}
+@var{len} is the length of the bytecode expression and @var{expr} is the
+actual conditional expression in bytecode form.
+
+@end table
+
see @ref{Architecture-Specific Protocol Details}.
@emph{Implementation note: It is possible for a target to copy or move
@end table
@item z1,@var{addr},@var{kind}
-@itemx Z1,@var{addr},@var{kind}
+@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}
@cindex @samp{z1} packet
@cindex @samp{Z1} packet
Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
A hardware breakpoint is implemented using a mechanism that is not
dependant on being able to modify the target's memory. @var{kind}
-has the same meaning as in @samp{Z0} packets.
+and @var{cond_list} have the same meaning as in @samp{Z0} packets.
@emph{Implementation note: A hardware breakpoint is not affected by code
movement.}
@table @samp
+@item QAgent:1
+@item QAgent:0
+Turn on or off the agent as a helper to perform some debugging operations
+delegated from @value{GDBN} (@pxref{Control Agent}).
+
@item QAllow:@var{op}:@var{val}@dots{}
@cindex @samp{QAllow} packet
Specify which operations @value{GDBN} expects to request of the
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item QProgramSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
+@cindex signals the inferior may see, remote request
+@cindex @samp{QProgramSignals} packet
+@anchor{QProgramSignals}
+Each listed @var{signal} may be delivered to the inferior process.
+Others should be silently discarded.
+
+In some cases, the remote stub may need to decide whether to deliver a
+signal to the program or not without @value{GDBN} involvement. One
+example of that is while detaching --- the program's threads may have
+stopped for signals that haven't yet had a chance of being reported to
+@value{GDBN}, and so the remote stub can use the signal list specified
+by this packet to know whether to deliver or ignore those pending
+signals.
+
+This does not influence whether to deliver a signal as requested by a
+resumption packet (@pxref{vCont packet}).
+
+Signals are numbered identically to continue packets and stop replies
+(@pxref{Stop Reply Packets}). Each @var{signal} list item should be
+strictly greater than the previous item. Multiple
+@samp{QProgramSignals} packets do not combine; any earlier
+@samp{QProgramSignals} list is completely replaced by the new list.
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. @var{nn} are hex digits.
+
+@item
+An empty reply indicates that @samp{QProgramSignals} is not supported
+by the stub.
+@end table
+
+Use of this packet is controlled by the @code{set remote program-signals}
+command (@pxref{Remote Configuration, set remote program-signals}).
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qRcmd,@var{command}
@cindex execute remote command, remote request
@cindex @samp{qRcmd} packet
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:uib:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:fdpic:read}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{ConditionalBreakpoints}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{ConditionalTracepoints}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{QAgent}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{QAllow}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:traceframe-info:read}
packet (@pxref{qXfer traceframe info read}).
+@item qXfer:uib:read
+The remote stub understands the @samp{qXfer:uib:read}
+packet (@pxref{qXfer unwind info block}).
+
@item qXfer:fdpic:read
The remote stub understands the @samp{qXfer:fdpic:read}
packet (@pxref{qXfer fdpic loadmap read}).
The remote stub understands the @samp{qXfer:osdata:read} packet
((@pxref{qXfer osdata read}).
+@item ConditionalBreakpoints
+The target accepts and implements evaluation of conditional expressions
+defined for breakpoints. The target will only report breakpoint triggers
+when such conditions are true (@pxref{Conditions, ,Break Conditions}).
+
@item ConditionalTracepoints
The remote stub accepts and implements conditional expressions defined
for tracepoints (@pxref{Tracepoint Conditions}).
The remote stub understands the @samp{QTDPsrc} packet that supplies
the source form of tracepoint definitions.
+@item QAgent
+The remote stub understands the @samp{QAgent} packet.
+
@item QAllow
The remote stub understands the @samp{QAllow} packet.
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:uib:read:@var{pc}:@var{offset},@var{length}
+@anchor{qXfer unwind info block}
+
+Return the unwind information block for @var{pc}. This packet is used
+on OpenVMS/ia64 to ask the kernel unwind information.
+
+This packet is not probed by default.
+
@item qXfer:fdpic:read:@var{annex}:@var{offset},@var{length}
@anchor{qXfer fdpic loadmap read}
Read contents of @code{loadmap}s on the target system. The
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
contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and
@samp{fir}. They may be 32-bit or 64-bit depending on the target.
+The @samp{org.gnu.gdb.mips.dsp} feature is optional. It should
+contain registers @samp{hi1} through @samp{hi3}, @samp{lo1} through
+@samp{lo3}, and @samp{dspctl}. The @samp{dspctl} register should
+be 32-bit and the rest may be 32-bit or 64-bit depending on the target.
+
The @samp{org.gnu.gdb.mips.linux} feature is optional. It should
contain a single register, @samp{restart}, which is used by the
Linux kernel to control restartable syscalls.
@enumerate
@item
-The version number, currently 5. Versions 1, 2 and 3 are obsolete.
-Version 4 differs by its hashing function.
+The version number, currently 6. Versions 1, 2 and 3 are obsolete.
+Version 4 uses a different hashing function from versions 5 and 6.
+Version 6 includes symbols for inlined functions, whereas versions
+4 and 5 do not. @value{GDBN} will only read version 4 and 5 indices
+if the @code{--use-deprecated-index-sections} option is used.
@item
The offset, from the start of the file, of the CU list.
@item Version 4
The formula is @code{r = r * 67 + c - 113}.
-@item Version 5
+@item Versions 5 and 6
The formula is @code{r = r * 67 + tolower (c) - 113}.
@end table
projects / binutils-gdb.git / blobdiff