| Index: gdb/doc/gdb.texinfo
|
| diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
|
| index a404d42396b44e7bd63daa7aaf824c68cb45c384..7dfa9f671a52eb6dc293bed2ac7686414dbb57b1 100644
|
| --- a/gdb/doc/gdb.texinfo
|
| +++ b/gdb/doc/gdb.texinfo
|
| @@ -1,12 +1,14 @@
|
| \input texinfo @c -*-texinfo-*-
|
| -@c Copyright (C) 1988-1996, 1998-2012 Free Software Foundation, Inc.
|
| +@c Copyright (C) 1988-2013 Free Software Foundation, Inc.
|
| @c
|
| @c %**start of header
|
| @c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
|
| @c of @set vars. However, you can override filename with makeinfo -o.
|
| @setfilename gdb.info
|
| @c
|
| +@c man begin INCLUDE
|
| @include gdb-cfg.texi
|
| +@c man end
|
| @c
|
| @settitle Debugging with @value{GDBN}
|
| @setchapternewpage odd
|
| @@ -28,7 +30,6 @@
|
| @c readline appendices use @vindex, @findex and @ftable,
|
| @c annotate.texi and gdbmi use @findex.
|
| @syncodeindex vr fn
|
| -@syncodeindex fn fn
|
|
|
| @c !!set GDB manual's edition---not the same as GDB version!
|
| @c This is updated by GNU Press.
|
| @@ -44,13 +45,12 @@
|
| @dircategory Software development
|
| @direntry
|
| * Gdb: (gdb). The GNU debugger.
|
| +* gdbserver: (gdb) Server. The GNU debugging server.
|
| @end direntry
|
|
|
| @copying
|
| -Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
| -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
|
| -2011, 2012
|
| -Free Software Foundation, Inc.
|
| +@c man begin COPYRIGHT
|
| +Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
|
|
|
| Permission is granted to copy, distribute and/or modify this document
|
| under the terms of the GNU Free Documentation License, Version 1.3 or
|
| @@ -62,6 +62,7 @@ and with the Back-Cover Texts as in (a) below.
|
| (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
|
| this GNU Manual. Buying copies from GNU Press supports the FSF in
|
| developing GNU and promoting software freedom.''
|
| +@c man end
|
| @end copying
|
|
|
| @ifnottex
|
| @@ -119,7 +120,7 @@ This is the @value{EDITION} Edition, for @value{GDBN}
|
| @end ifset
|
| Version @value{GDBVN}.
|
|
|
| -Copyright (C) 1988-2012 Free Software Foundation, Inc.
|
| +Copyright (C) 1988-2013 Free Software Foundation, Inc.
|
|
|
| This edition of the GDB manual is dedicated to the memory of Fred
|
| Fish. Fred was a long-standing contributor to GDB and to Free
|
| @@ -183,6 +184,7 @@ software in general. We will miss him.
|
| the operating system
|
| * Trace File Format:: GDB trace file format
|
| * Index Section Format:: .gdb_index section format
|
| +* Man Pages:: Manual pages
|
| * Copying:: GNU General Public License says
|
| how you can copy and share GDB
|
| * GNU Free Documentation License:: The license for this documentation
|
| @@ -1043,10 +1045,37 @@ batch mode or quiet mode.
|
| @itemx -n
|
| @cindex @code{--nx}
|
| @cindex @code{-n}
|
| -Do not execute commands found in any initialization files. Normally,
|
| -@value{GDBN} executes the commands in these files after all the command
|
| -options and arguments have been processed. @xref{Command Files,,Command
|
| -Files}.
|
| +Do not execute commands found in any initialization file.
|
| +There are three init files, loaded in the following order:
|
| +
|
| +@table @code
|
| +@item @file{system.gdbinit}
|
| +This is the system-wide init file.
|
| +Its location is specified with the @code{--with-system-gdbinit}
|
| +configure option (@pxref{System-wide configuration}).
|
| +It is loaded first when @value{GDBN} starts, before command line options
|
| +have been processed.
|
| +@item @file{~/.gdbinit}
|
| +This is the init file in your home directory.
|
| +It is loaded next, after @file{system.gdbinit}, and before
|
| +command options have been processed.
|
| +@item @file{./.gdbinit}
|
| +This is the init file in the current directory.
|
| +It is loaded last, after command line options other than @code{-x} and
|
| +@code{-ex} have been processed. Command line options @code{-x} and
|
| +@code{-ex} are processed last, after @file{./.gdbinit} has been loaded.
|
| +@end table
|
| +
|
| +For further documentation on startup processing, @xref{Startup}.
|
| +For documentation on how to write command files,
|
| +@xref{Command Files,,Command Files}.
|
| +
|
| +@anchor{-nh}
|
| +@item -nh
|
| +@cindex @code{--nh}
|
| +Do not execute commands found in @file{~/.gdbinit}, the init file
|
| +in your home directory.
|
| +@xref{Startup}.
|
|
|
| @item -quiet
|
| @itemx -silent
|
| @@ -1154,13 +1183,6 @@ and a newline. The Emacs-to-@value{GDBN} interface program uses the two
|
| @samp{\032} characters as a signal to display the source code for the
|
| frame.
|
|
|
| -@item -epoch
|
| -@cindex @code{--epoch}
|
| -The Epoch Emacs-@value{GDBN} interface sets this option when it runs
|
| -@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print
|
| -routines so as to allow Epoch to display values of expressions in a
|
| -separate window.
|
| -
|
| @item -annotate @var{level}
|
| @cindex @code{--annotate}
|
| This option sets the @dfn{annotation level} inside @value{GDBN}. Its
|
| @@ -1247,6 +1269,12 @@ memory usage after it completes each command and returns to the prompt.
|
| This option causes @value{GDBN} to print its version number and
|
| no-warranty blurb, and exit.
|
|
|
| +@item -configuration
|
| +@cindex @code{--configuration}
|
| +This option causes @value{GDBN} to print details about its build-time
|
| +configuration parameters, and then exit. These details can be
|
| +important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}).
|
| +
|
| @end table
|
|
|
| @node Startup
|
| @@ -1339,9 +1367,9 @@ can use @kbd{gdb --help}.
|
| The @value{GDBN} init files are normally called @file{.gdbinit}.
|
| The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
|
| the limitations of file names imposed by DOS filesystems. The Windows
|
| -ports of @value{GDBN} use the standard name, but if they find a
|
| -@file{gdb.ini} file, they warn you about that and suggest to rename
|
| -the file to the standard name.
|
| +port of @value{GDBN} uses the standard name, but if it finds a
|
| +@file{gdb.ini} file in your home directory, it warns you about that
|
| +and suggests to rename the file to the standard name.
|
|
|
|
|
| @node Quitting GDB
|
| @@ -1820,7 +1848,7 @@ values, you can use @code{show} with no arguments; you may also use
|
| @end table
|
| @c @end group
|
|
|
| -Here are three miscellaneous @code{show} subcommands, all of which are
|
| +Here are several miscellaneous @code{show} subcommands, all of which are
|
| exceptional in lacking corresponding @code{set} commands:
|
|
|
| @table @code
|
| @@ -1851,6 +1879,15 @@ Display information about permission for copying @value{GDBN}.
|
| Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
|
| if your version of @value{GDBN} comes with one.
|
|
|
| +@kindex show configuration
|
| +@item show configuration
|
| +Display detailed information about the way @value{GDBN} was configured
|
| +when it was built. This displays the optional arguments passed to the
|
| +@file{configure} script and also configuration parameters detected
|
| +automatically by @command{configure}. When reporting a @value{GDBN}
|
| +bug (@pxref{GDB Bugs}), it is important to include this information in
|
| +your report.
|
| +
|
| @end table
|
|
|
| @node Running
|
| @@ -1975,8 +2012,10 @@ is used to pass the arguments, so that you may use normal conventions
|
| (such as wildcard expansion or variable substitution) in describing
|
| the arguments.
|
| In Unix systems, you can control which shell is used with the
|
| -@code{SHELL} environment variable.
|
| -@xref{Arguments, ,Your Program's Arguments}.
|
| +@code{SHELL} environment variable. If you do not define @code{SHELL},
|
| +@value{GDBN} uses the default shell (@file{/bin/sh}). You can disable
|
| +use of any shell with the @code{set startup-with-shell} command (see
|
| +below for details).
|
|
|
| @item The @emph{environment.}
|
| Your program normally inherits its environment from @value{GDBN}, but you can
|
| @@ -2079,6 +2118,33 @@ environment:
|
| This command is available when debugging locally on most targets, excluding
|
| @sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
|
|
|
| +@kindex set startup-with-shell
|
| +@item set startup-with-shell
|
| +@itemx set startup-with-shell on
|
| +@itemx set startup-with-shell off
|
| +@itemx show set startup-with-shell
|
| +On Unix systems, by default, if a shell is available on your target,
|
| +@value{GDBN}) uses it to start your program. Arguments of the
|
| +@code{run} command are passed to the shell, which does variable
|
| +substitution, expands wildcard characters and performs redirection of
|
| +I/O. In some circumstances, it may be useful to disable such use of a
|
| +shell, for example, when debugging the shell itself or diagnosing
|
| +startup failures such as:
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) run
|
| +Starting program: ./a.out
|
| +During startup program terminated with signal SIGSEGV, Segmentation fault.
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +which indicates the shell or the wrapper specified with
|
| +@samp{exec-wrapper} crashed, not your program. Most often, this is
|
| +caused by something odd in your shell's non-interactive mode
|
| +initialization file---such as @file{.cshrc} for C-shell,
|
| +$@file{.zshenv} for the Z shell, or the file specified in the
|
| +@samp{BASH_ENV} environment variable for BASH.
|
| +
|
| @kindex set disable-randomization
|
| @item set disable-randomization
|
| @itemx set disable-randomization on
|
| @@ -2241,14 +2307,15 @@ rather than assigning it an empty value.
|
| @end table
|
|
|
| @emph{Warning:} On Unix systems, @value{GDBN} runs your program using
|
| -the shell indicated
|
| -by your @code{SHELL} environment variable if it exists (or
|
| -@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
|
| -that runs an initialization file---such as @file{.cshrc} for C-shell, or
|
| -@file{.bashrc} for BASH---any variables you set in that file affect
|
| -your program. You may wish to move setting of environment variables to
|
| -files that are only run when you sign on, such as @file{.login} or
|
| -@file{.profile}.
|
| +the shell indicated by your @code{SHELL} environment variable if it
|
| +exists (or @code{/bin/sh} if not). If your @code{SHELL} variable
|
| +names a shell that runs an initialization file when started
|
| +non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv}
|
| +for the Z shell, or the file specified in the @samp{BASH_ENV}
|
| +environment variable for BASH---any variables you set in that file
|
| +affect your program. You may wish to move setting of environment
|
| +variables to files that are only run when you sign on, such as
|
| +@file{.login} or @file{.profile}.
|
|
|
| @node Working Directory
|
| @section Your Program's Working Directory
|
| @@ -2267,8 +2334,9 @@ Specify Files}.
|
| @table @code
|
| @kindex cd
|
| @cindex change working directory
|
| -@item cd @var{directory}
|
| -Set the @value{GDBN} working directory to @var{directory}.
|
| +@item cd @r{[}@var{directory}@r{]}
|
| +Set the @value{GDBN} working directory to @var{directory}. If not
|
| +given, @var{directory} uses @file{'~'}.
|
|
|
| @kindex pwd
|
| @item pwd
|
| @@ -4035,15 +4103,72 @@ shared library. Use the @code{catch} command to set a catchpoint.
|
| @kindex catch
|
| @item catch @var{event}
|
| Stop when @var{event} occurs. @var{event} can be any of the following:
|
| +
|
| @table @code
|
| -@item throw
|
| +@item throw @r{[}@var{regexp}@r{]}
|
| +@itemx rethrow @r{[}@var{regexp}@r{]}
|
| +@itemx catch @r{[}@var{regexp}@r{]}
|
| +@kindex catch throw
|
| +@kindex catch rethrow
|
| +@kindex catch catch
|
| @cindex stop on C@t{++} exceptions
|
| -The throwing of a C@t{++} exception.
|
| +The throwing, re-throwing, or catching of a C@t{++} exception.
|
| +
|
| +If @var{regexp} is given, then only exceptions whose type matches the
|
| +regular expression will be caught.
|
|
|
| -@item catch
|
| -The catching of a C@t{++} exception.
|
| +@vindex $_exception@r{, convenience variable}
|
| +The convenience variable @code{$_exception} is available at an
|
| +exception-related catchpoint, on some systems. This holds the
|
| +exception being thrown.
|
| +
|
| +There are currently some limitations to C@t{++} exception handling in
|
| +@value{GDBN}:
|
| +
|
| +@itemize @bullet
|
| +@item
|
| +The support for these commands is system-dependent. Currently, only
|
| +systems using the @samp{gnu-v3} C@t{++} ABI (@pxref{ABI}) are
|
| +supported.
|
| +
|
| +@item
|
| +The regular expression feature and the @code{$_exception} convenience
|
| +variable rely on the presence of some SDT probes in @code{libstdc++}.
|
| +If these probes are not present, then these features cannot be used.
|
| +These probes were first available in the GCC 4.8 release, but whether
|
| +or not they are available in your GCC also depends on how it was
|
| +built.
|
| +
|
| +@item
|
| +The @code{$_exception} convenience variable is only valid at the
|
| +instruction at which an exception-related catchpoint is set.
|
| +
|
| +@item
|
| +When an exception-related catchpoint is hit, @value{GDBN} stops at a
|
| +location in the system library which implements runtime exception
|
| +support for C@t{++}, usually @code{libstdc++}. You can use @code{up}
|
| +(@pxref{Selection}) to get to your code.
|
| +
|
| +@item
|
| +If you call a function interactively, @value{GDBN} normally returns
|
| +control to you when the function has finished executing. If the call
|
| +raises an exception, however, the call may bypass the mechanism that
|
| +returns control to you and cause your program either to abort or to
|
| +simply continue running until it hits a breakpoint, catches a signal
|
| +that @value{GDBN} is listening for, or exits. This is the case even if
|
| +you set a catchpoint for the exception; catchpoints on exceptions are
|
| +disabled within interactive calls. @xref{Calling}, for information on
|
| +controlling this with @code{set unwind-on-terminating-exception}.
|
| +
|
| +@item
|
| +You cannot raise an exception interactively.
|
| +
|
| +@item
|
| +You cannot install an exception handler interactively.
|
| +@end itemize
|
|
|
| @item exception
|
| +@kindex catch exception
|
| @cindex Ada exception catching
|
| @cindex catch Ada exceptions
|
| An Ada exception being raised. If an exception name is specified
|
| @@ -4061,18 +4186,22 @@ the command to use to catch such exceptions is @kbd{catch exception
|
| Pck.Constraint_Error}.
|
|
|
| @item exception unhandled
|
| +@kindex catch exception unhandled
|
| An exception that was raised but is not handled by the program.
|
|
|
| @item assert
|
| +@kindex catch assert
|
| A failed Ada assertion.
|
|
|
| @item exec
|
| +@kindex catch exec
|
| @cindex break on fork/exec
|
| A call to @code{exec}. This is currently only available for HP-UX
|
| and @sc{gnu}/Linux.
|
|
|
| @item syscall
|
| @itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
|
| +@kindex catch syscall
|
| @cindex break on a system call.
|
| A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
|
| syscall is a mechanism for application programs to request a service
|
| @@ -4203,79 +4332,59 @@ Catchpoint 1 (syscall(s) 252)
|
| Again, in this case @value{GDBN} would not be able to display syscall's names.
|
|
|
| @item fork
|
| +@kindex catch fork
|
| A call to @code{fork}. This is currently only available for HP-UX
|
| and @sc{gnu}/Linux.
|
|
|
| @item vfork
|
| +@kindex catch vfork
|
| 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{]}
|
| +@kindex catch load
|
| +@kindex catch unload
|
| 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}
|
| -Set a catchpoint that is enabled only for one stop. The catchpoint is
|
| -automatically deleted after the first time the event is caught.
|
| -
|
| -@end table
|
| +@item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
|
| +@kindex catch signal
|
| +The delivery of a signal.
|
|
|
| -Use the @code{info break} command to list the current catchpoints.
|
| +With no arguments, this catchpoint will catch any signal that is not
|
| +used internally by @value{GDBN}, specifically, all signals except
|
| +@samp{SIGTRAP} and @samp{SIGINT}.
|
|
|
| -There are currently some limitations to C@t{++} exception handling
|
| -(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
|
| +With the argument @samp{all}, all signals, including those used by
|
| +@value{GDBN}, will be caught. This argument cannot be used with other
|
| +signal names.
|
|
|
| -@itemize @bullet
|
| -@item
|
| -If you call a function interactively, @value{GDBN} normally returns
|
| -control to you when the function has finished executing. If the call
|
| -raises an exception, however, the call may bypass the mechanism that
|
| -returns control to you and cause your program either to abort or to
|
| -simply continue running until it hits a breakpoint, catches a signal
|
| -that @value{GDBN} is listening for, or exits. This is the case even if
|
| -you set a catchpoint for the exception; catchpoints on exceptions are
|
| -disabled within interactive calls.
|
| +Otherwise, the arguments are a list of signal names as given to
|
| +@code{handle} (@pxref{Signals}). Only signals specified in this list
|
| +will be caught.
|
|
|
| -@item
|
| -You cannot raise an exception interactively.
|
| +One reason that @code{catch signal} can be more useful than
|
| +@code{handle} is that you can attach commands and conditions to the
|
| +catchpoint.
|
|
|
| -@item
|
| -You cannot install an exception handler interactively.
|
| -@end itemize
|
| +When a signal is caught by a catchpoint, the signal's @code{stop} and
|
| +@code{print} settings, as specified by @code{handle}, are ignored.
|
| +However, whether the signal is still delivered to the inferior depends
|
| +on the @code{pass} setting; this can be changed in the catchpoint's
|
| +commands.
|
|
|
| -@cindex raise exceptions
|
| -Sometimes @code{catch} is not the best way to debug exception handling:
|
| -if you need to know exactly where an exception is raised, it is better to
|
| -stop @emph{before} the exception handler is called, since that way you
|
| -can see the stack before any unwinding takes place. If you set a
|
| -breakpoint in an exception handler instead, it may not be easy to find
|
| -out where the exception was raised.
|
| +@end table
|
|
|
| -To stop just before an exception handler is called, you need some
|
| -knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are
|
| -raised by calling a library function named @code{__raise_exception}
|
| -which has the following ANSI C interface:
|
| +@item tcatch @var{event}
|
| +@kindex tcatch
|
| +Set a catchpoint that is enabled only for one stop. The catchpoint is
|
| +automatically deleted after the first time the event is caught.
|
|
|
| -@smallexample
|
| - /* @var{addr} is where the exception identifier is stored.
|
| - @var{id} is the exception identifier. */
|
| - void __raise_exception (void **addr, void *id);
|
| -@end smallexample
|
| +@end table
|
|
|
| -@noindent
|
| -To make the debugger catch all exceptions before any stack
|
| -unwinding takes place, set a breakpoint on @code{__raise_exception}
|
| -(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}).
|
| -
|
| -With a conditional breakpoint (@pxref{Conditions, ,Break Conditions})
|
| -that depends on the value of @var{id}, you can stop your program when
|
| -a specific exception is raised. You can use multiple conditional
|
| -breakpoints to stop your program when any of a number of exceptions are
|
| -raised.
|
| +Use the @code{info break} command to list the current catchpoints.
|
|
|
|
|
| @node Delete Breaks
|
| @@ -5155,6 +5264,38 @@ Execute one machine instruction, but if it is a function call,
|
| proceed until the function returns.
|
|
|
| An argument is a repeat count, as in @code{next}.
|
| +
|
| +@end table
|
| +
|
| +@anchor{range stepping}
|
| +@cindex range stepping
|
| +@cindex target-assisted range stepping
|
| +By default, and if available, @value{GDBN} makes use of
|
| +target-assisted @dfn{range stepping}. In other words, whenever you
|
| +use a stepping command (e.g., @code{step}, @code{next}), @value{GDBN}
|
| +tells the target to step the corresponding range of instruction
|
| +addresses instead of issuing multiple single-steps. This speeds up
|
| +line stepping, particularly for remote targets. Ideally, there should
|
| +be no reason you would want to turn range stepping off. However, it's
|
| +possible that a bug in the debug info, a bug in the remote stub (for
|
| +remote targets), or even a bug in @value{GDBN} could make line
|
| +stepping behave incorrectly when target-assisted range stepping is
|
| +enabled. You can use the following command to turn off range stepping
|
| +if necessary:
|
| +
|
| +@table @code
|
| +@kindex set range-stepping
|
| +@kindex show range-stepping
|
| +@item set range-stepping
|
| +@itemx show range-stepping
|
| +Control whether range stepping is enabled.
|
| +
|
| +If @code{on}, and the target supports it, @value{GDBN} tells the
|
| +target to step a range of addresses itself, instead of issuing
|
| +multiple single-steps. If @code{off}, @value{GDBN} always issues
|
| +single-steps, even if range stepping is supported by the target. The
|
| +default is @code{on}.
|
| +
|
| @end table
|
|
|
| @node Skipping Over Functions and Files
|
| @@ -5308,6 +5449,10 @@ Similar, but print information only about the specified signal number.
|
|
|
| @code{info handle} is an alias for @code{info signals}.
|
|
|
| +@item catch signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
|
| +Set a catchpoint for the indicated signals. @xref{Set Catchpoints},
|
| +for details about this command.
|
| +
|
| @kindex handle
|
| @item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
|
| Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
|
| @@ -5764,6 +5909,24 @@ after the breakpoint condition, like this:
|
|
|
| @end table
|
|
|
| +Thread-specific breakpoints are automatically deleted when
|
| +@value{GDBN} detects the corresponding thread is no longer in the
|
| +thread list. For example:
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) c
|
| +Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list.
|
| +@end smallexample
|
| +
|
| +There are several ways for a thread to disappear, such as a regular
|
| +thread exit, but also when you detach from the process with the
|
| +@code{detach} command (@pxref{Attach, ,Debugging an Already-running
|
| +Process}), or if @value{GDBN} loses the remote connection
|
| +(@pxref{Remote Debugging}), etc. Note that with some targets,
|
| +@value{GDBN} is only able to detect a thread has exited when the user
|
| +explictly asks for the thread list with the @code{info threads}
|
| +command.
|
| +
|
| @node Interrupted System Calls
|
| @subsection Interrupted System Calls
|
|
|
| @@ -6071,16 +6234,40 @@ For architecture environments that support process record and replay,
|
|
|
| @table @code
|
| @kindex target record
|
| +@kindex target record-full
|
| +@kindex target record-btrace
|
| @kindex record
|
| +@kindex record full
|
| +@kindex record btrace
|
| @kindex rec
|
| -@item target record
|
| -This command starts the process record and replay target. The process
|
| -record and replay target can only debug a process that is already
|
| -running. Therefore, you need first to start the process with the
|
| -@kbd{run} or @kbd{start} commands, and then start the recording with
|
| -the @kbd{target record} command.
|
| +@kindex rec full
|
| +@kindex rec btrace
|
| +@item record @var{method}
|
| +This command starts the process record and replay target. The
|
| +recording method can be specified as parameter. Without a parameter
|
| +the command uses the @code{full} recording method. The following
|
| +recording methods are available:
|
|
|
| -Both @code{record} and @code{rec} are aliases of @code{target record}.
|
| +@table @code
|
| +@item full
|
| +Full record/replay recording using @value{GDBN}'s software record and
|
| +replay implementation. This method allows replaying and reverse
|
| +execution.
|
| +
|
| +@item btrace
|
| +Hardware-supported instruction recording. This method does not allow
|
| +replaying and reverse execution.
|
| +
|
| +This recording method may not be available on all processors.
|
| +@end table
|
| +
|
| +The process record and replay target can only debug a process that is
|
| +already running. Therefore, you need first to start the process with
|
| +the @kbd{run} or @kbd{start} commands, and then start the recording
|
| +with the @kbd{record @var{method}} command.
|
| +
|
| +Both @code{record @var{method}} and @code{rec @var{method}} are
|
| +aliases of @code{target record-@var{method}}.
|
|
|
| @cindex displaced stepping, and process record and replay
|
| Displaced stepping (@pxref{Maintenance Commands,, displaced stepping})
|
| @@ -6091,9 +6278,9 @@ doesn't support displaced stepping.
|
| @cindex non-stop mode, and process record and replay
|
| @cindex asynchronous execution, and process record and replay
|
| If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in
|
| -the asynchronous execution mode (@pxref{Background Execution}), the
|
| -process record and replay target cannot be started because it doesn't
|
| -support these two modes.
|
| +the asynchronous execution mode (@pxref{Background Execution}), not
|
| +all recording methods are available. The @code{full} recording method
|
| +does not support these two modes.
|
|
|
| @kindex record stop
|
| @kindex rec s
|
| @@ -6117,20 +6304,41 @@ usual ``live'' debugging of the process from that state.
|
| When the inferior process exits, or @value{GDBN} detaches from it,
|
| process record and replay target will automatically stop itself.
|
|
|
| +@kindex record goto
|
| +@item record goto
|
| +Go to a specific location in the execution log. There are several
|
| +ways to specify the location to go to:
|
| +
|
| +@table @code
|
| +@item record goto begin
|
| +@itemx record goto start
|
| +Go to the beginning of the execution log.
|
| +
|
| +@item record goto end
|
| +Go to the end of the execution log.
|
| +
|
| +@item record goto @var{n}
|
| +Go to instruction number @var{n} in the execution log.
|
| +@end table
|
| +
|
| @kindex record save
|
| @item record save @var{filename}
|
| Save the execution log to a file @file{@var{filename}}.
|
| Default filename is @file{gdb_record.@var{process_id}}, where
|
| @var{process_id} is the process ID of the inferior.
|
|
|
| +This command may not be available for all recording methods.
|
| +
|
| @kindex record restore
|
| @item record restore @var{filename}
|
| Restore the execution log from a file @file{@var{filename}}.
|
| File must have been created with @code{record save}.
|
|
|
| -@kindex set record insn-number-max
|
| -@item set record insn-number-max @var{limit}
|
| -Set the limit of instructions to be recorded. Default value is 200000.
|
| +@kindex set record full
|
| +@item set record full insn-number-max @var{limit}
|
| +@itemx set record full insn-number-max unlimited
|
| +Set the limit of instructions to be recorded for the @code{full}
|
| +recording method. Default value is 200000.
|
|
|
| If @var{limit} is a positive number, then @value{GDBN} will start
|
| deleting instructions from the log once the number of the record
|
| @@ -6141,35 +6349,35 @@ instruction to keep the number of recorded instructions at the limit.
|
| lets you control what happens when the limit is reached, by means of
|
| the @code{stop-at-limit} option, described below.)
|
|
|
| -If @var{limit} is zero, @value{GDBN} will never delete recorded
|
| -instructions from the execution log. The number of recorded
|
| -instructions is unlimited in this case.
|
| +If @var{limit} is @code{unlimited} or zero, @value{GDBN} will never
|
| +delete recorded instructions from the execution log. The number of
|
| +recorded instructions is limited only by the available memory.
|
|
|
| -@kindex show record insn-number-max
|
| -@item show record insn-number-max
|
| -Show the limit of instructions to be recorded.
|
| +@kindex show record full
|
| +@item show record full insn-number-max
|
| +Show the limit of instructions to be recorded with the @code{full}
|
| +recording method.
|
|
|
| -@kindex set record stop-at-limit
|
| -@item set record stop-at-limit
|
| -Control the behavior when the number of recorded instructions reaches
|
| -the limit. If ON (the default), @value{GDBN} will stop when the limit
|
| -is reached for the first time and ask you whether you want to stop the
|
| -inferior or continue running it and recording the execution log. If
|
| -you decide to continue recording, each new recorded instruction will
|
| -cause the oldest one to be deleted.
|
| +@item set record full stop-at-limit
|
| +Control the behavior of the @code{full} recording method when the
|
| +number of recorded instructions reaches the limit. If ON (the
|
| +default), @value{GDBN} will stop when the limit is reached for the
|
| +first time and ask you whether you want to stop the inferior or
|
| +continue running it and recording the execution log. If you decide
|
| +to continue recording, each new recorded instruction will cause the
|
| +oldest one to be deleted.
|
|
|
| If this option is OFF, @value{GDBN} will automatically delete the
|
| oldest record to make room for each new one, without asking.
|
|
|
| -@kindex show record stop-at-limit
|
| -@item show record stop-at-limit
|
| +@item show record full stop-at-limit
|
| Show the current setting of @code{stop-at-limit}.
|
|
|
| -@kindex set record memory-query
|
| -@item set record memory-query
|
| +@item set record full memory-query
|
| Control the behavior when @value{GDBN} is unable to record memory
|
| -changes caused by an instruction. If ON, @value{GDBN} will query
|
| -whether to stop the inferior in that case.
|
| +changes caused by an instruction for the @code{full} recording method.
|
| +If ON, @value{GDBN} will query whether to stop the inferior in that
|
| +case.
|
|
|
| If this option is OFF (the default), @value{GDBN} will automatically
|
| ignore the effect of such instructions on memory. Later, when
|
| @@ -6177,14 +6385,18 @@ ignore the effect of such instructions on memory. Later, when
|
| instruction as not accessible, and it will not affect the replay
|
| results.
|
|
|
| -@kindex show record memory-query
|
| -@item show record memory-query
|
| +@item show record full memory-query
|
| Show the current setting of @code{memory-query}.
|
|
|
| @kindex info record
|
| @item info record
|
| -Show various statistics about the state of process record and its
|
| -in-memory execution log buffer, including:
|
| +Show various statistics about the recording depending on the recording
|
| +method:
|
| +
|
| +@table @code
|
| +@item full
|
| +For the @code{full} recording method, it shows the state of process
|
| +record and its in-memory execution log buffer, including:
|
|
|
| @itemize @bullet
|
| @item
|
| @@ -6201,6 +6413,12 @@ Number of instructions contained in the execution log.
|
| Maximum number of instructions that may be contained in the execution log.
|
| @end itemize
|
|
|
| +@item btrace
|
| +For the @code{btrace} recording method, it shows the number of
|
| +instructions that have been recorded and the number of blocks of
|
| +sequential control-flow that is formed by the recorded instructions.
|
| +@end table
|
| +
|
| @kindex record delete
|
| @kindex rec del
|
| @item record delete
|
| @@ -6208,6 +6426,120 @@ When record target runs in replay mode (``in the past''), delete the
|
| subsequent execution log and begin to record a new execution log starting
|
| from the current address. This means you will abandon the previously
|
| recorded ``future'' and begin recording a new ``future''.
|
| +
|
| +@kindex record instruction-history
|
| +@kindex rec instruction-history
|
| +@item record instruction-history
|
| +Disassembles instructions from the recorded execution log. By
|
| +default, ten instructions are disassembled. This can be changed using
|
| +the @code{set record instruction-history-size} command. Instructions
|
| +are printed in execution order. There are several ways to specify
|
| +what part of the execution log to disassemble:
|
| +
|
| +@table @code
|
| +@item record instruction-history @var{insn}
|
| +Disassembles ten instructions starting from instruction number
|
| +@var{insn}.
|
| +
|
| +@item record instruction-history @var{insn}, +/-@var{n}
|
| +Disassembles @var{n} instructions around instruction number
|
| +@var{insn}. If @var{n} is preceded with @code{+}, disassembles
|
| +@var{n} instructions after instruction number @var{insn}. If
|
| +@var{n} is preceded with @code{-}, disassembles @var{n}
|
| +instructions before instruction number @var{insn}.
|
| +
|
| +@item record instruction-history
|
| +Disassembles ten more instructions after the last disassembly.
|
| +
|
| +@item record instruction-history -
|
| +Disassembles ten more instructions before the last disassembly.
|
| +
|
| +@item record instruction-history @var{begin} @var{end}
|
| +Disassembles instructions beginning with instruction number
|
| +@var{begin} until instruction number @var{end}. The instruction
|
| +number @var{end} is not included.
|
| +@end table
|
| +
|
| +This command may not be available for all recording methods.
|
| +
|
| +@kindex set record
|
| +@item set record instruction-history-size @var{size}
|
| +@itemx set record instruction-history-size unlimited
|
| +Define how many instructions to disassemble in the @code{record
|
| +instruction-history} command. The default value is 10.
|
| +A @var{size} of @code{unlimited} means unlimited instructions.
|
| +
|
| +@kindex show record
|
| +@item show record instruction-history-size
|
| +Show how many instructions to disassemble in the @code{record
|
| +instruction-history} command.
|
| +
|
| +@kindex record function-call-history
|
| +@kindex rec function-call-history
|
| +@item record function-call-history
|
| +Prints the execution history at function granularity. It prints one
|
| +line for each sequence of instructions that belong to the same
|
| +function giving the name of that function, the source lines
|
| +for this instruction sequence (if the @code{/l} modifier is
|
| +specified), and the instructions numbers that form the sequence (if
|
| +the @code{/i} modifier is specified).
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) @b{list 1, 10}
|
| +1 void foo (void)
|
| +2 @{
|
| +3 @}
|
| +4
|
| +5 void bar (void)
|
| +6 @{
|
| +7 ...
|
| +8 foo ();
|
| +9 ...
|
| +10 @}
|
| +(@value{GDBP}) @b{record function-call-history /l}
|
| +1 foo.c:6-8 bar
|
| +2 foo.c:2-3 foo
|
| +3 foo.c:9-10 bar
|
| +@end smallexample
|
| +
|
| +By default, ten lines are printed. This can be changed using the
|
| +@code{set record function-call-history-size} command. Functions are
|
| +printed in execution order. There are several ways to specify what
|
| +to print:
|
| +
|
| +@table @code
|
| +@item record function-call-history @var{func}
|
| +Prints ten functions starting from function number @var{func}.
|
| +
|
| +@item record function-call-history @var{func}, +/-@var{n}
|
| +Prints @var{n} functions around function number @var{func}. If
|
| +@var{n} is preceded with @code{+}, prints @var{n} functions after
|
| +function number @var{func}. If @var{n} is preceded with @code{-},
|
| +prints @var{n} functions before function number @var{func}.
|
| +
|
| +@item record function-call-history
|
| +Prints ten more functions after the last ten-line print.
|
| +
|
| +@item record function-call-history -
|
| +Prints ten more functions before the last ten-line print.
|
| +
|
| +@item record function-call-history @var{begin} @var{end}
|
| +Prints functions beginning with function number @var{begin} until
|
| +function number @var{end}. The function number @var{end} is not
|
| +included.
|
| +@end table
|
| +
|
| +This command may not be available for all recording methods.
|
| +
|
| +@item set record function-call-history-size @var{size}
|
| +@itemx set record function-call-history-size unlimited
|
| +Define how many lines to print in the
|
| +@code{record function-call-history} command. The default value is 10.
|
| +A size of @code{unlimited} means unlimited lines.
|
| +
|
| +@item show record function-call-history-size
|
| +Show how many lines to print in the
|
| +@code{record function-call-history} command.
|
| @end table
|
|
|
|
|
| @@ -6245,6 +6577,7 @@ currently executing frame and describes it briefly, similar to the
|
| @menu
|
| * Frames:: Stack frames
|
| * Backtrace:: Backtraces
|
| +* Frame Filter Management:: Managing frame filters
|
| * Selection:: Selecting a frame
|
| * Frame Info:: Information on a frame
|
|
|
| @@ -6332,6 +6665,7 @@ line per frame, for many frames, starting with the currently executing
|
| frame (frame zero), followed by its caller (frame one), and on up the
|
| stack.
|
|
|
| +@anchor{backtrace-command}
|
| @table @code
|
| @kindex backtrace
|
| @kindex bt @r{(@code{backtrace})}
|
| @@ -6357,6 +6691,19 @@ Similar, but print only the outermost @var{n} frames.
|
| @itemx bt full -@var{n}
|
| Print the values of the local variables also. @var{n} specifies the
|
| number of frames to print, as described above.
|
| +
|
| +@item backtrace no-filters
|
| +@itemx bt no-filters
|
| +@itemx bt no-filters @var{n}
|
| +@itemx bt no-filters -@var{n}
|
| +@itemx bt no-filters full
|
| +@itemx bt no-filters full @var{n}
|
| +@itemx bt no-filters full -@var{n}
|
| +Do not run Python frame filters on this backtrace. @xref{Frame
|
| +Filter API}, for more information. Additionally use @ref{disable
|
| +frame-filter all} to turn off all frame filters. This is only
|
| +relevant when @value{GDBN} has been configured with @code{Python}
|
| +support.
|
| @end table
|
|
|
| @kindex where
|
| @@ -6480,14 +6827,176 @@ Display the current internal entry point backtrace policy.
|
|
|
| @item set backtrace limit @var{n}
|
| @itemx set backtrace limit 0
|
| +@itemx set backtrace limit unlimited
|
| @cindex backtrace limit
|
| -Limit the backtrace to @var{n} levels. A value of zero means
|
| -unlimited.
|
| +Limit the backtrace to @var{n} levels. A value of @code{unlimited}
|
| +or zero means unlimited levels.
|
|
|
| @item show backtrace limit
|
| Display the current limit on backtrace levels.
|
| @end table
|
|
|
| +You can control how file names are displayed.
|
| +
|
| +@table @code
|
| +@item set filename-display
|
| +@itemx set filename-display relative
|
| +@cindex filename-display
|
| +Display file names relative to the compilation directory. This is the default.
|
| +
|
| +@item set filename-display basename
|
| +Display only basename of a filename.
|
| +
|
| +@item set filename-display absolute
|
| +Display an absolute filename.
|
| +
|
| +@item show filename-display
|
| +Show the current way to display filenames.
|
| +@end table
|
| +
|
| +@node Frame Filter Management
|
| +@section Management of Frame Filters.
|
| +@cindex managing frame filters
|
| +
|
| +Frame filters are Python based utilities to manage and decorate the
|
| +output of frames. @xref{Frame Filter API}, for further information.
|
| +
|
| +Managing frame filters is performed by several commands available
|
| +within @value{GDBN}, detailed here.
|
| +
|
| +@table @code
|
| +@kindex info frame-filter
|
| +@item info frame-filter
|
| +Print a list of installed frame filters from all dictionaries, showing
|
| +their name, priority and enabled status.
|
| +
|
| +@kindex disable frame-filter
|
| +@anchor{disable frame-filter all}
|
| +@item disable frame-filter @var{filter-dictionary} @var{filter-name}
|
| +Disable a frame filter in the dictionary matching
|
| +@var{filter-dictionary}, or @code{all}, and @var{filter-name}.
|
| +@var{filter-dictionary} may be @code{all}, @code{global},
|
| +@code{progspace} or the name of the object file where the frame filter
|
| +dictionary resides. When @code{all} is specified, all frame filters
|
| +across all dictionaries are disabled. @var{filter-name} is the name
|
| +of the frame filter and is used when @code{all} is not the option for
|
| +@var{filter-dictionary}. A disabled frame-filter is not deleted, it
|
| +may be enabled again later.
|
| +
|
| +@kindex enable frame-filter
|
| +@item enable frame-filter @var{filter-dictionary} @var{filter-name}
|
| +Enable a frame filter in the dictionary matching
|
| +@var{filter-dictionary}, or @code{all}, and @var{filter-name}.
|
| +@var{filter-dictionary} may be @code{all}, @code{global},
|
| +@code{progspace} or the name of the object file where the frame filter
|
| +dictionary resides. When @code{all} is specified, all frame filters across
|
| +all dictionaries are enabled. @var{filter-name} is the name of the frame
|
| +filter and is used when @code{all} is not the option for
|
| +@var{filter-dictionary}.
|
| +
|
| +Example:
|
| +
|
| +@smallexample
|
| +(gdb) info frame-filter
|
| +
|
| +global frame-filters:
|
| + Priority Enabled Name
|
| + 1000 No PrimaryFunctionFilter
|
| + 100 Yes Reverse
|
| +
|
| +progspace /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 100 Yes ProgspaceFilter
|
| +
|
| +objfile /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 999 Yes BuildProgra Filter
|
| +
|
| +(gdb) disable frame-filter /build/test BuildProgramFilter
|
| +(gdb) info frame-filter
|
| +
|
| +global frame-filters:
|
| + Priority Enabled Name
|
| + 1000 No PrimaryFunctionFilter
|
| + 100 Yes Reverse
|
| +
|
| +progspace /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 100 Yes ProgspaceFilter
|
| +
|
| +objfile /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 999 No BuildProgramFilter
|
| +
|
| +(gdb) enable frame-filter global PrimaryFunctionFilter
|
| +(gdb) info frame-filter
|
| +
|
| +global frame-filters:
|
| + Priority Enabled Name
|
| + 1000 Yes PrimaryFunctionFilter
|
| + 100 Yes Reverse
|
| +
|
| +progspace /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 100 Yes ProgspaceFilter
|
| +
|
| +objfile /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 999 No BuildProgramFilter
|
| +@end smallexample
|
| +
|
| +@kindex set frame-filter priority
|
| +@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority}
|
| +Set the @var{priority} of a frame filter in the dictionary matching
|
| +@var{filter-dictionary}, and the frame filter name matching
|
| +@var{filter-name}. @var{filter-dictionary} may be @code{global},
|
| +@code{progspace} or the name of the object file where the frame filter
|
| +dictionary resides. @var{priority} is an integer.
|
| +
|
| +@kindex show frame-filter priority
|
| +@item show frame-filter priority @var{filter-dictionary} @var{filter-name}
|
| +Show the @var{priority} of a frame filter in the dictionary matching
|
| +@var{filter-dictionary}, and the frame filter name matching
|
| +@var{filter-name}. @var{filter-dictionary} may be @code{global},
|
| +@code{progspace} or the name of the object file where the frame filter
|
| +dictionary resides.
|
| +
|
| +Example:
|
| +
|
| +@smallexample
|
| +(gdb) info frame-filter
|
| +
|
| +global frame-filters:
|
| + Priority Enabled Name
|
| + 1000 Yes PrimaryFunctionFilter
|
| + 100 Yes Reverse
|
| +
|
| +progspace /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 100 Yes ProgspaceFilter
|
| +
|
| +objfile /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 999 No BuildProgramFilter
|
| +
|
| +(gdb) set frame-filter priority global Reverse 50
|
| +(gdb) info frame-filter
|
| +
|
| +global frame-filters:
|
| + Priority Enabled Name
|
| + 1000 Yes PrimaryFunctionFilter
|
| + 50 Yes Reverse
|
| +
|
| +progspace /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 100 Yes ProgspaceFilter
|
| +
|
| +objfile /build/test frame-filters:
|
| + Priority Enabled Name
|
| + 999 No BuildProgramFilter
|
| +@end smallexample
|
| +@end table
|
| +
|
| @node Selection
|
| @section Selecting a Frame
|
|
|
| @@ -6703,8 +7212,10 @@ the @code{list} command. You can change this using @code{set listsize}:
|
| @table @code
|
| @kindex set listsize
|
| @item set listsize @var{count}
|
| +@itemx set listsize unlimited
|
| Make the @code{list} command display @var{count} source lines (unless
|
| the @code{list} argument explicitly specifies some other number).
|
| +Setting @var{count} to @code{unlimited} or 0 means there's no limit.
|
|
|
| @kindex show listsize
|
| @item show listsize
|
| @@ -6925,6 +7436,7 @@ regular expression.
|
| @table @code
|
| @kindex search
|
| @kindex forward-search
|
| +@kindex fo @r{(@code{forward-search})}
|
| @item forward-search @var{regexp}
|
| @itemx search @var{regexp}
|
| The command @samp{forward-search @var{regexp}} checks each line,
|
| @@ -7305,6 +7817,11 @@ Dump of assembler code from 0x400281 to 0x40028b:
|
| End of assembler dump.
|
| @end smallexample
|
|
|
| +Addresses cannot be specified as a linespec (@pxref{Specify Location}).
|
| +So, for example, if you want to disassemble function @code{bar}
|
| +in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar}
|
| +and not @samp{disassemble foo.c:bar}.
|
| +
|
| Some architectures have more than one commonly-used set of instruction
|
| mnemonics or other syntax.
|
|
|
| @@ -7362,9 +7879,6 @@ instruction.
|
| @cindex examining data
|
| @kindex print
|
| @kindex inspect
|
| -@c "inspect" is not quite a synonym if you are using Epoch, which we do not
|
| -@c document because it is nonstandard... Under Epoch it displays in a
|
| -@c different window or something like that.
|
| The usual way to examine data in your program is with the @code{print}
|
| command (abbreviated @code{p}), or its synonym @code{inspect}. It
|
| evaluates and prints the value of an expression of the language your
|
| @@ -7557,6 +8071,7 @@ being passed the type of @var{arg} as the argument.
|
| * Pretty Printing:: Python pretty printing
|
| * Value History:: Value history
|
| * Convenience Vars:: Convenience variables
|
| +* Convenience Funs:: Convenience functions
|
| * Registers:: Registers
|
| * Floating Point Hardware:: Floating point hardware
|
| * Vector Unit:: Vector Unit
|
| @@ -7566,7 +8081,7 @@ being passed the type of @var{arg} as the argument.
|
| * Core File Generation:: Cause a program dump its core
|
| * Character Sets:: Debugging programs that use a different
|
| character set than GDB does
|
| -* Caching Remote Data:: Data caching for remote targets
|
| +* Caching Target Data:: Data caching for targets
|
| * Searching Memory:: Searching memory for a sequence of bytes
|
| @end menu
|
|
|
| @@ -7824,11 +8339,24 @@ $4 = 0
|
| @end smallexample
|
|
|
| @cindex C@t{++} scope resolution
|
| -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
|
| -@c conflict?? --mew
|
| +These uses of @samp{::} are very rarely in conflict with the very
|
| +similar use of the same notation in C@t{++}. When they are in
|
| +conflict, the C@t{++} meaning takes precedence; however, this can be
|
| +overridden by quoting the file or function name with single quotes.
|
| +
|
| +For example, suppose the program is stopped in a method of a class
|
| +that has a field named @code{includefile}, and there is also an
|
| +include file named @file{includefile} that defines a variable,
|
| +@code{some_global}.
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) p includefile
|
| +$1 = 23
|
| +(@value{GDBP}) p includefile::some_global
|
| +A syntax error in expression, near `'.
|
| +(@value{GDBP}) p 'includefile'::some_global
|
| +$2 = 27
|
| +@end smallexample
|
|
|
| @cindex wrong values
|
| @cindex variable values, wrong
|
| @@ -8065,6 +8593,11 @@ Without this format, @value{GDBN} displays pointers to and arrays of
|
| strings. Single-byte members of a vector are displayed as an integer
|
| array.
|
|
|
| +@item z
|
| +Like @samp{x} formatting, the value is treated as an integer and
|
| +printed as hexadecimal, but leading zeros are printed to pad the value
|
| +to the size of the integer type.
|
| +
|
| @item r
|
| @cindex raw printing
|
| Print using the @samp{raw} formatting. By default, @value{GDBN} will
|
| @@ -8431,11 +8964,13 @@ printed is reasonably close to the closest earlier symbol:
|
|
|
| @table @code
|
| @item set print max-symbolic-offset @var{max-offset}
|
| +@itemx set print max-symbolic-offset unlimited
|
| @cindex maximum value for offset of closest symbol
|
| Tell @value{GDBN} to only display the symbolic form of an address if the
|
| offset between the closest earlier symbol and the address is less than
|
| -@var{max-offset}. The default is 0, which tells @value{GDBN}
|
| -to always print the symbolic form of an address if any symbol precedes it.
|
| +@var{max-offset}. The default is @code{unlimited}, which tells @value{GDBN}
|
| +to always print the symbolic form of an address if any symbol precedes
|
| +it. Zero is equivalent to @code{unlimited}.
|
|
|
| @item show print max-symbolic-offset
|
| Ask how large the maximum offset is that @value{GDBN} prints in a
|
| @@ -8512,6 +9047,7 @@ Show whether the index of each element is printed when displaying
|
| arrays.
|
|
|
| @item set print elements @var{number-of-elements}
|
| +@itemx set print elements unlimited
|
| @cindex number of array elements to print
|
| @cindex limit on number of printed array elements
|
| Set a limit on how many elements of an array @value{GDBN} will print.
|
| @@ -8519,7 +9055,8 @@ If @value{GDBN} is printing a large array, it stops printing after it has
|
| printed the number of elements set by the @code{set print elements} command.
|
| This limit also applies to the display of strings.
|
| When @value{GDBN} starts, this limit is set to 200.
|
| -Setting @var{number-of-elements} to zero means that the printing is unlimited.
|
| +Setting @var{number-of-elements} to @code{unlimited} or zero means
|
| +that the number of elements to print is unlimited.
|
|
|
| @item show print elements
|
| Display the number of elements of a large array that @value{GDBN} will print.
|
| @@ -8574,6 +9111,18 @@ thus speeding up the display of each Ada frame.
|
| @item show print frame-arguments
|
| Show how the value of arguments should be displayed when printing a frame.
|
|
|
| +@item set print raw frame-arguments on
|
| +Print frame arguments in raw, non pretty-printed, form.
|
| +
|
| +@item set print raw frame-arguments off
|
| +Print frame arguments in pretty-printed form, if there is a pretty-printer
|
| +for the value (@pxref{Pretty Printing}),
|
| +otherwise print the value in raw form.
|
| +This is the default.
|
| +
|
| +@item show print raw frame-arguments
|
| +Show whether to print frame arguments in raw form.
|
| +
|
| @anchor{set print entry-values}
|
| @item set print entry-values @var{value}
|
| @kindex set print entry-values
|
| @@ -8689,15 +9238,17 @@ entry resolution see @ref{set debug entry-values}.
|
| Show the method being used for printing of frame argument values at function
|
| entry.
|
|
|
| -@item set print repeats
|
| +@item set print repeats @var{number-of-repeats}
|
| +@itemx set print repeats unlimited
|
| @cindex repeated array elements
|
| Set the threshold for suppressing display of repeated array
|
| elements. When the number of consecutive identical elements of an
|
| array exceeds the threshold, @value{GDBN} prints the string
|
| @code{"<repeats @var{n} times>"}, where @var{n} is the number of
|
| identical repetitions, instead of displaying the identical elements
|
| -themselves. Setting the threshold to zero will cause all elements to
|
| -be individually printed. The default threshold is 10.
|
| +themselves. Setting the threshold to @code{unlimited} or zero will
|
| +cause all elements to be individually printed. The default threshold
|
| +is 10.
|
|
|
| @item show print repeats
|
| Display the current threshold for printing repeated identical
|
| @@ -8852,10 +9403,10 @@ represent C@t{++} names. The choices for @var{style} are currently:
|
| @table @code
|
| @item auto
|
| Allow @value{GDBN} to choose a decoding style by inspecting your program.
|
| +This is the default.
|
|
|
| @item gnu
|
| Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
|
| -This is the default.
|
|
|
| @item hp
|
| Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
|
| @@ -9223,9 +9774,10 @@ variable, when used as an expression, has the type of its current value.
|
|
|
| @table @code
|
| @kindex show convenience
|
| -@cindex show all user variables
|
| +@cindex show all user variables and functions
|
| @item show convenience
|
| -Print a list of convenience variables used so far, and their values.
|
| +Print a list of convenience variables used so far, and their values,
|
| +as well as a list of the convenience functions.
|
| Abbreviated @code{show conv}.
|
|
|
| @kindex init-if-undefined
|
| @@ -9275,8 +9827,68 @@ to match the format in which the data was printed.
|
|
|
| @item $_exitcode
|
| @vindex $_exitcode@r{, convenience variable}
|
| -The variable @code{$_exitcode} is automatically set to the exit code when
|
| -the program being debugged terminates.
|
| +When the program being debugged terminates normally, @value{GDBN}
|
| +automatically sets this variable to the exit code of the program, and
|
| +resets @code{$_exitsignal} to @code{void}.
|
| +
|
| +@item $_exitsignal
|
| +@vindex $_exitsignal@r{, convenience variable}
|
| +When the program being debugged dies due to an uncaught signal,
|
| +@value{GDBN} automatically sets this variable to that signal's number,
|
| +and resets @code{$_exitcode} to @code{void}.
|
| +
|
| +To distinguish between whether the program being debugged has exited
|
| +(i.e., @code{$_exitcode} is not @code{void}) or signalled (i.e.,
|
| +@code{$_exitsignal} is not @code{void}), the convenience function
|
| +@code{$_isvoid} can be used (@pxref{Convenience Funs,, Convenience
|
| +Functions}). For example, considering the following source code:
|
| +
|
| +@smallexample
|
| +#include <signal.h>
|
| +
|
| +int
|
| +main (int argc, char *argv[])
|
| +@{
|
| + raise (SIGALRM);
|
| + return 0;
|
| +@}
|
| +@end smallexample
|
| +
|
| +A valid way of telling whether the program being debugged has exited
|
| +or signalled would be:
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) define has_exited_or_signalled
|
| +Type commands for definition of ``has_exited_or_signalled''.
|
| +End with a line saying just ``end''.
|
| +>if $_isvoid ($_exitsignal)
|
| + >echo The program has exited\n
|
| + >else
|
| + >echo The program has signalled\n
|
| + >end
|
| +>end
|
| +(@value{GDBP}) run
|
| +Starting program:
|
| +
|
| +Program terminated with signal SIGALRM, Alarm clock.
|
| +The program no longer exists.
|
| +(@value{GDBP}) has_exited_or_signalled
|
| +The program has signalled
|
| +@end smallexample
|
| +
|
| +As can be seen, @value{GDBN} correctly informs that the program being
|
| +debugged has signalled, since it calls @code{raise} and raises a
|
| +@code{SIGALRM} signal. If the program being debugged had not called
|
| +@code{raise}, then @value{GDBN} would report a normal exit:
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) has_exited_or_signalled
|
| +The program has exited
|
| +@end smallexample
|
| +
|
| +@item $_exception
|
| +The variable @code{$_exception} is set to the exception object being
|
| +thrown at an exception-related catchpoint. @xref{Set Catchpoints}.
|
|
|
| @item $_probe_argc
|
| @itemx $_probe_arg0@dots{}$_probe_arg11
|
| @@ -9310,6 +9922,9 @@ On HP-UX systems, if you refer to a function or variable name that
|
| begins with a dollar sign, @value{GDBN} searches for a user or system
|
| name first, before it searches for a convenience variable.
|
|
|
| +@node Convenience Funs
|
| +@section Convenience Functions
|
| +
|
| @cindex convenience functions
|
| @value{GDBN} also supplies some @dfn{convenience functions}. These
|
| have a syntax similar to convenience variables. A convenience
|
| @@ -9317,6 +9932,101 @@ function can be used in an expression just like an ordinary function;
|
| however, a convenience function is implemented internally to
|
| @value{GDBN}.
|
|
|
| +These functions do not require @value{GDBN} to be configured with
|
| +@code{Python} support, which means that they are always available.
|
| +
|
| +@table @code
|
| +
|
| +@item $_isvoid (@var{expr})
|
| +@findex $_isvoid@r{, convenience function}
|
| +Return one if the expression @var{expr} is @code{void}. Otherwise it
|
| +returns zero.
|
| +
|
| +A @code{void} expression is an expression where the type of the result
|
| +is @code{void}. For example, you can examine a convenience variable
|
| +(see @ref{Convenience Vars,, Convenience Variables}) to check whether
|
| +it is @code{void}:
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) print $_exitcode
|
| +$1 = void
|
| +(@value{GDBP}) print $_isvoid ($_exitcode)
|
| +$2 = 1
|
| +(@value{GDBP}) run
|
| +Starting program: ./a.out
|
| +[Inferior 1 (process 29572) exited normally]
|
| +(@value{GDBP}) print $_exitcode
|
| +$3 = 0
|
| +(@value{GDBP}) print $_isvoid ($_exitcode)
|
| +$4 = 0
|
| +@end smallexample
|
| +
|
| +In the example above, we used @code{$_isvoid} to check whether
|
| +@code{$_exitcode} is @code{void} before and after the execution of the
|
| +program being debugged. Before the execution there is no exit code to
|
| +be examined, therefore @code{$_exitcode} is @code{void}. After the
|
| +execution the program being debugged returned zero, therefore
|
| +@code{$_exitcode} is zero, which means that it is not @code{void}
|
| +anymore.
|
| +
|
| +The @code{void} expression can also be a call of a function from the
|
| +program being debugged. For example, given the following function:
|
| +
|
| +@smallexample
|
| +void
|
| +foo (void)
|
| +@{
|
| +@}
|
| +@end smallexample
|
| +
|
| +The result of calling it inside @value{GDBN} is @code{void}:
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) print foo ()
|
| +$1 = void
|
| +(@value{GDBP}) print $_isvoid (foo ())
|
| +$2 = 1
|
| +(@value{GDBP}) set $v = foo ()
|
| +(@value{GDBP}) print $v
|
| +$3 = void
|
| +(@value{GDBP}) print $_isvoid ($v)
|
| +$4 = 1
|
| +@end smallexample
|
| +
|
| +@end table
|
| +
|
| +These functions require @value{GDBN} to be configured with
|
| +@code{Python} support.
|
| +
|
| +@table @code
|
| +
|
| +@item $_memeq(@var{buf1}, @var{buf2}, @var{length})
|
| +@findex $_memeq@r{, convenience function}
|
| +Returns one if the @var{length} bytes at the addresses given by
|
| +@var{buf1} and @var{buf2} are equal.
|
| +Otherwise it returns zero.
|
| +
|
| +@item $_regex(@var{str}, @var{regex})
|
| +@findex $_regex@r{, convenience function}
|
| +Returns one if the string @var{str} matches the regular expression
|
| +@var{regex}. Otherwise it returns zero.
|
| +The syntax of the regular expression is that specified by @code{Python}'s
|
| +regular expression support.
|
| +
|
| +@item $_streq(@var{str1}, @var{str2})
|
| +@findex $_streq@r{, convenience function}
|
| +Returns one if the strings @var{str1} and @var{str2} are equal.
|
| +Otherwise it returns zero.
|
| +
|
| +@item $_strlen(@var{str})
|
| +@findex $_strlen@r{, convenience function}
|
| +Returns the length of string @var{str}.
|
| +
|
| +@end table
|
| +
|
| +@value{GDBN} provides the ability to list and get help on
|
| +convenience functions.
|
| +
|
| @table @code
|
| @item help function
|
| @kindex help function
|
| @@ -9453,10 +10163,33 @@ were exited and their saved registers restored. In order to see the
|
| true contents of hardware registers, you must select the innermost
|
| frame (with @samp{frame 0}).
|
|
|
| -However, @value{GDBN} must deduce where registers are saved, from the machine
|
| -code generated by your compiler. If some registers are not saved, or if
|
| -@value{GDBN} is unable to locate the saved registers, the selected stack
|
| -frame makes no difference.
|
| +@cindex caller-saved registers
|
| +@cindex call-clobbered registers
|
| +@cindex volatile registers
|
| +@cindex <not saved> values
|
| +Usually ABIs reserve some registers as not needed to be saved by the
|
| +callee (a.k.a.: ``caller-saved'', ``call-clobbered'' or ``volatile''
|
| +registers). It may therefore not be possible for @value{GDBN} to know
|
| +the value a register had before the call (in other words, in the outer
|
| +frame), if the register value has since been changed by the callee.
|
| +@value{GDBN} tries to deduce where the inner frame saved
|
| +(``callee-saved'') registers, from the debug info, unwind info, or the
|
| +machine code generated by your compiler. If some register is not
|
| +saved, and @value{GDBN} knows the register is ``caller-saved'' (via
|
| +its own knowledge of the ABI, or because the debug/unwind info
|
| +explicitly says the register's value is undefined), @value{GDBN}
|
| +displays @w{@samp{<not saved>}} as the register's value. With targets
|
| +that @value{GDBN} has no knowledge of the register saving convention,
|
| +if a register was not saved by the callee, then its value and location
|
| +in the outer frame are assumed to be the same of the inner frame.
|
| +This is usually harmless, because if the register is call-clobbered,
|
| +the caller either does not care what is in the register after the
|
| +call, or has code to restore the value that it does care about. Note,
|
| +however, that if you change such a register in the outer frame, you
|
| +may also be affecting the inner frame. Also, the more ``outer'' the
|
| +frame is you're looking at, the more likely a call-clobbered
|
| +register's value is to be wrong, in the sense that it doesn't actually
|
| +represent the value the register had just before the call.
|
|
|
| @node Floating Point Hardware
|
| @section Floating Point Hardware
|
| @@ -9495,24 +10228,6 @@ layout vary depending on the hardware.
|
| @value{GDBN} provides interfaces to useful OS facilities that can help
|
| you debug your program.
|
|
|
| -@cindex @code{ptrace} system call
|
| -@cindex @code{struct user} contents
|
| -When @value{GDBN} runs on a @dfn{Posix system} (such as GNU or Unix
|
| -machines), it interfaces with the inferior via the @code{ptrace}
|
| -system call. The operating system creates a special sata structure,
|
| -called @code{struct user}, for this interface. You can use the
|
| -command @code{info udot} to display the contents of this data
|
| -structure.
|
| -
|
| -@table @code
|
| -@item info udot
|
| -@kindex info udot
|
| -Display the contents of the @code{struct user} maintained by the OS
|
| -kernel for the program being debugged. @value{GDBN} displays the
|
| -contents of @code{struct user} as a list of hex numbers, similar to
|
| -the @code{examine} command.
|
| -@end table
|
| -
|
| @cindex auxiliary vector
|
| @cindex vector, auxiliary
|
| Some operating systems supply an @dfn{auxiliary vector} to programs at
|
| @@ -9901,7 +10616,7 @@ specified, the file name defaults to @file{core.@var{pid}}, where
|
| @var{pid} is the inferior process ID.
|
|
|
| Note that this command is implemented only for some systems (as of
|
| -this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
|
| +this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390).
|
| @end table
|
|
|
| @node Character Sets
|
| @@ -10123,25 +10838,29 @@ $10 = 78 '+'
|
| The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
|
| character.
|
|
|
| -@node Caching Remote Data
|
| -@section Caching Data of Remote Targets
|
| -@cindex caching data of remote targets
|
| -
|
| -@value{GDBN} caches data exchanged between the debugger and a
|
| -remote target (@pxref{Remote Debugging}). Such caching generally improves
|
| -performance, because it reduces the overhead of the remote protocol by
|
| -bundling memory reads and writes into large chunks. Unfortunately, simply
|
| -caching everything would lead to incorrect results, since @value{GDBN}
|
| -does not necessarily know anything about volatile values, memory-mapped I/O
|
| -addresses, etc. Furthermore, in non-stop mode (@pxref{Non-Stop Mode})
|
| -memory can be changed @emph{while} a gdb command is executing.
|
| +@node Caching Target Data
|
| +@section Caching Data of Targets
|
| +@cindex caching data of targets
|
| +
|
| +@value{GDBN} caches data exchanged between the debugger and a target.
|
| +Each cache is associated with the address space of the inferior.
|
| +@xref{Inferiors and Programs}, about inferior and address space.
|
| +Such caching generally improves performance in remote debugging
|
| +(@pxref{Remote Debugging}), because it reduces the overhead of the
|
| +remote protocol by bundling memory reads and writes into large chunks.
|
| +Unfortunately, simply caching everything would lead to incorrect results,
|
| +since @value{GDBN} does not necessarily know anything about volatile
|
| +values, memory-mapped I/O addresses, etc. Furthermore, in non-stop mode
|
| +(@pxref{Non-Stop Mode}) memory can be changed @emph{while} a gdb command
|
| +is executing.
|
| Therefore, by default, @value{GDBN} only caches data
|
| known to be on the stack@footnote{In non-stop mode, it is moderately
|
| rare for a running thread to modify the stack of a stopped thread
|
| in a way that would interfere with a backtrace, and caching of
|
| -stack reads provides a significant speed up of remote backtraces.}.
|
| +stack reads provides a significant speed up of remote backtraces.} or
|
| +in the code segment.
|
| Other regions of memory can be explicitly marked as
|
| -cacheable; see @pxref{Memory Region Attributes}.
|
| +cacheable; @pxref{Memory Region Attributes}.
|
|
|
| @table @code
|
| @kindex set remotecache
|
| @@ -10157,20 +10876,32 @@ Show the current state of the obsolete remotecache flag.
|
| @kindex set stack-cache
|
| @item set stack-cache on
|
| @itemx set stack-cache off
|
| -Enable or disable caching of stack accesses. When @code{ON}, use
|
| -caching. By default, this option is @code{ON}.
|
| +Enable or disable caching of stack accesses. When @code{on}, use
|
| +caching. By default, this option is @code{on}.
|
|
|
| @kindex show stack-cache
|
| @item show stack-cache
|
| Show the current state of data caching for memory accesses.
|
|
|
| +@kindex set code-cache
|
| +@item set code-cache on
|
| +@itemx set code-cache off
|
| +Enable or disable caching of code segment accesses. When @code{on},
|
| +use caching. By default, this option is @code{on}. This improves
|
| +performance of disassembly in remote debugging.
|
| +
|
| +@kindex show code-cache
|
| +@item show code-cache
|
| +Show the current state of target memory cache for code segment
|
| +accesses.
|
| +
|
| @kindex info dcache
|
| @item info dcache @r{[}line@r{]}
|
| -Print the information about the data cache performance. The
|
| -information displayed includes the dcache width and depth, and for
|
| -each cache line, its number, address, and how many times it was
|
| -referenced. This command is useful for debugging the data cache
|
| -operation.
|
| +Print the information about the performance of data cache of the
|
| +current inferior's address space. The information displayed
|
| +includes the dcache width and depth, and for each cache line, its
|
| +number, address, and how many times it was referenced. This
|
| +command is useful for debugging the data cache operation.
|
|
|
| If a line number is specified, the contents of that line will be
|
| printed in hex.
|
| @@ -10188,11 +10919,11 @@ Must be a power of 2.
|
|
|
| @item show dcache size
|
| @kindex show dcache size
|
| -Show maximum number of dcache entries. See also @ref{Caching Remote Data, info dcache}.
|
| +Show maximum number of dcache entries. @xref{Caching Target Data, info dcache}.
|
|
|
| @item show dcache line-size
|
| @kindex show dcache line-size
|
| -Show default size of dcache lines. See also @ref{Caching Remote Data, info dcache}.
|
| +Show default size of dcache lines.
|
|
|
| @end table
|
|
|
| @@ -11426,6 +12157,9 @@ tracing:
|
| @itemize @bullet
|
| @item
|
| its passcount as given by the @code{passcount @var{n}} command
|
| +
|
| +@item
|
| +the state about installed on target of each location
|
| @end itemize
|
|
|
| @smallexample
|
| @@ -11438,6 +12172,15 @@ Num Type Disp Enb Address What
|
| collect globfoo2
|
| end
|
| pass count 1200
|
| +2 tracepoint keep y <MULTIPLE>
|
| + collect $eip
|
| +2.1 y 0x0804859c in func4 at change-loc.h:35
|
| + installed on target
|
| +2.2 y 0xb7ffc480 in func4 at change-loc.h:35
|
| + installed on target
|
| +2.3 y <PENDING> set_tracepoint
|
| +3 tracepoint keep y 0x080485b1 in foo at change-loc.c:29
|
| + not installed on target
|
| (@value{GDBP})
|
| @end smallexample
|
|
|
| @@ -11628,6 +12371,26 @@ for instance if you are looking at frames from a trace file.
|
| @end table
|
|
|
| @table @code
|
| +@item set trace-buffer-size @var{n}
|
| +@itemx set trace-buffer-size unlimited
|
| +@kindex set trace-buffer-size
|
| +Request that the target use a trace buffer of @var{n} bytes. Not all
|
| +targets will honor the request; they may have a compiled-in size for
|
| +the trace buffer, or some other limitation. Set to a value of
|
| +@code{unlimited} or @code{-1} to let the target use whatever size it
|
| +likes. This is also the default.
|
| +
|
| +@item show trace-buffer-size
|
| +@kindex show trace-buffer-size
|
| +Show the current requested size for the trace buffer. Note that this
|
| +will only match the actual size if the target supports size-setting,
|
| +and was able to handle the requested size. For instance, if the
|
| +target can only change buffer size between runs, this variable will
|
| +not reflect the change until the next run starts. Use @code{tstatus}
|
| +to get a report of the actual buffer size.
|
| +@end table
|
| +
|
| +@table @code
|
| @item set trace-user @var{text}
|
| @kindex set trace-user
|
|
|
| @@ -12020,6 +12783,7 @@ of trace data, via the @code{target tfile} command.
|
|
|
| @kindex tsave
|
| @item tsave [ -r ] @var{filename}
|
| +@itemx tsave [-ctf] @var{dirname}
|
| Save the trace data to @var{filename}. By default, this command
|
| assumes that @var{filename} refers to the host filesystem, so if
|
| necessary @value{GDBN} will copy raw trace data up from the target and
|
| @@ -12028,16 +12792,41 @@ optional argument @code{-r} (``remote'') to direct the target to save
|
| the data directly into @var{filename} in its own filesystem, which may be
|
| more efficient if the trace buffer is very large. (Note, however, that
|
| @code{target tfile} can only read from files accessible to the host.)
|
| +By default, this command will save trace frame in tfile format.
|
| +You can supply the optional argument @code{-ctf} to save date in CTF
|
| +format. The @dfn{Common Trace Format} (CTF) is proposed as a trace format
|
| +that can be shared by multiple debugging and tracing tools. Please go to
|
| +@indicateurl{http://www.efficios.com/ctf} to get more information.
|
|
|
| @kindex target tfile
|
| @kindex tfile
|
| +@kindex target ctf
|
| +@kindex ctf
|
| @item target tfile @var{filename}
|
| -Use the file named @var{filename} as a source of trace data. Commands
|
| -that examine data work as they do with a live target, but it is not
|
| -possible to run any new trace experiments. @code{tstatus} will report
|
| -the state of the trace run at the moment the data was saved, as well
|
| -as the current trace frame you are examining. @var{filename} must be
|
| -on a filesystem accessible to the host.
|
| +@itemx target ctf @var{dirname}
|
| +Use the file named @var{filename} or directory named @var{dirname} as
|
| +a source of trace data. Commands that examine data work as they do with
|
| +a live target, but it is not possible to run any new trace experiments.
|
| +@code{tstatus} will report the state of the trace run at the moment
|
| +the data was saved, as well as the current trace frame you are examining.
|
| +@var{filename} or @var{dirname} must be on a filesystem accessible to
|
| +the host.
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) target ctf ctf.ctf
|
| +(@value{GDBP}) tfind
|
| +Found trace frame 0, tracepoint 2
|
| +39 ++a; /* set tracepoint 1 here */
|
| +(@value{GDBP}) tdump
|
| +Data collected at tracepoint 2, trace frame 0:
|
| +i = 0
|
| +a = 0
|
| +b = 1 '\001'
|
| +c = @{"123", "456", "789", "123", "456", "789"@}
|
| +d = @{@{@{a = 1, b = 2@}, @{a = 3, b = 4@}@}, @{@{a = 5, b = 6@}, @{a = 7, b = 8@}@}@}
|
| +(@value{GDBP}) p b
|
| +$1 = 1
|
| +@end smallexample
|
|
|
| @end table
|
|
|
| @@ -12595,6 +13384,7 @@ working language, and also what language source files were written in.
|
|
|
| @table @code
|
| @item show language
|
| +@anchor{show language}
|
| @kindex show language
|
| Display the current working language. This is the
|
| language you can use with commands such as @code{print} to
|
| @@ -12632,29 +13422,18 @@ List all the filename extensions and the associated languages.
|
| @node Checks
|
| @section Type and Range Checking
|
|
|
| -@quotation
|
| -@emph{Warning:} In this release, the @value{GDBN} commands for type and range
|
| -checking are included, but they do not yet have any effect. This
|
| -section documents the intended facilities.
|
| -@end quotation
|
| -@c FIXME remove warning when type/range code added
|
| -
|
| Some languages are designed to guard you against making seemingly common
|
| errors through a series of compile- and run-time checks. These include
|
| -checking the type of arguments to functions and operators, and making
|
| +checking the type of arguments to functions and operators and making
|
| sure mathematical overflows are caught at run time. Checks such as
|
| these help to ensure a program's correctness once it has been compiled
|
| -by eliminating type mismatches, and providing active checks for range
|
| +by eliminating type mismatches and providing active checks for range
|
| errors when your program is running.
|
|
|
| -@value{GDBN} can check for conditions like the above if you wish.
|
| -Although @value{GDBN} does not check the statements in your program,
|
| -it can check expressions entered directly into @value{GDBN} for
|
| -evaluation via the @code{print} command, for example. As with the
|
| -working language, @value{GDBN} can also decide whether or not to check
|
| -automatically based on your program's source language.
|
| -@xref{Supported Languages, ,Supported Languages}, for the default
|
| -settings of supported languages.
|
| +By default @value{GDBN} checks for these errors according to the
|
| +rules of the current source language. Although @value{GDBN} does not check
|
| +the statements in your program, it can check expressions entered directly
|
| +into @value{GDBN} for evaluation via the @code{print} command, for example.
|
|
|
| @menu
|
| * Type Checking:: An overview of type checking
|
| @@ -12666,69 +13445,51 @@ settings of supported languages.
|
| @node Type Checking
|
| @subsection An Overview of Type Checking
|
|
|
| -Some languages, such as Modula-2, are strongly typed, meaning that the
|
| +Some languages, such as C and C@t{++}, are strongly typed, meaning that the
|
| arguments to operators and functions have to be of the correct type,
|
| otherwise an error occurs. These checks prevent type mismatch
|
| errors from ever causing any run-time problems. For example,
|
|
|
| @smallexample
|
| -1 + 2 @result{} 3
|
| +int klass::my_method(char *b) @{ return b ? 1 : 2; @}
|
| +
|
| +(@value{GDBP}) print obj.my_method (0)
|
| +$1 = 2
|
| @exdent but
|
| -@error{} 1 + 2.3
|
| +(@value{GDBP}) print obj.my_method (0x1234)
|
| +Cannot resolve method klass::my_method to any overloaded instance
|
| @end smallexample
|
|
|
| -The second example fails because the @code{CARDINAL} 1 is not
|
| -type-compatible with the @code{REAL} 2.3.
|
| +The second example fails because in C@t{++} the integer constant
|
| +@samp{0x1234} is not type-compatible with the pointer parameter type.
|
|
|
| -For the expressions you use in @value{GDBN} commands, you can tell the
|
| -@value{GDBN} type checker to skip checking;
|
| +For the expressions you use in @value{GDBN} commands, you can tell
|
| +@value{GDBN} to not enforce strict type checking or
|
| to treat any mismatches as errors and abandon the expression;
|
| -or to only issue warnings when type mismatches occur,
|
| -but evaluate the expression anyway. When you choose the last of
|
| -these, @value{GDBN} evaluates expressions like the second example above, but
|
| -also issues a warning.
|
| +When type checking is disabled, @value{GDBN} successfully evaluates
|
| +expressions like the second example above.
|
|
|
| -Even if you turn type checking off, there may be other reasons
|
| +Even if type checking is off, there may be other reasons
|
| related to type that prevent @value{GDBN} from evaluating an expression.
|
| For instance, @value{GDBN} does not know how to add an @code{int} and
|
| a @code{struct foo}. These particular type errors have nothing to do
|
| -with the language in use, and usually arise from expressions, such as
|
| -the one described above, which make little sense to evaluate anyway.
|
| +with the language in use and usually arise from expressions which make
|
| +little sense to evaluate anyway.
|
|
|
| -Each language defines to what degree it is strict about type. For
|
| -instance, both Modula-2 and C require the arguments to arithmetical
|
| -operators to be numbers. In C, enumerated types and pointers can be
|
| -represented as numbers, so that they are valid arguments to mathematical
|
| -operators. @xref{Supported Languages, ,Supported Languages}, for further
|
| -details on specific languages.
|
| -
|
| -@value{GDBN} provides some additional commands for controlling the type checker:
|
| +@value{GDBN} provides some additional commands for controlling type checking:
|
|
|
| @kindex set check type
|
| @kindex show check type
|
| @table @code
|
| -@item set check type auto
|
| -Set type checking on or off based on the current working language.
|
| -@xref{Supported Languages, ,Supported Languages}, for the default settings for
|
| -each language.
|
| -
|
| @item set check type on
|
| @itemx set check type off
|
| -Set type checking on or off, overriding the default setting for the
|
| -current working language. Issue a warning if the setting does not
|
| -match the language default. If any type mismatches occur in
|
| +Set strict type checking on or off. If any type mismatches occur in
|
| evaluating an expression while type checking is on, @value{GDBN} prints a
|
| message and aborts evaluation of the expression.
|
|
|
| -@item set check type warn
|
| -Cause the type checker to issue warnings, but to always attempt to
|
| -evaluate the expression. Evaluating the expression may still
|
| -be impossible for other reasons. For example, @value{GDBN} cannot add
|
| -numbers and structures.
|
| -
|
| -@item show type
|
| -Show the current setting of the type checker, and whether or not @value{GDBN}
|
| -is setting it automatically.
|
| +@item show check type
|
| +Show the current setting of type checking and whether @value{GDBN}
|
| +is enforcing strict type checking rules.
|
| @end table
|
|
|
| @cindex range checking
|
| @@ -13179,8 +13940,8 @@ specification.
|
|
|
| @cindex C and C@t{++} defaults
|
|
|
| -If you allow @value{GDBN} to set type and range checking automatically, they
|
| -both default to @code{off} whenever the working language changes to
|
| +If you allow @value{GDBN} to set range checking automatically, it
|
| +defaults to @code{off} whenever the working language changes to
|
| C or C@t{++}. This happens regardless of whether you or @value{GDBN}
|
| selects the working language.
|
|
|
| @@ -13191,37 +13952,15 @@ these files, it sets the working language to C or C@t{++}.
|
| @xref{Automatically, ,Having @value{GDBN} Infer the Source Language},
|
| for further details.
|
|
|
| -@c Type checking is (a) primarily motivated by Modula-2, and (b)
|
| -@c unimplemented. If (b) changes, it might make sense to let this node
|
| -@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
|
| -
|
| @node C Checks
|
| @subsubsection C and C@t{++} Type and Range Checks
|
|
|
| @cindex C and C@t{++} checks
|
|
|
| -By default, when @value{GDBN} parses C or C@t{++} expressions, type checking
|
| -is not used. However, if you turn type checking on, @value{GDBN}
|
| -considers two variables type equivalent if:
|
| -
|
| -@itemize @bullet
|
| -@item
|
| -The two variables are structured and have the same structure, union, or
|
| -enumerated tag.
|
| -
|
| -@item
|
| -The two variables have the same type name, or types that have been
|
| -declared equivalent through @code{typedef}.
|
| -
|
| -@ignore
|
| -@c leaving this out because neither J Gilmore nor R Pesch understand it.
|
| -@c FIXME--beers?
|
| -@item
|
| -The two @code{struct}, @code{union}, or @code{enum} variables are
|
| -declared in the same declaration. (Note: this may not be true for all C
|
| -compilers.)
|
| -@end ignore
|
| -@end itemize
|
| +By default, when @value{GDBN} parses C or C@t{++} expressions, strict type
|
| +checking is used. However, if you turn type checking off, @value{GDBN}
|
| +will allow certain non-standard conversions, such as promoting integer
|
| +constants to pointers.
|
|
|
| Range checking, if turned on, is done on mathematical operations. Array
|
| indices are not checked, since they are often used to index a pointer
|
| @@ -13264,6 +14003,7 @@ classes.
|
|
|
| @cindex C@t{++} exception handling
|
| @item catch throw
|
| +@itemx catch rethrow
|
| @itemx catch catch
|
| Debug C@t{++} exception handling using these commands. @xref{Set
|
| Catchpoints, , Setting Catchpoints}.
|
| @@ -13344,8 +14084,8 @@ specified by the extension to support decimal floating-point arithmetic.
|
|
|
| There are two encodings in use, depending on the architecture: BID (Binary
|
| Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
|
| -PowerPC. @value{GDBN} will use the appropriate encoding for the configured
|
| -target.
|
| +PowerPC and S/390. @value{GDBN} will use the appropriate encoding for the
|
| +configured target.
|
|
|
| Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
|
| to manipulate decimal floating point numbers, it is not possible to convert
|
| @@ -14270,6 +15010,7 @@ to be difficult.
|
| * Omissions from Ada:: Restrictions on the Ada expression syntax.
|
| * Additions to Ada:: Extensions of the Ada expression syntax.
|
| * Stopping Before Main Program:: Debugging the program during elaboration.
|
| +* Ada Exceptions:: Ada Exceptions
|
| * Ada Tasks:: Listing and setting breakpoints in tasks.
|
| * Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
|
| * Ravenscar Profile:: Tasking Support when using the Ravenscar
|
| @@ -14594,6 +15335,42 @@ Manual, the elaboration code is invoked from a procedure called
|
| elaboration, simply use the following two commands:
|
| @code{tbreak adainit} and @code{run}.
|
|
|
| +@node Ada Exceptions
|
| +@subsubsection Ada Exceptions
|
| +
|
| +A command is provided to list all Ada exceptions:
|
| +
|
| +@table @code
|
| +@kindex info exceptions
|
| +@item info exceptions
|
| +@itemx info exceptions @var{regexp}
|
| +The @code{info exceptions} command allows you to list all Ada exceptions
|
| +defined within the program being debugged, as well as their addresses.
|
| +With a regular expression, @var{regexp}, as argument, only those exceptions
|
| +whose names match @var{regexp} are listed.
|
| +@end table
|
| +
|
| +Below is a small example, showing how the command can be used, first
|
| +without argument, and next with a regular expression passed as an
|
| +argument.
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) info exceptions
|
| +All defined Ada exceptions:
|
| +constraint_error: 0x613da0
|
| +program_error: 0x613d20
|
| +storage_error: 0x613ce0
|
| +tasking_error: 0x613ca0
|
| +const.aint_global_e: 0x613b00
|
| +(@value{GDBP}) info exceptions const.aint
|
| +All Ada exceptions matching regular expression "const.aint":
|
| +constraint_error: 0x613da0
|
| +const.aint_global_e: 0x613b00
|
| +@end smallexample
|
| +
|
| +It is also possible to ask @value{GDBN} to stop your program's execution
|
| +when an exception is raised. For more details, see @ref{Set Catchpoints}.
|
| +
|
| @node Ada Tasks
|
| @subsubsection Extensions for Ada Tasks
|
| @cindex Ada, tasking
|
| @@ -14991,6 +15768,42 @@ case-insensitive matches.
|
| This command shows the current setting of case sensitivity for symbols
|
| lookups.
|
|
|
| +@kindex set print type methods
|
| +@item set print type methods
|
| +@itemx set print type methods on
|
| +@itemx set print type methods off
|
| +Normally, when @value{GDBN} prints a class, it displays any methods
|
| +declared in that class. You can control this behavior either by
|
| +passing the appropriate flag to @code{ptype}, or using @command{set
|
| +print type methods}. Specifying @code{on} will cause @value{GDBN} to
|
| +display the methods; this is the default. Specifying @code{off} will
|
| +cause @value{GDBN} to omit the methods.
|
| +
|
| +@kindex show print type methods
|
| +@item show print type methods
|
| +This command shows the current setting of method display when printing
|
| +classes.
|
| +
|
| +@kindex set print type typedefs
|
| +@item set print type typedefs
|
| +@itemx set print type typedefs on
|
| +@itemx set print type typedefs off
|
| +
|
| +Normally, when @value{GDBN} prints a class, it displays any typedefs
|
| +defined in that class. You can control this behavior either by
|
| +passing the appropriate flag to @code{ptype}, or using @command{set
|
| +print type typedefs}. Specifying @code{on} will cause @value{GDBN} to
|
| +display the typedef definitions; this is the default. Specifying
|
| +@code{off} will cause @value{GDBN} to omit the typedef definitions.
|
| +Note that this controls whether the typedef definition itself is
|
| +printed, not whether typedef names are substituted when printing other
|
| +types.
|
| +
|
| +@kindex show print type typedefs
|
| +@item show print type typedefs
|
| +This command shows the current setting of typedef display when
|
| +printing classes.
|
| +
|
| @kindex info address
|
| @cindex address of a symbol
|
| @item info address @var{symbol}
|
| @@ -15031,7 +15844,7 @@ __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
|
| @end smallexample
|
|
|
| @kindex whatis
|
| -@item whatis [@var{arg}]
|
| +@item whatis[/@var{flags}] [@var{arg}]
|
| Print the data type of @var{arg}, which can be either an expression
|
| or a name of a data type. With no argument, print the data type of
|
| @code{$}, the last value in the value history.
|
| @@ -15061,8 +15874,34 @@ For C code, the type names may also have the form @samp{class
|
| @var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
|
| @var{union-tag}} or @samp{enum @var{enum-tag}}.
|
|
|
| +@var{flags} can be used to modify how the type is displayed.
|
| +Available flags are:
|
| +
|
| +@table @code
|
| +@item r
|
| +Display in ``raw'' form. Normally, @value{GDBN} substitutes template
|
| +parameters and typedefs defined in a class when printing the class'
|
| +members. The @code{/r} flag disables this.
|
| +
|
| +@item m
|
| +Do not print methods defined in the class.
|
| +
|
| +@item M
|
| +Print methods defined in the class. This is the default, but the flag
|
| +exists in case you change the default with @command{set print type methods}.
|
| +
|
| +@item t
|
| +Do not print typedefs defined in the class. Note that this controls
|
| +whether the typedef definition itself is printed, not whether typedef
|
| +names are substituted when printing other types.
|
| +
|
| +@item T
|
| +Print typedefs defined in the class. This is the default, but the flag
|
| +exists in case you change the default with @command{set print type typedefs}.
|
| +@end table
|
| +
|
| @kindex ptype
|
| -@item ptype [@var{arg}]
|
| +@item ptype[/@var{flags}] [@var{arg}]
|
| @code{ptype} accepts the same arguments as @code{whatis}, but prints a
|
| detailed description of the type, instead of just the name of the type.
|
| @xref{Expressions, ,Expressions}.
|
| @@ -15157,6 +15996,22 @@ This command differs from @code{ptype} in two ways: first, like
|
| @code{whatis}, it does not print a detailed description; second, it
|
| lists all source files where a type is defined.
|
|
|
| +@kindex info type-printers
|
| +@item info type-printers
|
| +Versions of @value{GDBN} that ship with Python scripting enabled may
|
| +have ``type printers'' available. When using @command{ptype} or
|
| +@command{whatis}, these printers are consulted when the name of a type
|
| +is needed. @xref{Type Printing API}, for more information on writing
|
| +type printers.
|
| +
|
| +@code{info type-printers} displays all the available type printers.
|
| +
|
| +@kindex enable type-printer
|
| +@kindex disable type-printer
|
| +@item enable type-printer @var{name}@dots{}
|
| +@item disable type-printer @var{name}@dots{}
|
| +These commands can be used to enable or disable type printers.
|
| +
|
| @kindex info scope
|
| @cindex local variables
|
| @item info scope @var{location}
|
| @@ -15290,6 +16145,8 @@ Show whether opaque types are resolved or not.
|
| @cindex symbol dump
|
| @kindex maint print psymbols
|
| @cindex partial symbol dump
|
| +@kindex maint print msymbols
|
| +@cindex minimal symbol dump
|
| @item maint print symbols @var{filename}
|
| @itemx maint print psymbols @var{filename}
|
| @itemx maint print msymbols @var{filename}
|
| @@ -15506,8 +16363,11 @@ an address of your own choosing, with the following commands:
|
|
|
| @table @code
|
| @kindex jump
|
| +@kindex j @r{(@code{jump})}
|
| @item jump @var{linespec}
|
| +@itemx j @var{linespec}
|
| @itemx jump @var{location}
|
| +@itemx j @var{location}
|
| Resume execution at line @var{linespec} or at address given by
|
| @var{location}. Execution stops again immediately if there is a
|
| breakpoint there. @xref{Specify Location}, for a description of the
|
| @@ -15562,7 +16422,7 @@ SIGINT} are both ways of sending an interrupt signal.
|
|
|
| Alternatively, if @var{signal} is zero, continue execution without
|
| giving a signal. This is useful when your program stopped on account of
|
| -a signal and would ordinary see the signal when resumed with the
|
| +a signal and would ordinarily see the signal when resumed with the
|
| @code{continue} command; @samp{signal 0} causes it to resume without a
|
| signal.
|
|
|
| @@ -15785,6 +16645,7 @@ program. To debug a core dump of a previous run, you must also tell
|
| @menu
|
| * Files:: Commands to specify files
|
| * Separate Debug Files:: Debugging information in separate files
|
| +* MiniDebugInfo:: Debugging information in a special section
|
| * Index Files:: Index files speed up GDB
|
| * Symbol Errors:: Errors reading symbol files
|
| * Data Files:: GDB data files
|
| @@ -15941,8 +16802,9 @@ section name and base address for that section. You can specify any
|
| The symbol table of the file @var{filename} is added to the symbol table
|
| originally read with the @code{symbol-file} command. You can use the
|
| @code{add-symbol-file} command any number of times; the new symbol data
|
| -thus read keeps adding to the old. To discard all old symbol data
|
| -instead, use the @code{symbol-file} command without any arguments.
|
| +thus read is kept in addition to the old.
|
| +
|
| +Changes can be reverted using the command @code{remove-symbol-file}.
|
|
|
| @cindex relocatable object files, reading symbols from
|
| @cindex object files, relocatable, reading symbols from
|
| @@ -15980,6 +16842,27 @@ way.
|
|
|
| @code{add-symbol-file} does not repeat if you press @key{RET} after using it.
|
|
|
| +@kindex remove-symbol-file
|
| +@item remove-symbol-file @var{filename}
|
| +@item remove-symbol-file -a @var{address}
|
| +Remove a symbol file added via the @code{add-symbol-file} command. The
|
| +file to remove can be identified by its @var{filename} or by an @var{address}
|
| +that lies within the boundaries of this symbol file in memory. Example:
|
| +
|
| +@smallexample
|
| +(gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
|
| +add symbol table from file "/home/user/gdb/mylib.so" at
|
| + .text_addr = 0x7ffff7ff9480
|
| +(y or n) y
|
| +Reading symbols from /home/user/gdb/mylib.so...done.
|
| +(gdb) remove-symbol-file -a 0x7ffff7ff9480
|
| +Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
|
| +(gdb)
|
| +@end smallexample
|
| +
|
| +
|
| +@code{remove-symbol-file} does not repeat if you press @key{RET} after using it.
|
| +
|
| @kindex add-symbol-file-from-memory
|
| @cindex @code{syscall DSO}
|
| @cindex load symbols from memory
|
| @@ -16710,6 +17593,63 @@ gnu_debuglink_crc32 (unsigned long crc,
|
| @noindent
|
| This computation does not apply to the ``build ID'' method.
|
|
|
| +@node MiniDebugInfo
|
| +@section Debugging information in a special section
|
| +@cindex separate debug sections
|
| +@cindex @samp{.gnu_debugdata} section
|
| +
|
| +Some systems ship pre-built executables and libraries that have a
|
| +special @samp{.gnu_debugdata} section. This feature is called
|
| +@dfn{MiniDebugInfo}. This section holds an LZMA-compressed object and
|
| +is used to supply extra symbols for backtraces.
|
| +
|
| +The intent of this section is to provide extra minimal debugging
|
| +information for use in simple backtraces. It is not intended to be a
|
| +replacement for full separate debugging information (@pxref{Separate
|
| +Debug Files}). The example below shows the intended use; however,
|
| +@value{GDBN} does not currently put restrictions on what sort of
|
| +debugging information might be included in the section.
|
| +
|
| +@value{GDBN} has support for this extension. If the section exists,
|
| +then it is used provided that no other source of debugging information
|
| +can be found, and that @value{GDBN} was configured with LZMA support.
|
| +
|
| +This section can be easily created using @command{objcopy} and other
|
| +standard utilities:
|
| +
|
| +@smallexample
|
| +# Extract the dynamic symbols from the main binary, there is no need
|
| +# to also have these in the normal symbol table.
|
| +nm -D @var{binary} --format=posix --defined-only \
|
| + | awk '@{ print $1 @}' | sort > dynsyms
|
| +
|
| +# Extract all the text (i.e. function) symbols from the debuginfo.
|
| +# (Note that we actually also accept "D" symbols, for the benefit
|
| +# of platforms like PowerPC64 that use function descriptors.)
|
| +nm @var{binary} --format=posix --defined-only \
|
| + | awk '@{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 @}' \
|
| + | sort > funcsyms
|
| +
|
| +# Keep all the function symbols not already in the dynamic symbol
|
| +# table.
|
| +comm -13 dynsyms funcsyms > keep_symbols
|
| +
|
| +# Separate full debug info into debug binary.
|
| +objcopy --only-keep-debug @var{binary} debug
|
| +
|
| +# Copy the full debuginfo, keeping only a minimal set of symbols and
|
| +# removing some unnecessary sections.
|
| +objcopy -S --remove-section .gdb_index --remove-section .comment \
|
| + --keep-symbols=keep_symbols debug mini_debuginfo
|
| +
|
| +# Drop the full debug info from the original binary.
|
| +strip --strip-all -R .comment @var{binary}
|
| +
|
| +# Inject the compressed data into the .gnu_debugdata section of the
|
| +# original binary.
|
| +xz mini_debuginfo
|
| +objcopy --add-section .gnu_debugdata=mini_debuginfo.xz @var{binary}
|
| +@end smallexample
|
|
|
| @node Index Files
|
| @section Index Files Speed Up @value{GDBN}
|
| @@ -17011,7 +17951,7 @@ you must know the actual BFD name.
|
| Use the @code{show gnutarget} command to display what file format
|
| @code{gnutarget} is set to read. If you have not set @code{gnutarget},
|
| @value{GDBN} will determine the file format for each file automatically,
|
| -and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
|
| +and @code{show gnutarget} displays @samp{The current BFD target is "auto"}.
|
| @end table
|
|
|
| @cindex common targets
|
| @@ -17066,16 +18006,6 @@ Processors}.
|
|
|
| @end table
|
|
|
| -Some configurations may include these targets as well:
|
| -
|
| -@table @code
|
| -
|
| -@item target nrom @var{dev}
|
| -@cindex NetROM ROM emulator target
|
| -NetROM ROM emulator. This target only supports downloading.
|
| -
|
| -@end table
|
| -
|
| Different targets are available on different configurations of @value{GDBN};
|
| your configuration may have more or fewer targets.
|
|
|
| @@ -17228,8 +18158,8 @@ target remote /dev/ttyb
|
| @end smallexample
|
|
|
| If you're using a serial line, you may want to give @value{GDBN} the
|
| -@w{@samp{--baud}} option, or use the @code{set remotebaud} command
|
| -(@pxref{Remote Configuration, set remotebaud}) before the
|
| +@samp{--baud} option, or use the @code{set serial baud} command
|
| +(@pxref{Remote Configuration, set serial baud}) before the
|
| @code{target} command.
|
|
|
| @item target remote @code{@var{host}:@var{port}}
|
| @@ -17554,7 +18484,7 @@ completeness, at most one @value{GDBN} can be connected at a time.
|
|
|
| @cindex @option{--once}, @code{gdbserver} option
|
| By default, @code{gdbserver} keeps the listening TCP port open, so that
|
| -additional connections are possible. However, if you start @code{gdbserver}
|
| +subsequent connections are possible. However, if you start @code{gdbserver}
|
| with the @option{--once} option, it will stop listening for any further
|
| connection attempts after connecting to the first @value{GDBN} session. This
|
| means no further connections to @code{gdbserver} will be possible after the
|
| @@ -17771,13 +18701,13 @@ default value is the number of bits in the target's address.
|
| @item show remoteaddresssize
|
| Show the current value of remote address size in bits.
|
|
|
| -@item set remotebaud @var{n}
|
| +@item set serial baud @var{n}
|
| @cindex baud rate for remote targets
|
| Set the baud rate for the remote serial I/O to @var{n} baud. The
|
| value is used to set the speed of the serial port used for debugging
|
| remote targets.
|
|
|
| -@item show remotebaud
|
| +@item show serial baud
|
| Show the current speed of the remote connection.
|
|
|
| @item set remotebreak
|
| @@ -17910,13 +18840,16 @@ Do not auto-retry failed TCP connections.
|
| Show the current auto-retry setting.
|
|
|
| @item set tcp connect-timeout @var{seconds}
|
| +@itemx set tcp connect-timeout unlimited
|
| @cindex connection timeout, for remote TCP target
|
| @cindex timeout, for remote target connection
|
| Set the timeout for establishing a TCP connection to the remote target to
|
| @var{seconds}. The timeout affects both polling to retry failed connections
|
| (enabled by @code{set tcp auto-retry on}) and waiting for connections
|
| that are merely slow to complete, and represents an approximate cumulative
|
| -value.
|
| +value. If @var{seconds} is @code{unlimited}, there is no timeout and
|
| +@value{GDBN} will keep attempting to establish a connection forever,
|
| +unless interrupted with @kbd{Ctrl-c}. The default is 15 seconds.
|
|
|
| @item show tcp connect-timeout
|
| Show the current connection timeout setting.
|
| @@ -18094,6 +19027,14 @@ are:
|
| @tab @code{qAttached}
|
| @tab Querying remote process attach state.
|
|
|
| +@item @code{trace-buffer-size}
|
| +@tab @code{QTBuffer:size}
|
| +@tab @code{set trace-buffer-size}
|
| +
|
| +@item @code{trace-status}
|
| +@tab @code{qTStatus}
|
| +@tab @code{tstatus}
|
| +
|
| @item @code{traceframe-info}
|
| @tab @code{qXfer:traceframe-info:read}
|
| @tab Traceframe info
|
| @@ -18460,7 +19401,6 @@ configurations.
|
| * DJGPP Native:: Features specific to the DJGPP port
|
| * Cygwin Native:: Features specific to the Cygwin port
|
| * Hurd Native:: Features specific to @sc{gnu} Hurd
|
| -* Neutrino:: Features specific to QNX Neutrino
|
| * Darwin:: Features specific to Darwin
|
| @end menu
|
|
|
| @@ -18520,13 +19460,17 @@ modern FreeBSD systems.
|
|
|
| Many versions of SVR4 and compatible systems provide a facility called
|
| @samp{/proc} that can be used to examine the image of a running
|
| -process using file-system subroutines. If @value{GDBN} is configured
|
| -for an operating system with this facility, the command @code{info
|
| -proc} is available to report information about the process running
|
| -your program, or about any process running on your system. @code{info
|
| -proc} works only on SVR4 systems that include the @code{procfs} code.
|
| -This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital
|
| -Unix), Solaris, Irix, and Unixware, but not HP-UX, for example.
|
| +process using file-system subroutines.
|
| +
|
| +If @value{GDBN} is configured for an operating system with this
|
| +facility, the command @code{info proc} is available to report
|
| +information about the process running your program, or about any
|
| +process running on your system. This includes, as of this writing,
|
| +@sc{gnu}/Linux, OSF/1 (Digital Unix), Solaris, and Irix, but
|
| +not HP-UX, for example.
|
| +
|
| +This command may also work on core files that were created on a system
|
| +that has the @samp{/proc} facility.
|
|
|
| @table @code
|
| @kindex info proc
|
| @@ -18547,6 +19491,21 @@ a thread from the process being debugged (the leading @samp{/} still
|
| needs to be present, or else @value{GDBN} will interpret the number as
|
| a process ID rather than a thread ID).
|
|
|
| +@item info proc cmdline
|
| +@cindex info proc cmdline
|
| +Show the original command line of the process. This command is
|
| +specific to @sc{gnu}/Linux.
|
| +
|
| +@item info proc cwd
|
| +@cindex info proc cwd
|
| +Show the current working directory of the process. This command is
|
| +specific to @sc{gnu}/Linux.
|
| +
|
| +@item info proc exe
|
| +@cindex info proc exe
|
| +Show the name of executable of the process. This command is specific
|
| +to @sc{gnu}/Linux.
|
| +
|
| @item info proc mappings
|
| @cindex memory address space mappings
|
| Report the memory address space ranges accessible in the program, with
|
| @@ -19239,25 +20198,6 @@ threads; you can then change the properties of individual threads with
|
| the non-default commands.
|
| @end table
|
|
|
| -
|
| -@node Neutrino
|
| -@subsection QNX Neutrino
|
| -@cindex QNX Neutrino
|
| -
|
| -@value{GDBN} provides the following commands specific to the QNX
|
| -Neutrino target:
|
| -
|
| -@table @code
|
| -@item set debug nto-debug
|
| -@kindex set debug nto-debug
|
| -When set to on, enables debugging messages specific to the QNX
|
| -Neutrino support.
|
| -
|
| -@item show debug nto-debug
|
| -@kindex show debug nto-debug
|
| -Show the current state of QNX Neutrino messages.
|
| -@end table
|
| -
|
| @node Darwin
|
| @subsection Darwin
|
| @cindex Darwin
|
| @@ -19502,7 +20442,6 @@ acceptable commands.
|
| * M68K:: Motorola M68K
|
| * MicroBlaze:: Xilinx MicroBlaze
|
| * MIPS Embedded:: MIPS Embedded
|
| -* OpenRISC 1000:: OpenRisc 1000
|
| * PowerPC Embedded:: PowerPC Embedded
|
| * PA:: HP PA Embedded
|
| * Sparclet:: Tsqware Sparclet
|
| @@ -19976,120 +20915,6 @@ This command allows sending an arbitrary @var{command} string to the
|
| monitor. The monitor must be in debug mode for this to work.
|
| @end table
|
|
|
| -@node OpenRISC 1000
|
| -@subsection OpenRISC 1000
|
| -@cindex OpenRISC 1000
|
| -
|
| -@cindex or1k boards
|
| -See OR1k Architecture document (@uref{www.opencores.org}) for more information
|
| -about platform and commands.
|
| -
|
| -@table @code
|
| -
|
| -@kindex target jtag
|
| -@item target jtag jtag://@var{host}:@var{port}
|
| -
|
| -Connects to remote JTAG server.
|
| -JTAG remote server can be either an or1ksim or JTAG server,
|
| -connected via parallel port to the board.
|
| -
|
| -Example: @code{target jtag jtag://localhost:9999}
|
| -
|
| -@kindex or1ksim
|
| -@item or1ksim @var{command}
|
| -If connected to @code{or1ksim} OpenRISC 1000 Architectural
|
| -Simulator, proprietary commands can be executed.
|
| -
|
| -@kindex info or1k spr
|
| -@item info or1k spr
|
| -Displays spr groups.
|
| -
|
| -@item info or1k spr @var{group}
|
| -@itemx info or1k spr @var{groupno}
|
| -Displays register names in selected group.
|
| -
|
| -@item info or1k spr @var{group} @var{register}
|
| -@itemx info or1k spr @var{register}
|
| -@itemx info or1k spr @var{groupno} @var{registerno}
|
| -@itemx info or1k spr @var{registerno}
|
| -Shows information about specified spr register.
|
| -
|
| -@kindex spr
|
| -@item spr @var{group} @var{register} @var{value}
|
| -@itemx spr @var{register @var{value}}
|
| -@itemx spr @var{groupno} @var{registerno @var{value}}
|
| -@itemx spr @var{registerno @var{value}}
|
| -Writes @var{value} to specified spr register.
|
| -@end table
|
| -
|
| -Some implementations of OpenRISC 1000 Architecture also have hardware trace.
|
| -It is very similar to @value{GDBN} trace, except it does not interfere with normal
|
| -program execution and is thus much faster. Hardware breakpoints/watchpoint
|
| -triggers can be set using:
|
| -@table @code
|
| -@item $LEA/$LDATA
|
| -Load effective address/data
|
| -@item $SEA/$SDATA
|
| -Store effective address/data
|
| -@item $AEA/$ADATA
|
| -Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA)
|
| -@item $FETCH
|
| -Fetch data
|
| -@end table
|
| -
|
| -When triggered, it can capture low level data, like: @code{PC}, @code{LSEA},
|
| -@code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}.
|
| -
|
| -@code{htrace} commands:
|
| -@cindex OpenRISC 1000 htrace
|
| -@table @code
|
| -@kindex hwatch
|
| -@item hwatch @var{conditional}
|
| -Set hardware watchpoint on combination of Load/Store Effective Address(es)
|
| -or Data. For example:
|
| -
|
| -@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
|
| -
|
| -@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
|
| -
|
| -@kindex htrace
|
| -@item htrace info
|
| -Display information about current HW trace configuration.
|
| -
|
| -@item htrace trigger @var{conditional}
|
| -Set starting criteria for HW trace.
|
| -
|
| -@item htrace qualifier @var{conditional}
|
| -Set acquisition qualifier for HW trace.
|
| -
|
| -@item htrace stop @var{conditional}
|
| -Set HW trace stopping criteria.
|
| -
|
| -@item htrace record [@var{data}]*
|
| -Selects the data to be recorded, when qualifier is met and HW trace was
|
| -triggered.
|
| -
|
| -@item htrace enable
|
| -@itemx htrace disable
|
| -Enables/disables the HW trace.
|
| -
|
| -@item htrace rewind [@var{filename}]
|
| -Clears currently recorded trace data.
|
| -
|
| -If filename is specified, new trace file is made and any newly collected data
|
| -will be written there.
|
| -
|
| -@item htrace print [@var{start} [@var{len}]]
|
| -Prints trace buffer, using current record configuration.
|
| -
|
| -@item htrace mode continuous
|
| -Set continuous trace mode.
|
| -
|
| -@item htrace mode suspend
|
| -Set suspend trace mode.
|
| -
|
| -@end table
|
| -
|
| @node PowerPC Embedded
|
| @subsection PowerPC Embedded
|
|
|
| @@ -20491,13 +21316,6 @@ For the Renesas Super-H processor, @value{GDBN} provides these
|
| commands:
|
|
|
| @table @code
|
| -@item regs
|
| -@kindex regs@r{, Super-H}
|
| -This command is deprecated, and @code{info all-registers} should be
|
| -used instead.
|
| -
|
| -Show the values of all Super-H registers.
|
| -
|
| @item set sh calling-convention @var{convention}
|
| @kindex set sh calling-convention
|
| Set the calling-convention used when calling functions from @value{GDBN}.
|
| @@ -20525,14 +21343,34 @@ This section describes characteristics of architectures that affect
|
| all uses of @value{GDBN} with the architecture, both native and cross.
|
|
|
| @menu
|
| +* AArch64::
|
| * i386::
|
| * Alpha::
|
| * MIPS::
|
| * HPPA:: HP PA architecture
|
| * SPU:: Cell Broadband Engine SPU architecture
|
| * PowerPC::
|
| +* Nios II::
|
| @end menu
|
|
|
| +@node AArch64
|
| +@subsection AArch64
|
| +@cindex AArch64 support
|
| +
|
| +When @value{GDBN} is debugging the AArch64 architecture, it provides the
|
| +following special commands:
|
| +
|
| +@table @code
|
| +@item set debug aarch64
|
| +@kindex set debug aarch64
|
| +This command determines whether AArch64 architecture-specific debugging
|
| +messages are to be displayed.
|
| +
|
| +@item show debug aarch64
|
| +Show whether AArch64 debugging messages are displayed.
|
| +
|
| +@end table
|
| +
|
| @node i386
|
| @subsection x86 Architecture-specific Issues
|
|
|
| @@ -20555,6 +21393,39 @@ Show the current setting of the convention to return @code{struct}s
|
| from functions.
|
| @end table
|
|
|
| +@subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX).
|
| +@cindex Intel(R) Memory Protection Extensions (MPX).
|
| +
|
| +Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
|
| +@footnote{The register named with capital letters represent the architecture
|
| +registers.} through @samp{BND3}. Bound registers store a pair of 64-bit values
|
| +which are the lower bound and upper bound. Bounds are effective addresses or
|
| +memory locations. The upper bounds are architecturally represented in 1's
|
| +complement form. A bound having lower bound = 0, and upper bound = 0
|
| +(1's complement of all bits set) will allow access to the entire address space.
|
| +
|
| +@samp{BND0} through @samp{BND3} are represented in @value{GDBN} as @samp{bnd0raw}
|
| +through @samp{bnd3raw}. Pseudo registers @samp{bnd0} through @samp{bnd3}
|
| +display the upper bound performing the complement of one operation on the
|
| +upper bound value, i.e.@ when upper bound in @samp{bnd0raw} is 0 in the
|
| +@value{GDBN} @samp{bnd0} it will be @code{0xfff@dots{}}. In this sense it
|
| +can also be noted that the upper bounds are inclusive.
|
| +
|
| +As an example, assume that the register BND0 holds bounds for a pointer having
|
| +access allowed for the range between 0x32 and 0x71. The values present on
|
| +bnd0raw and bnd registers are presented as follows:
|
| +
|
| +@smallexample
|
| + bnd0raw = @{0x32, 0xffffffff8e@}
|
| + bnd0 = @{lbound = 0x32, ubound = 0x71@} : size 64
|
| +@end smallexample
|
| +
|
| +This way the raw value can be accessed via bnd0raw@dots{}bnd3raw. Any
|
| +change on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its
|
| +counterpart. When the bnd0@dots{}bnd3 registers are displayed via
|
| +Python, the display includes the memory size, in bits, accessible to
|
| +the pointer.
|
| +
|
| @node Alpha
|
| @subsection Alpha
|
|
|
| @@ -20796,6 +21667,24 @@ by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0},
|
| For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit
|
| wide Extended Floating Point Registers (@samp{f32} through @samp{f63}).
|
|
|
| +@node Nios II
|
| +@subsection Nios II
|
| +@cindex Nios II architecture
|
| +
|
| +When @value{GDBN} is debugging the Nios II architecture,
|
| +it provides the following special commands:
|
| +
|
| +@table @code
|
| +
|
| +@item set debug nios2
|
| +@kindex set debug nios2
|
| +This command turns on and off debugging messages for the Nios II
|
| +target code in @value{GDBN}.
|
| +
|
| +@item show debug nios2
|
| +@kindex show debug nios2
|
| +Show the current setting of Nios II debugging messages.
|
| +@end table
|
|
|
| @node Controlling GDB
|
| @chapter Controlling @value{GDBN}
|
| @@ -20976,9 +21865,12 @@ Stop recording command history in a file.
|
| @kindex set history size
|
| @cindex @env{HISTSIZE}, environment variable
|
| @item set history size @var{size}
|
| +@itemx set history size unlimited
|
| Set the number of commands which @value{GDBN} keeps in its history list.
|
| This defaults to the value of the environment variable
|
| -@code{HISTSIZE}, or to 256 if this variable is not set.
|
| +@code{HISTSIZE}, or to 256 if this variable is not set. If @var{size}
|
| +is @code{unlimited}, the number of commands @value{GDBN} keeps in the
|
| +history list is unlimited.
|
| @end table
|
|
|
| History expansion assigns special meaning to the character @kbd{!}.
|
| @@ -21063,25 +21955,28 @@ width} commands:
|
| @kindex show width
|
| @kindex show height
|
| @item set height @var{lpp}
|
| +@itemx set height unlimited
|
| @itemx show height
|
| @itemx set width @var{cpl}
|
| +@itemx set width unlimited
|
| @itemx show width
|
| These @code{set} commands specify a screen height of @var{lpp} lines and
|
| a screen width of @var{cpl} characters. The associated @code{show}
|
| commands display the current settings.
|
|
|
| -If you specify a height of zero lines, @value{GDBN} does not pause during
|
| -output no matter how long the output is. This is useful if output is to a
|
| -file or to an editor buffer.
|
| +If you specify a height of either @code{unlimited} or zero lines,
|
| +@value{GDBN} does not pause during output no matter how long the
|
| +output is. This is useful if output is to a file or to an editor
|
| +buffer.
|
|
|
| -Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
|
| -from wrapping its output.
|
| +Likewise, you can specify @samp{set width unlimited} or @samp{set
|
| +width 0} to prevent @value{GDBN} from wrapping its output.
|
|
|
| @item set pagination on
|
| @itemx set pagination off
|
| @kindex set pagination
|
| Turn the output pagination on or off; the default is on. Turning
|
| -pagination off is the alternative to @code{set height 0}. Note that
|
| +pagination off is the alternative to @code{set height unlimited}. Note that
|
| running @value{GDBN} with the @option{--batch} option (@pxref{Mode
|
| Options, -batch}) also automatically disables pagination.
|
|
|
| @@ -21162,6 +22057,7 @@ current ABI.
|
| @cindex OS ABI
|
| @kindex set osabi
|
| @kindex show osabi
|
| +@cindex Newlib OS ABI and its influence on the longjmp handling
|
|
|
| One @value{GDBN} configuration can debug binaries for multiple operating
|
| system targets, either via remote debugging or native emulation.
|
| @@ -21172,6 +22068,11 @@ an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does
|
| not have the same identifying marks that the standard C library for your
|
| platform provides.
|
|
|
| +When @value{GDBN} is debugging the AArch64 architecture, it provides a
|
| +``Newlib'' OS ABI. This is useful for handling @code{setjmp} and
|
| +@code{longjmp} when debugging binaries that use the @sc{newlib} C library.
|
| +The ``Newlib'' OS ABI can be selected by @code{set osabi Newlib}.
|
| +
|
| @table @code
|
| @item show osabi
|
| Show the OS ABI currently in use.
|
| @@ -21514,6 +22415,14 @@ warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been
|
| to "$debugdir:$datadir/auto-load".
|
| @end smallexample
|
|
|
| +@noindent
|
| +To instruct @value{GDBN} to go ahead and use the init files anyway,
|
| +invoke @value{GDBN} like this:
|
| +
|
| +@smallexample
|
| +$ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb
|
| +@end smallexample
|
| +
|
| The list of trusted directories is controlled by the following commands:
|
|
|
| @table @code
|
| @@ -21762,13 +22671,26 @@ asynchronous command finishes its execution. The default is off.
|
| Displays the current setting of asynchronous command completion
|
| notification.
|
| @kindex set debug
|
| +@cindex ARM AArch64
|
| +@item set debug aarch64
|
| +Turns on or off display of debugging messages related to ARM AArch64.
|
| +The default is off.
|
| +@kindex show debug
|
| +@item show debug aarch64
|
| +Displays the current state of displaying debugging messages related to
|
| +ARM AArch64.
|
| @cindex gdbarch debugging info
|
| @cindex architecture debugging info
|
| @item set debug arch
|
| Turns on or off display of gdbarch debugging info. The default is off
|
| -@kindex show debug
|
| @item show debug arch
|
| Displays the current state of displaying gdbarch debugging info.
|
| +@item set debug aix-solib
|
| +@cindex AIX shared library debugging
|
| +Control display of debugging messages from the AIX shared library
|
| +support module. The default is off.
|
| +@item show debug aix-thread
|
| +Show the current state of displaying AIX shared library debugging messages.
|
| @item set debug aix-thread
|
| @cindex AIX threads
|
| Display debugging messages about inner workings of the AIX thread
|
| @@ -21785,6 +22707,13 @@ When enabled, this setting causes @value{GDBN} to compute the names
|
| both ways and display any discrepancies.
|
| @item show debug check-physname
|
| Show the current state of ``physname'' checking.
|
| +@item set debug coff-pe-read
|
| +@cindex COFF/PE exported symbols
|
| +Control display of debugging messages related to reading of COFF/PE
|
| +exported symbols. The default is off.
|
| +@item show debug coff-pe-read
|
| +Displays the current state of displaying debugging messages related to
|
| +reading of COFF/PE exported symbols.
|
| @item set debug dwarf2-die
|
| @cindex DWARF2 DIEs
|
| Dump DWARF2 DIEs after they are read in.
|
| @@ -21795,7 +22724,9 @@ Show the current state of DWARF2 DIE debugging.
|
| @item set debug dwarf2-read
|
| @cindex DWARF2 Reading
|
| Turns on or off display of debugging messages related to reading
|
| -DWARF debug info. The default is off.
|
| +DWARF debug info. The default is 0 (off).
|
| +A value of 1 provides basic information.
|
| +A value greater than 1 provides more verbose information.
|
| @item show debug dwarf2-read
|
| Show the current state of DWARF2 reader debugging.
|
| @item set debug displaced
|
| @@ -21849,6 +22780,19 @@ Displays the current state of @value{GDBN} JIT debugging.
|
| Turns on or off debugging messages from the Linux LWP debug support.
|
| @item show debug lin-lwp
|
| Show the current state of Linux LWP debugging messages.
|
| +@item set debug mach-o
|
| +@cindex Mach-O symbols processing
|
| +Control display of debugging messages related to Mach-O symbols
|
| +processing. The default is off.
|
| +@item show debug mach-o
|
| +Displays the current state of displaying debugging messages related to
|
| +reading of COFF/PE exported symbols.
|
| +@item set debug notification
|
| +@cindex remote async notification debugging info
|
| +Turns on or off debugging messages about remote async notification.
|
| +The default is off.
|
| +@item show debug notification
|
| +Displays the current state of remote async notification debugging messages.
|
| @item set debug observer
|
| @cindex observer debugging info
|
| Turns on or off display of @value{GDBN} observer debugging. This
|
| @@ -21895,10 +22839,18 @@ Turns on or off debugging messages for FR-V shared-library code.
|
| @item show debug solib-frv
|
| Display the current state of FR-V shared-library code debugging
|
| messages.
|
| +@item set debug symfile
|
| +@cindex symbol file functions
|
| +Turns on or off display of debugging messages related to symbol file functions.
|
| +The default is off. @xref{Files}.
|
| +@item show debug symfile
|
| +Show the current state of symbol file debugging messages.
|
| @item set debug symtab-create
|
| @cindex symbol table creation
|
| Turns on or off display of debugging messages related to symbol table creation.
|
| -The default is off.
|
| +The default is 0 (off).
|
| +A value of 1 provides basic information.
|
| +A value greater than 1 provides more verbose information.
|
| @item show debug symtab-create
|
| Show the current state of symbol table creation debugging.
|
| @item set debug target
|
| @@ -22539,12 +23491,31 @@ automatically imported when @value{GDBN} starts.
|
| @cindex python commands
|
| @cindex commands to access python
|
|
|
| -@value{GDBN} provides one command for accessing the Python interpreter,
|
| +@value{GDBN} provides two commands for accessing the Python interpreter,
|
| and one related setting:
|
|
|
| @table @code
|
| +@kindex python-interactive
|
| +@kindex pi
|
| +@item python-interactive @r{[}@var{command}@r{]}
|
| +@itemx pi @r{[}@var{command}@r{]}
|
| +Without an argument, the @code{python-interactive} command can be used
|
| +to start an interactive Python prompt. To return to @value{GDBN},
|
| +type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt).
|
| +
|
| +Alternatively, a single-line Python command can be given as an
|
| +argument and evaluated. If the command is an expression, the result
|
| +will be printed; otherwise, nothing will be printed. For example:
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) python-interactive 2 + 3
|
| +5
|
| +@end smallexample
|
| +
|
| @kindex python
|
| -@item python @r{[}@var{code}@r{]}
|
| +@kindex py
|
| +@item python @r{[}@var{command}@r{]}
|
| +@itemx py @r{[}@var{command}@r{]}
|
| The @code{python} command can be used to evaluate Python code.
|
|
|
| If given an argument, the @code{python} command will evaluate the
|
| @@ -22599,13 +23570,13 @@ and thus is always available.
|
| @cindex python api
|
| @cindex programming in python
|
|
|
| -@cindex python stdout
|
| -@cindex python pagination
|
| -At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
|
| -@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
|
| -A Python program which outputs to one of these streams may have its
|
| -output interrupted by the user (@pxref{Screen Size}). In this
|
| -situation, a Python @code{KeyboardInterrupt} exception is thrown.
|
| +You can get quick online help for @value{GDBN}'s Python API by issuing
|
| +the command @w{@kbd{python help (gdb)}}.
|
| +
|
| +Functions and methods which have two or more optional arguments allow
|
| +them to be specified using keyword syntax. This allows passing some
|
| +optional arguments while skipping others. Example:
|
| +@w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}.
|
|
|
| @menu
|
| * Basic Python:: Basic Python Functions.
|
| @@ -22615,6 +23586,10 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
|
| * Pretty Printing API:: Pretty-printing values.
|
| * Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
|
| * Writing a Pretty-Printer:: Writing a Pretty-Printer.
|
| +* Type Printing API:: Pretty-printing types.
|
| +* Frame Filter API:: Filtering Frames.
|
| +* Frame Decorator API:: Decorating Frames.
|
| +* Writing a Frame Filter:: Writing a Frame Filter.
|
| * Inferiors In Python:: Python representation of inferiors (processes)
|
| * Events In Python:: Listening for events from @value{GDBN}.
|
| * Threads In Python:: Accessing inferior threads from Python.
|
| @@ -22624,18 +23599,49 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
|
| * Progspaces In Python:: Program spaces.
|
| * Objfiles In Python:: Object files.
|
| * Frames In Python:: Accessing inferior stack frames from Python.
|
| -* Blocks In Python:: Accessing frame blocks from Python.
|
| +* Blocks In Python:: Accessing blocks from Python.
|
| * Symbols In Python:: Python representation of symbols.
|
| * Symbol Tables In Python:: Python representation of symbol tables.
|
| +* Line Tables In Python:: Python representation of line tables.
|
| * Breakpoints In Python:: Manipulating breakpoints using Python.
|
| * Finish Breakpoints in Python:: Setting Breakpoints on function return
|
| using Python.
|
| * Lazy Strings In Python:: Python representation of lazy strings.
|
| +* Architectures In Python:: Python representation of architectures.
|
| @end menu
|
|
|
| @node Basic Python
|
| @subsubsection Basic Python
|
|
|
| +@cindex python stdout
|
| +@cindex python pagination
|
| +At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
|
| +@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
|
| +A Python program which outputs to one of these streams may have its
|
| +output interrupted by the user (@pxref{Screen Size}). In this
|
| +situation, a Python @code{KeyboardInterrupt} exception is thrown.
|
| +
|
| +Some care must be taken when writing Python code to run in
|
| +@value{GDBN}. Two things worth noting in particular:
|
| +
|
| +@itemize @bullet
|
| +@item
|
| +@value{GDBN} install handlers for @code{SIGCHLD} and @code{SIGINT}.
|
| +Python code must not override these, or even change the options using
|
| +@code{sigaction}. If your program changes the handling of these
|
| +signals, @value{GDBN} will most likely stop working correctly. Note
|
| +that it is unfortunately common for GUI toolkits to install a
|
| +@code{SIGCHLD} handler.
|
| +
|
| +@item
|
| +@value{GDBN} takes care to mark its internal file descriptors as
|
| +close-on-exec. However, this cannot be done in a thread-safe way on
|
| +all platforms. Your Python programs should be aware of this and
|
| +should both create new file descriptors with the close-on-exec flag
|
| +set and arrange to close unneeded file descriptors before starting a
|
| +child process.
|
| +@end itemize
|
| +
|
| @cindex python functions
|
| @cindex python module
|
| @cindex gdb module
|
| @@ -22999,7 +24005,6 @@ Any values returned from a function call will be stored as a
|
|
|
| The following attributes are provided:
|
|
|
| -@table @code
|
| @defvar Value.address
|
| If this object is addressable, this read-only attribute holds a
|
| @code{gdb.Value} object representing the address. Otherwise,
|
| @@ -23047,11 +24052,9 @@ 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:
|
|
|
| -@table @code
|
| @defun Value.__init__ (@var{val})
|
| Many Python values can be converted directly to a @code{gdb.Value} via
|
| this object initializer. Specifically:
|
| @@ -23266,7 +24269,6 @@ has no effect.
|
| This method does not return a value.
|
| @end defun
|
|
|
| -@end table
|
|
|
| @node Types In Python
|
| @subsubsection Types In Python
|
| @@ -23307,7 +24309,6 @@ description of the @code{Type.fields} method for a description of the
|
|
|
| An instance of @code{Type} has the following attributes:
|
|
|
| -@table @code
|
| @defvar Type.code
|
| The type code for this type. The type code will be one of the
|
| @code{TYPE_CODE_} constants defined below.
|
| @@ -23325,11 +24326,9 @@ The tag name for this type. The tag name is the name after
|
| languages have this concept. If this type has no tag name, then
|
| @code{None} is returned.
|
| @end defvar
|
| -@end table
|
|
|
| The following methods are provided:
|
|
|
| -@table @code
|
| @defun Type.fields ()
|
| For structure and union types, this method returns the fields. Range
|
| types have two fields, the minimum and maximum values. Enum types
|
| @@ -23380,6 +24379,19 @@ second argument is the upper bound of the array. An array's length
|
| must not be negative, but the bounds can be.
|
| @end defun
|
|
|
| +@defun Type.vector (@var{n1} @r{[}, @var{n2}@r{]})
|
| +Return a new @code{gdb.Type} object which represents a vector of this
|
| +type. If one argument is given, it is the inclusive upper bound of
|
| +the vector; in this case the lower bound is zero. If two arguments are
|
| +given, the first argument is the lower bound of the vector, and the
|
| +second argument is the upper bound of the vector. A vector's length
|
| +must not be negative, but the bounds can be.
|
| +
|
| +The difference between an @code{array} and a @code{vector} is that
|
| +arrays behave like in C: when used in expressions they decay to a pointer
|
| +to the first element whereas vectors are treated as first class values.
|
| +@end defun
|
| +
|
| @defun Type.const ()
|
| Return a new @code{gdb.Type} object which represents a
|
| @code{const}-qualified variant of this type.
|
| @@ -23444,7 +24456,6 @@ exception. Ordinarily, only C@t{++} code will have template types.
|
| If @var{block} is given, then @var{name} is looked up in that scope.
|
| Otherwise, it is searched for globally.
|
| @end defun
|
| -@end table
|
|
|
|
|
| Each type has a code, which indicates what category this type falls
|
| @@ -23521,7 +24532,7 @@ language-defined string types; C strings are not represented this way.
|
| @findex TYPE_CODE_BITSTRING
|
| @findex gdb.TYPE_CODE_BITSTRING
|
| @item gdb.TYPE_CODE_BITSTRING
|
| -A string of bits.
|
| +A string of bits. It is deprecated.
|
|
|
| @findex TYPE_CODE_ERROR
|
| @findex gdb.TYPE_CODE_ERROR
|
| @@ -23897,6 +24908,698 @@ my_library.so:
|
| bar
|
| @end smallexample
|
|
|
| +@node Type Printing API
|
| +@subsubsection Type Printing API
|
| +@cindex type printing API for Python
|
| +
|
| +@value{GDBN} provides a way for Python code to customize type display.
|
| +This is mainly useful for substituting canonical typedef names for
|
| +types.
|
| +
|
| +@cindex type printer
|
| +A @dfn{type printer} is just a Python object conforming to a certain
|
| +protocol. A simple base class implementing the protocol is provided;
|
| +see @ref{gdb.types}. A type printer must supply at least:
|
| +
|
| +@defivar type_printer enabled
|
| +A boolean which is True if the printer is enabled, and False
|
| +otherwise. This is manipulated by the @code{enable type-printer}
|
| +and @code{disable type-printer} commands.
|
| +@end defivar
|
| +
|
| +@defivar type_printer name
|
| +The name of the type printer. This must be a string. This is used by
|
| +the @code{enable type-printer} and @code{disable type-printer}
|
| +commands.
|
| +@end defivar
|
| +
|
| +@defmethod type_printer instantiate (self)
|
| +This is called by @value{GDBN} at the start of type-printing. It is
|
| +only called if the type printer is enabled. This method must return a
|
| +new object that supplies a @code{recognize} method, as described below.
|
| +@end defmethod
|
| +
|
| +
|
| +When displaying a type, say via the @code{ptype} command, @value{GDBN}
|
| +will compute a list of type recognizers. This is done by iterating
|
| +first over the per-objfile type printers (@pxref{Objfiles In Python}),
|
| +followed by the per-progspace type printers (@pxref{Progspaces In
|
| +Python}), and finally the global type printers.
|
| +
|
| +@value{GDBN} will call the @code{instantiate} method of each enabled
|
| +type printer. If this method returns @code{None}, then the result is
|
| +ignored; otherwise, it is appended to the list of recognizers.
|
| +
|
| +Then, when @value{GDBN} is going to display a type name, it iterates
|
| +over the list of recognizers. For each one, it calls the recognition
|
| +function, stopping if the function returns a non-@code{None} value.
|
| +The recognition function is defined as:
|
| +
|
| +@defmethod type_recognizer recognize (self, type)
|
| +If @var{type} is not recognized, return @code{None}. Otherwise,
|
| +return a string which is to be printed as the name of @var{type}.
|
| +@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
|
| +Python}).
|
| +@end defmethod
|
| +
|
| +@value{GDBN} uses this two-pass approach so that type printers can
|
| +efficiently cache information without holding on to it too long. For
|
| +example, it can be convenient to look up type information in a type
|
| +printer and hold it for a recognizer's lifetime; if a single pass were
|
| +done then type printers would have to make use of the event system in
|
| +order to avoid holding information that could become stale as the
|
| +inferior changed.
|
| +
|
| +@node Frame Filter API
|
| +@subsubsection Filtering Frames.
|
| +@cindex frame filters api
|
| +
|
| +Frame filters are Python objects that manipulate the visibility of a
|
| +frame or frames when a backtrace (@pxref{Backtrace}) is printed by
|
| +@value{GDBN}.
|
| +
|
| +Only commands that print a backtrace, or, in the case of @sc{gdb/mi}
|
| +commands (@pxref{GDB/MI}), those that return a collection of frames
|
| +are affected. The commands that work with frame filters are:
|
| +
|
| +@code{backtrace} (@pxref{backtrace-command,, The backtrace command}),
|
| +@code{-stack-list-frames}
|
| +(@pxref{-stack-list-frames,, The -stack-list-frames command}),
|
| +@code{-stack-list-variables} (@pxref{-stack-list-variables,, The
|
| +-stack-list-variables command}), @code{-stack-list-arguments}
|
| +@pxref{-stack-list-arguments,, The -stack-list-arguments command}) and
|
| +@code{-stack-list-locals} (@pxref{-stack-list-locals,, The
|
| +-stack-list-locals command}).
|
| +
|
| +A frame filter works by taking an iterator as an argument, applying
|
| +actions to the contents of that iterator, and returning another
|
| +iterator (or, possibly, the same iterator it was provided in the case
|
| +where the filter does not perform any operations). Typically, frame
|
| +filters utilize tools such as the Python's @code{itertools} module to
|
| +work with and create new iterators from the source iterator.
|
| +Regardless of how a filter chooses to apply actions, it must not alter
|
| +the underlying @value{GDBN} frame or frames, or attempt to alter the
|
| +call-stack within @value{GDBN}. This preserves data integrity within
|
| +@value{GDBN}. Frame filters are executed on a priority basis and care
|
| +should be taken that some frame filters may have been executed before,
|
| +and that some frame filters will be executed after.
|
| +
|
| +An important consideration when designing frame filters, and well
|
| +worth reflecting upon, is that frame filters should avoid unwinding
|
| +the call stack if possible. Some stacks can run very deep, into the
|
| +tens of thousands in some cases. To search every frame when a frame
|
| +filter executes may be too expensive at that step. The frame filter
|
| +cannot know how many frames it has to iterate over, and it may have to
|
| +iterate through them all. This ends up duplicating effort as
|
| +@value{GDBN} performs this iteration when it prints the frames. If
|
| +the filter can defer unwinding frames until frame decorators are
|
| +executed, after the last filter has executed, it should. @xref{Frame
|
| +Decorator API}, for more information on decorators. Also, there are
|
| +examples for both frame decorators and filters in later chapters.
|
| +@xref{Writing a Frame Filter}, for more information.
|
| +
|
| +The Python dictionary @code{gdb.frame_filters} contains key/object
|
| +pairings that comprise a frame filter. Frame filters in this
|
| +dictionary are called @code{global} frame filters, and they are
|
| +available when debugging all inferiors. These frame filters must
|
| +register with the dictionary directly. In addition to the
|
| +@code{global} dictionary, there are other dictionaries that are loaded
|
| +with different inferiors via auto-loading (@pxref{Python
|
| +Auto-loading}). The two other areas where frame filter dictionaries
|
| +can be found are: @code{gdb.Progspace} which contains a
|
| +@code{frame_filters} dictionary attribute, and each @code{gdb.Objfile}
|
| +object which also contains a @code{frame_filters} dictionary
|
| +attribute.
|
| +
|
| +When a command is executed from @value{GDBN} that is compatible with
|
| +frame filters, @value{GDBN} combines the @code{global},
|
| +@code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently
|
| +loaded. All of the @code{gdb.Objfile} dictionaries are combined, as
|
| +several frames, and thus several object files, might be in use.
|
| +@value{GDBN} then prunes any frame filter whose @code{enabled}
|
| +attribute is @code{False}. This pruned list is then sorted according
|
| +to the @code{priority} attribute in each filter.
|
| +
|
| +Once the dictionaries are combined, pruned and sorted, @value{GDBN}
|
| +creates an iterator which wraps each frame in the call stack in a
|
| +@code{FrameDecorator} object, and calls each filter in order. The
|
| +output from the previous filter will always be the input to the next
|
| +filter, and so on.
|
| +
|
| +Frame filters have a mandatory interface which each frame filter must
|
| +implement, defined here:
|
| +
|
| +@defun FrameFilter.filter (iterator)
|
| +@value{GDBN} will call this method on a frame filter when it has
|
| +reached the order in the priority list for that filter.
|
| +
|
| +For example, if there are four frame filters:
|
| +
|
| +@smallexample
|
| +Name Priority
|
| +
|
| +Filter1 5
|
| +Filter2 10
|
| +Filter3 100
|
| +Filter4 1
|
| +@end smallexample
|
| +
|
| +The order that the frame filters will be called is:
|
| +
|
| +@smallexample
|
| +Filter3 -> Filter2 -> Filter1 -> Filter4
|
| +@end smallexample
|
| +
|
| +Note that the output from @code{Filter3} is passed to the input of
|
| +@code{Filter2}, and so on.
|
| +
|
| +This @code{filter} method is passed a Python iterator. This iterator
|
| +contains a sequence of frame decorators that wrap each
|
| +@code{gdb.Frame}, or a frame decorator that wraps another frame
|
| +decorator. The first filter that is executed in the sequence of frame
|
| +filters will receive an iterator entirely comprised of default
|
| +@code{FrameDecorator} objects. However, after each frame filter is
|
| +executed, the previous frame filter may have wrapped some or all of
|
| +the frame decorators with their own frame decorator. As frame
|
| +decorators must also conform to a mandatory interface, these
|
| +decorators can be assumed to act in a uniform manner (@pxref{Frame
|
| +Decorator API}).
|
| +
|
| +This method must return an object conforming to the Python iterator
|
| +protocol. Each item in the iterator must be an object conforming to
|
| +the frame decorator interface. If a frame filter does not wish to
|
| +perform any operations on this iterator, it should return that
|
| +iterator untouched.
|
| +
|
| +This method is not optional. If it does not exist, @value{GDBN} will
|
| +raise and print an error.
|
| +@end defun
|
| +
|
| +@defvar FrameFilter.name
|
| +The @code{name} attribute must be Python string which contains the
|
| +name of the filter displayed by @value{GDBN} (@pxref{Frame Filter
|
| +Management}). This attribute may contain any combination of letters
|
| +or numbers. Care should be taken to ensure that it is unique. This
|
| +attribute is mandatory.
|
| +@end defvar
|
| +
|
| +@defvar FrameFilter.enabled
|
| +The @code{enabled} attribute must be Python boolean. This attribute
|
| +indicates to @value{GDBN} whether the frame filter is enabled, and
|
| +should be considered when frame filters are executed. If
|
| +@code{enabled} is @code{True}, then the frame filter will be executed
|
| +when any of the backtrace commands detailed earlier in this chapter
|
| +are executed. If @code{enabled} is @code{False}, then the frame
|
| +filter will not be executed. This attribute is mandatory.
|
| +@end defvar
|
| +
|
| +@defvar FrameFilter.priority
|
| +The @code{priority} attribute must be Python integer. This attribute
|
| +controls the order of execution in relation to other frame filters.
|
| +There are no imposed limits on the range of @code{priority} other than
|
| +it must be a valid integer. The higher the @code{priority} attribute,
|
| +the sooner the frame filter will be executed in relation to other
|
| +frame filters. Although @code{priority} can be negative, it is
|
| +recommended practice to assume zero is the lowest priority that a
|
| +frame filter can be assigned. Frame filters that have the same
|
| +priority are executed in unsorted order in that priority slot. This
|
| +attribute is mandatory.
|
| +@end defvar
|
| +
|
| +@node Frame Decorator API
|
| +@subsubsection Decorating Frames.
|
| +@cindex frame decorator api
|
| +
|
| +Frame decorators are sister objects to frame filters (@pxref{Frame
|
| +Filter API}). Frame decorators are applied by a frame filter and can
|
| +only be used in conjunction with frame filters.
|
| +
|
| +The purpose of a frame decorator is to customize the printed content
|
| +of each @code{gdb.Frame} in commands where frame filters are executed.
|
| +This concept is called decorating a frame. Frame decorators decorate
|
| +a @code{gdb.Frame} with Python code contained within each API call.
|
| +This separates the actual data contained in a @code{gdb.Frame} from
|
| +the decorated data produced by a frame decorator. This abstraction is
|
| +necessary to maintain integrity of the data contained in each
|
| +@code{gdb.Frame}.
|
| +
|
| +Frame decorators have a mandatory interface, defined below.
|
| +
|
| +@value{GDBN} already contains a frame decorator called
|
| +@code{FrameDecorator}. This contains substantial amounts of
|
| +boilerplate code to decorate the content of a @code{gdb.Frame}. It is
|
| +recommended that other frame decorators inherit and extend this
|
| +object, and only to override the methods needed.
|
| +
|
| +@defun FrameDecorator.elided (self)
|
| +
|
| +The @code{elided} method groups frames together in a hierarchical
|
| +system. An example would be an interpreter, where multiple low-level
|
| +frames make up a single call in the interpreted language. In this
|
| +example, the frame filter would elide the low-level frames and present
|
| +a single high-level frame, representing the call in the interpreted
|
| +language, to the user.
|
| +
|
| +The @code{elided} function must return an iterable and this iterable
|
| +must contain the frames that are being elided wrapped in a suitable
|
| +frame decorator. If no frames are being elided this function may
|
| +return an empty iterable, or @code{None}. Elided frames are indented
|
| +from normal frames in a @code{CLI} backtrace, or in the case of
|
| +@code{GDB/MI}, are placed in the @code{children} field of the eliding
|
| +frame.
|
| +
|
| +It is the frame filter's task to also filter out the elided frames from
|
| +the source iterator. This will avoid printing the frame twice.
|
| +@end defun
|
| +
|
| +@defun FrameDecorator.function (self)
|
| +
|
| +This method returns the name of the function in the frame that is to
|
| +be printed.
|
| +
|
| +This method must return a Python string describing the function, or
|
| +@code{None}.
|
| +
|
| +If this function returns @code{None}, @value{GDBN} will not print any
|
| +data for this field.
|
| +@end defun
|
| +
|
| +@defun FrameDecorator.address (self)
|
| +
|
| +This method returns the address of the frame that is to be printed.
|
| +
|
| +This method must return a Python numeric integer type of sufficient
|
| +size to describe the address of the frame, or @code{None}.
|
| +
|
| +If this function returns a @code{None}, @value{GDBN} will not print
|
| +any data for this field.
|
| +@end defun
|
| +
|
| +@defun FrameDecorator.filename (self)
|
| +
|
| +This method returns the filename and path associated with this frame.
|
| +
|
| +This method must return a Python string containing the filename and
|
| +the path to the object file backing the frame, or @code{None}.
|
| +
|
| +If this function returns a @code{None}, @value{GDBN} will not print
|
| +any data for this field.
|
| +@end defun
|
| +
|
| +@defun FrameDecorator.line (self):
|
| +
|
| +This method returns the line number associated with the current
|
| +position within the function addressed by this frame.
|
| +
|
| +This method must return a Python integer type, or @code{None}.
|
| +
|
| +If this function returns a @code{None}, @value{GDBN} will not print
|
| +any data for this field.
|
| +@end defun
|
| +
|
| +@defun FrameDecorator.frame_args (self)
|
| +@anchor{frame_args}
|
| +
|
| +This method must return an iterable, or @code{None}. Returning an
|
| +empty iterable, or @code{None} means frame arguments will not be
|
| +printed for this frame. This iterable must contain objects that
|
| +implement two methods, described here.
|
| +
|
| +This object must implement a @code{argument} method which takes a
|
| +single @code{self} parameter and must return a @code{gdb.Symbol}
|
| +(@pxref{Symbols In Python}), or a Python string. The object must also
|
| +implement a @code{value} method which takes a single @code{self}
|
| +parameter and must return a @code{gdb.Value} (@pxref{Values From
|
| +Inferior}), a Python value, or @code{None}. If the @code{value}
|
| +method returns @code{None}, and the @code{argument} method returns a
|
| +@code{gdb.Symbol}, @value{GDBN} will look-up and print the value of
|
| +the @code{gdb.Symbol} automatically.
|
| +
|
| +A brief example:
|
| +
|
| +@smallexample
|
| +class SymValueWrapper():
|
| +
|
| + def __init__(self, symbol, value):
|
| + self.sym = symbol
|
| + self.val = value
|
| +
|
| + def value(self):
|
| + return self.val
|
| +
|
| + def symbol(self):
|
| + return self.sym
|
| +
|
| +class SomeFrameDecorator()
|
| +...
|
| +...
|
| + def frame_args(self):
|
| + args = []
|
| + try:
|
| + block = self.inferior_frame.block()
|
| + except:
|
| + return None
|
| +
|
| + # Iterate over all symbols in a block. Only add
|
| + # symbols that are arguments.
|
| + for sym in block:
|
| + if not sym.is_argument:
|
| + continue
|
| + args.append(SymValueWrapper(sym,None))
|
| +
|
| + # Add example synthetic argument.
|
| + args.append(SymValueWrapper(``foo'', 42))
|
| +
|
| + return args
|
| +@end smallexample
|
| +@end defun
|
| +
|
| +@defun FrameDecorator.frame_locals (self)
|
| +
|
| +This method must return an iterable or @code{None}. Returning an
|
| +empty iterable, or @code{None} means frame local arguments will not be
|
| +printed for this frame.
|
| +
|
| +The object interface, the description of the various strategies for
|
| +reading frame locals, and the example are largely similar to those
|
| +described in the @code{frame_args} function, (@pxref{frame_args,,The
|
| +frame filter frame_args function}). Below is a modified example:
|
| +
|
| +@smallexample
|
| +class SomeFrameDecorator()
|
| +...
|
| +...
|
| + def frame_locals(self):
|
| + vars = []
|
| + try:
|
| + block = self.inferior_frame.block()
|
| + except:
|
| + return None
|
| +
|
| + # Iterate over all symbols in a block. Add all
|
| + # symbols, except arguments.
|
| + for sym in block:
|
| + if sym.is_argument:
|
| + continue
|
| + vars.append(SymValueWrapper(sym,None))
|
| +
|
| + # Add an example of a synthetic local variable.
|
| + vars.append(SymValueWrapper(``bar'', 99))
|
| +
|
| + return vars
|
| +@end smallexample
|
| +@end defun
|
| +
|
| +@defun FrameDecorator.inferior_frame (self):
|
| +
|
| +This method must return the underlying @code{gdb.Frame} that this
|
| +frame decorator is decorating. @value{GDBN} requires the underlying
|
| +frame for internal frame information to determine how to print certain
|
| +values when printing a frame.
|
| +@end defun
|
| +
|
| +@node Writing a Frame Filter
|
| +@subsubsection Writing a Frame Filter
|
| +@cindex writing a frame filter
|
| +
|
| +There are three basic elements that a frame filter must implement: it
|
| +must correctly implement the documented interface (@pxref{Frame Filter
|
| +API}), it must register itself with @value{GDBN}, and finally, it must
|
| +decide if it is to work on the data provided by @value{GDBN}. In all
|
| +cases, whether it works on the iterator or not, each frame filter must
|
| +return an iterator. A bare-bones frame filter follows the pattern in
|
| +the following example.
|
| +
|
| +@smallexample
|
| +import gdb
|
| +
|
| +class FrameFilter():
|
| +
|
| + def __init__(self):
|
| + # Frame filter attribute creation.
|
| + #
|
| + # 'name' is the name of the filter that GDB will display.
|
| + #
|
| + # 'priority' is the priority of the filter relative to other
|
| + # filters.
|
| + #
|
| + # 'enabled' is a boolean that indicates whether this filter is
|
| + # enabled and should be executed.
|
| +
|
| + self.name = "Foo"
|
| + self.priority = 100
|
| + self.enabled = True
|
| +
|
| + # Register this frame filter with the global frame_filters
|
| + # dictionary.
|
| + gdb.frame_filters[self.name] = self
|
| +
|
| + def filter(self, frame_iter):
|
| + # Just return the iterator.
|
| + return frame_iter
|
| +@end smallexample
|
| +
|
| +The frame filter in the example above implements the three
|
| +requirements for all frame filters. It implements the API, self
|
| +registers, and makes a decision on the iterator (in this case, it just
|
| +returns the iterator untouched).
|
| +
|
| +The first step is attribute creation and assignment, and as shown in
|
| +the comments the filter assigns the following attributes: @code{name},
|
| +@code{priority} and whether the filter should be enabled with the
|
| +@code{enabled} attribute.
|
| +
|
| +The second step is registering the frame filter with the dictionary or
|
| +dictionaries that the frame filter has interest in. As shown in the
|
| +comments, this filter just registers itself with the global dictionary
|
| +@code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters}
|
| +is a dictionary that is initialized in the @code{gdb} module when
|
| +@value{GDBN} starts. What dictionary a filter registers with is an
|
| +important consideration. Generally, if a filter is specific to a set
|
| +of code, it should be registered either in the @code{objfile} or
|
| +@code{progspace} dictionaries as they are specific to the program
|
| +currently loaded in @value{GDBN}. The global dictionary is always
|
| +present in @value{GDBN} and is never unloaded. Any filters registered
|
| +with the global dictionary will exist until @value{GDBN} exits. To
|
| +avoid filters that may conflict, it is generally better to register
|
| +frame filters against the dictionaries that more closely align with
|
| +the usage of the filter currently in question. @xref{Python
|
| +Auto-loading}, for further information on auto-loading Python scripts.
|
| +
|
| +@value{GDBN} takes a hands-off approach to frame filter registration,
|
| +therefore it is the frame filter's responsibility to ensure
|
| +registration has occurred, and that any exceptions are handled
|
| +appropriately. In particular, you may wish to handle exceptions
|
| +relating to Python dictionary key uniqueness. It is mandatory that
|
| +the dictionary key is the same as frame filter's @code{name}
|
| +attribute. When a user manages frame filters (@pxref{Frame Filter
|
| +Management}), the names @value{GDBN} will display are those contained
|
| +in the @code{name} attribute.
|
| +
|
| +The final step of this example is the implementation of the
|
| +@code{filter} method. As shown in the example comments, we define the
|
| +@code{filter} method and note that the method must take an iterator,
|
| +and also must return an iterator. In this bare-bones example, the
|
| +frame filter is not very useful as it just returns the iterator
|
| +untouched. However this is a valid operation for frame filters that
|
| +have the @code{enabled} attribute set, but decide not to operate on
|
| +any frames.
|
| +
|
| +In the next example, the frame filter operates on all frames and
|
| +utilizes a frame decorator to perform some work on the frames.
|
| +@xref{Frame Decorator API}, for further information on the frame
|
| +decorator interface.
|
| +
|
| +This example works on inlined frames. It highlights frames which are
|
| +inlined by tagging them with an ``[inlined]'' tag. By applying a
|
| +frame decorator to all frames with the Python @code{itertools imap}
|
| +method, the example defers actions to the frame decorator. Frame
|
| +decorators are only processed when @value{GDBN} prints the backtrace.
|
| +
|
| +This introduces a new decision making topic: whether to perform
|
| +decision making operations at the filtering step, or at the printing
|
| +step. In this example's approach, it does not perform any filtering
|
| +decisions at the filtering step beyond mapping a frame decorator to
|
| +each frame. This allows the actual decision making to be performed
|
| +when each frame is printed. This is an important consideration, and
|
| +well worth reflecting upon when designing a frame filter. An issue
|
| +that frame filters should avoid is unwinding the stack if possible.
|
| +Some stacks can run very deep, into the tens of thousands in some
|
| +cases. To search every frame to determine if it is inlined ahead of
|
| +time may be too expensive at the filtering step. The frame filter
|
| +cannot know how many frames it has to iterate over, and it would have
|
| +to iterate through them all. This ends up duplicating effort as
|
| +@value{GDBN} performs this iteration when it prints the frames.
|
| +
|
| +In this example decision making can be deferred to the printing step.
|
| +As each frame is printed, the frame decorator can examine each frame
|
| +in turn when @value{GDBN} iterates. From a performance viewpoint,
|
| +this is the most appropriate decision to make as it avoids duplicating
|
| +the effort that the printing step would undertake anyway. Also, if
|
| +there are many frame filters unwinding the stack during filtering, it
|
| +can substantially delay the printing of the backtrace which will
|
| +result in large memory usage, and a poor user experience.
|
| +
|
| +@smallexample
|
| +class InlineFilter():
|
| +
|
| + def __init__(self):
|
| + self.name = "InlinedFrameFilter"
|
| + self.priority = 100
|
| + self.enabled = True
|
| + gdb.frame_filters[self.name] = self
|
| +
|
| + def filter(self, frame_iter):
|
| + frame_iter = itertools.imap(InlinedFrameDecorator,
|
| + frame_iter)
|
| + return frame_iter
|
| +@end smallexample
|
| +
|
| +This frame filter is somewhat similar to the earlier example, except
|
| +that the @code{filter} method applies a frame decorator object called
|
| +@code{InlinedFrameDecorator} to each element in the iterator. The
|
| +@code{imap} Python method is light-weight. It does not proactively
|
| +iterate over the iterator, but rather creates a new iterator which
|
| +wraps the existing one.
|
| +
|
| +Below is the frame decorator for this example.
|
| +
|
| +@smallexample
|
| +class InlinedFrameDecorator(FrameDecorator):
|
| +
|
| + def __init__(self, fobj):
|
| + super(InlinedFrameDecorator, self).__init__(fobj)
|
| +
|
| + def function(self):
|
| + frame = fobj.inferior_frame()
|
| + name = str(frame.name())
|
| +
|
| + if frame.type() == gdb.INLINE_FRAME:
|
| + name = name + " [inlined]"
|
| +
|
| + return name
|
| +@end smallexample
|
| +
|
| +This frame decorator only defines and overrides the @code{function}
|
| +method. It lets the supplied @code{FrameDecorator}, which is shipped
|
| +with @value{GDBN}, perform the other work associated with printing
|
| +this frame.
|
| +
|
| +The combination of these two objects create this output from a
|
| +backtrace:
|
| +
|
| +@smallexample
|
| +#0 0x004004e0 in bar () at inline.c:11
|
| +#1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
|
| +#2 0x00400566 in main () at inline.c:31
|
| +@end smallexample
|
| +
|
| +So in the case of this example, a frame decorator is applied to all
|
| +frames, regardless of whether they may be inlined or not. As
|
| +@value{GDBN} iterates over the iterator produced by the frame filters,
|
| +@value{GDBN} executes each frame decorator which then makes a decision
|
| +on what to print in the @code{function} callback. Using a strategy
|
| +like this is a way to defer decisions on the frame content to printing
|
| +time.
|
| +
|
| +@subheading Eliding Frames
|
| +
|
| +It might be that the above example is not desirable for representing
|
| +inlined frames, and a hierarchical approach may be preferred. If we
|
| +want to hierarchically represent frames, the @code{elided} frame
|
| +decorator interface might be preferable.
|
| +
|
| +This example approaches the issue with the @code{elided} method. This
|
| +example is quite long, but very simplistic. It is out-of-scope for
|
| +this section to write a complete example that comprehensively covers
|
| +all approaches of finding and printing inlined frames. However, this
|
| +example illustrates the approach an author might use.
|
| +
|
| +This example comprises of three sections.
|
| +
|
| +@smallexample
|
| +class InlineFrameFilter():
|
| +
|
| + def __init__(self):
|
| + self.name = "InlinedFrameFilter"
|
| + self.priority = 100
|
| + self.enabled = True
|
| + gdb.frame_filters[self.name] = self
|
| +
|
| + def filter(self, frame_iter):
|
| + return ElidingInlineIterator(frame_iter)
|
| +@end smallexample
|
| +
|
| +This frame filter is very similar to the other examples. The only
|
| +difference is this frame filter is wrapping the iterator provided to
|
| +it (@code{frame_iter}) with a custom iterator called
|
| +@code{ElidingInlineIterator}. This again defers actions to when
|
| +@value{GDBN} prints the backtrace, as the iterator is not traversed
|
| +until printing.
|
| +
|
| +The iterator for this example is as follows. It is in this section of
|
| +the example where decisions are made on the content of the backtrace.
|
| +
|
| +@smallexample
|
| +class ElidingInlineIterator:
|
| + def __init__(self, ii):
|
| + self.input_iterator = ii
|
| +
|
| + def __iter__(self):
|
| + return self
|
| +
|
| + def next(self):
|
| + frame = next(self.input_iterator)
|
| +
|
| + if frame.inferior_frame().type() != gdb.INLINE_FRAME:
|
| + return frame
|
| +
|
| + try:
|
| + eliding_frame = next(self.input_iterator)
|
| + except StopIteration:
|
| + return frame
|
| + return ElidingFrameDecorator(eliding_frame, [frame])
|
| +@end smallexample
|
| +
|
| +This iterator implements the Python iterator protocol. When the
|
| +@code{next} function is called (when @value{GDBN} prints each frame),
|
| +the iterator checks if this frame decorator, @code{frame}, is wrapping
|
| +an inlined frame. If it is not, it returns the existing frame decorator
|
| +untouched. If it is wrapping an inlined frame, it assumes that the
|
| +inlined frame was contained within the next oldest frame,
|
| +@code{eliding_frame}, which it fetches. It then creates and returns a
|
| +frame decorator, @code{ElidingFrameDecorator}, which contains both the
|
| +elided frame, and the eliding frame.
|
| +
|
| +@smallexample
|
| +class ElidingInlineDecorator(FrameDecorator):
|
| +
|
| + def __init__(self, frame, elided_frames):
|
| + super(ElidingInlineDecorator, self).__init__(frame)
|
| + self.frame = frame
|
| + self.elided_frames = elided_frames
|
| +
|
| + def elided(self):
|
| + return iter(self.elided_frames)
|
| +@end smallexample
|
| +
|
| +This frame decorator overrides one function and returns the inlined
|
| +frame in the @code{elided} method. As before it lets
|
| +@code{FrameDecorator} do the rest of the work involved in printing
|
| +this frame. This produces the following output.
|
| +
|
| +@smallexample
|
| +#0 0x004004e0 in bar () at inline.c:11
|
| +#2 0x00400529 in main () at inline.c:25
|
| + #1 0x00400529 in max (b=6, a=12) at inline.c:15
|
| +@end smallexample
|
| +
|
| +In that output, @code{max} which has been inlined into @code{main} is
|
| +printed hierarchically. Another approach would be to combine the
|
| +@code{function} method, and the @code{elided} method to both print a
|
| +marker in the inlined frame, and also show the hierarchical
|
| +relationship.
|
| +
|
| @node Inferiors In Python
|
| @subsubsection Inferiors In Python
|
| @cindex inferiors in Python
|
| @@ -23920,7 +25623,6 @@ Return an object representing the current inferior.
|
|
|
| A @code{gdb.Inferior} object has the following attributes:
|
|
|
| -@table @code
|
| @defvar Inferior.num
|
| ID of inferior, as assigned by GDB.
|
| @end defvar
|
| @@ -23934,11 +25636,9 @@ system.
|
| Boolean signaling whether the inferior was created using `attach', or
|
| started by @value{GDBN} itself.
|
| @end defvar
|
| -@end table
|
|
|
| A @code{gdb.Inferior} object has the following methods:
|
|
|
| -@table @code
|
| @defun Inferior.is_valid ()
|
| Returns @code{True} if the @code{gdb.Inferior} object is valid,
|
| @code{False} if not. A @code{gdb.Inferior} object will become invalid
|
| @@ -23958,7 +25658,8 @@ return an empty tuple.
|
| Read @var{length} bytes of memory from the inferior, starting at
|
| @var{address}. Returns a buffer object, which behaves much like an array
|
| or a string. It can be modified and given to the
|
| -@code{Inferior.write_memory} function.
|
| +@code{Inferior.write_memory} function. In @code{Python} 3, the return
|
| +value is a @code{memoryview} object.
|
| @end defun
|
|
|
| @findex Inferior.write_memory
|
| @@ -23980,7 +25681,6 @@ object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
|
| containing the address where the pattern was found, or @code{None} if
|
| the pattern could not be found.
|
| @end defun
|
| -@end table
|
|
|
| @node Events In Python
|
| @subsubsection Events In Python
|
| @@ -23999,7 +25699,6 @@ with an @dfn{event registry}. An event registry is an object in the
|
| @code{gdb.events} module which dispatches particular events. A registry
|
| provides methods to register and unregister event handlers:
|
|
|
| -@table @code
|
| @defun EventRegistry.connect (object)
|
| Add the given callable @var{object} to the registry. This object will be
|
| called when an event corresponding to this registry occurs.
|
| @@ -24009,7 +25708,6 @@ called when an event corresponding to this registry occurs.
|
| Remove the given @var{object} from the registry. Once removed, the object
|
| will no longer receive notifications of events.
|
| @end defun
|
| -@end table
|
|
|
| Here is an example:
|
|
|
| @@ -24043,12 +25741,10 @@ events which are emitted by this or other modules might extend this event.
|
| Examples of these events are @code{gdb.BreakpointEvent} and
|
| @code{gdb.ContinueEvent}.
|
|
|
| -@table @code
|
| @defvar ThreadEvent.inferior_thread
|
| In non-stop mode this attribute will be set to the specific thread which was
|
| involved in the emitted event. Otherwise, it will be set to @code{None}.
|
| @end defvar
|
| -@end table
|
|
|
| Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
|
|
|
| @@ -24058,7 +25754,6 @@ inherited attribute refer to @code{gdb.ThreadEvent} above.
|
| @item events.exited
|
| Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
|
| @code{events.ExitedEvent} has two attributes:
|
| -@table @code
|
| @defvar ExitedEvent.exit_code
|
| An integer representing the exit code, if available, which the inferior
|
| has returned. (The exit code could be unavailable if, for example,
|
| @@ -24068,7 +25763,6 @@ the attribute does not exist.
|
| @defvar ExitedEvent inferior
|
| A reference to the inferior which triggered the @code{exited} event.
|
| @end defvar
|
| -@end table
|
|
|
| @item events.stop
|
| Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
|
| @@ -24083,20 +25777,17 @@ Emits @code{gdb.SignalEvent} which extends @code{gdb.StopEvent}.
|
| This event indicates that the inferior or one of its threads has received as
|
| signal. @code{gdb.SignalEvent} has the following attributes:
|
|
|
| -@table @code
|
| @defvar SignalEvent.stop_signal
|
| A string representing the signal received by the inferior. A list of possible
|
| signal values can be obtained by running the command @code{info signals} in
|
| the @value{GDBN} command prompt.
|
| @end defvar
|
| -@end table
|
|
|
| Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
|
|
|
| @code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
|
| been hit, and has the following attributes:
|
|
|
| -@table @code
|
| @defvar BreakpointEvent.breakpoints
|
| A sequence containing references to all the breakpoints (type
|
| @code{gdb.Breakpoint}) that were hit.
|
| @@ -24107,18 +25798,15 @@ A reference to the first breakpoint that was hit.
|
| This function is maintained for backward compatibility and is now deprecated
|
| in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
|
| @end defvar
|
| -@end table
|
|
|
| @item events.new_objfile
|
| Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
|
| been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
|
|
|
| -@table @code
|
| @defvar NewObjFileEvent.new_objfile
|
| A reference to the object file (@code{gdb.Objfile}) which has been loaded.
|
| @xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
|
| @end defvar
|
| -@end table
|
|
|
| @end table
|
|
|
| @@ -24141,7 +25829,6 @@ is no selected thread, this will return @code{None}.
|
|
|
| A @code{gdb.InferiorThread} object has the following attributes:
|
|
|
| -@table @code
|
| @defvar InferiorThread.name
|
| The name of the thread. If the user specified a name using
|
| @code{thread name}, then this returns that name. Otherwise, if an
|
| @@ -24164,11 +25851,9 @@ is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
|
| Either the LWPID or TID may be 0, which indicates that the operating system
|
| does not use that identifier.
|
| @end defvar
|
| -@end table
|
|
|
| A @code{gdb.InferiorThread} object has the following methods:
|
|
|
| -@table @code
|
| @defun InferiorThread.is_valid ()
|
| Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
|
| @code{False} if not. A @code{gdb.InferiorThread} object will become
|
| @@ -24193,7 +25878,6 @@ Return a Boolean indicating whether the thread is running.
|
| @defun InferiorThread.is_exited ()
|
| Return a Boolean indicating whether the thread is exited.
|
| @end defun
|
| -@end table
|
|
|
| @node Commands In Python
|
| @subsubsection Commands In Python
|
| @@ -24447,6 +26131,13 @@ command names.
|
| @item gdb.COMPLETE_SYMBOL
|
| This constant means that completion should be done using symbol names
|
| as the source.
|
| +
|
| +@findex COMPLETE_EXPRESSION
|
| +@findex gdb.COMPLETE_EXPRESSION
|
| +@item gdb.COMPLETE_EXPRESSION
|
| +This constant means that completion should be done on expressions.
|
| +Often this means completing on symbol names, but some language
|
| +parsers also have support for completing on field names.
|
| @end table
|
|
|
| The following code snippet shows how a trivial CLI command can be
|
| @@ -24691,6 +26382,13 @@ registration of the function with @value{GDBN}. Depending on how the
|
| Python code is read into @value{GDBN}, you may need to import the
|
| @code{gdb} module explicitly.
|
|
|
| +Now you can use the function in an expression:
|
| +
|
| +@smallexample
|
| +(gdb) print $greet("Bob")
|
| +$1 = "Hello, Bob!"
|
| +@end smallexample
|
| +
|
| @node Progspaces In Python
|
| @subsubsection Program Spaces In Python
|
|
|
| @@ -24734,6 +26432,16 @@ which is used to format the value. @xref{Pretty Printing API}, for more
|
| information.
|
| @end defvar
|
|
|
| +@defvar Progspace.type_printers
|
| +The @code{type_printers} attribute is a list of type printer objects.
|
| +@xref{Type Printing API}, for more information.
|
| +@end defvar
|
| +
|
| +@defvar Progspace.frame_filters
|
| +The @code{frame_filters} attribute is a dictionary of frame filter
|
| +objects. @xref{Frame Filter API}, for more information.
|
| +@end defvar
|
| +
|
| @node Objfiles In Python
|
| @subsubsection Objfiles In Python
|
|
|
| @@ -24779,6 +26487,16 @@ which is used to format the value. @xref{Pretty Printing API}, for more
|
| information.
|
| @end defvar
|
|
|
| +@defvar Objfile.type_printers
|
| +The @code{type_printers} attribute is a list of type printer objects.
|
| +@xref{Type Printing API}, for more information.
|
| +@end defvar
|
| +
|
| +@defvar Objfile.frame_filters
|
| +The @code{frame_filters} attribute is a dictionary of frame filter
|
| +objects. @xref{Frame Filter API}, for more information.
|
| +@end defvar
|
| +
|
| A @code{gdb.Objfile} object has the following methods:
|
|
|
| @defun Objfile.is_valid ()
|
| @@ -24828,7 +26546,6 @@ frames, as expressed by the given @var{reason} code (an integer, see the
|
|
|
| A @code{gdb.Frame} object has the following methods:
|
|
|
| -@table @code
|
| @defun Frame.is_valid ()
|
| Returns true if the @code{gdb.Frame} object is valid, false if not.
|
| A frame object can become invalid if the frame it refers to doesn't
|
| @@ -24841,6 +26558,11 @@ Returns the function name of the frame, or @code{None} if it can't be
|
| obtained.
|
| @end defun
|
|
|
| +@defun Frame.architecture ()
|
| +Returns the @code{gdb.Architecture} object corresponding to the frame's
|
| +architecture. @xref{Architectures In Python}.
|
| +@end defun
|
| +
|
| @defun Frame.type ()
|
| Returns the type of the frame. The value can be one of:
|
| @table @code
|
| @@ -24882,7 +26604,9 @@ function to a string. The value can be one of:
|
| No particular reason (older frames should be available).
|
|
|
| @item gdb.FRAME_UNWIND_NULL_ID
|
| -The previous frame's analyzer returns an invalid result.
|
| +The previous frame's analyzer returns an invalid result. This is no
|
| +longer used by @value{GDBN}, and is kept only for backward
|
| +compatibility.
|
|
|
| @item gdb.FRAME_UNWIND_OUTERMOST
|
| This frame is the outermost.
|
| @@ -24962,21 +26686,63 @@ must be a string or a @code{gdb.Symbol} object. @var{block} must be a
|
| Set this frame to be the selected frame. @xref{Stack, ,Examining the
|
| Stack}.
|
| @end defun
|
| -@end table
|
|
|
| @node Blocks In Python
|
| -@subsubsection Accessing frame blocks from Python.
|
| +@subsubsection Accessing blocks from Python.
|
|
|
| @cindex blocks in python
|
| @tindex gdb.Block
|
|
|
| -Within each frame, @value{GDBN} maintains information on each block
|
| -stored in that frame. These blocks are organized hierarchically, and
|
| -are represented individually in Python as a @code{gdb.Block}.
|
| -Please see @ref{Frames In Python}, for a more in-depth discussion on
|
| -frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more
|
| -detailed technical information on @value{GDBN}'s book-keeping of the
|
| -stack.
|
| +In @value{GDBN}, symbols are stored in blocks. A block corresponds
|
| +roughly to a scope in the source code. Blocks are organized
|
| +hierarchically, and are represented individually in Python as a
|
| +@code{gdb.Block}. Blocks rely on debugging information being
|
| +available.
|
| +
|
| +A frame has a block. Please see @ref{Frames In Python}, for a more
|
| +in-depth discussion of frames.
|
| +
|
| +The outermost block is known as the @dfn{global block}. The global
|
| +block typically holds public global variables and functions.
|
| +
|
| +The block nested just inside the global block is the @dfn{static
|
| +block}. The static block typically holds file-scoped variables and
|
| +functions.
|
| +
|
| +@value{GDBN} provides a method to get a block's superblock, but there
|
| +is currently no way to examine the sub-blocks of a block, or to
|
| +iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
|
| +Python}).
|
| +
|
| +Here is a short example that should help explain blocks:
|
| +
|
| +@smallexample
|
| +/* This is in the global block. */
|
| +int global;
|
| +
|
| +/* This is in the static block. */
|
| +static int file_scope;
|
| +
|
| +/* 'function' is in the global block, and 'argument' is
|
| + in a block nested inside of 'function'. */
|
| +int function (int argument)
|
| +@{
|
| + /* 'local' is in a block inside 'function'. It may or may
|
| + not be in the same block as 'argument'. */
|
| + int local;
|
| +
|
| + @{
|
| + /* 'inner' is in a block whose superblock is the one holding
|
| + 'local'. */
|
| + int inner;
|
| +
|
| + /* If this call is expanded by the compiler, you may see
|
| + a nested block here whose function is 'inline_function'
|
| + and whose superblock is the one holding 'inner'. */
|
| + inline_function ();
|
| + @}
|
| +@}
|
| +@end smallexample
|
|
|
| A @code{gdb.Block} is iterable. The iterator returns the symbols
|
| (@pxref{Symbols In Python}) local to the block. Python programs
|
| @@ -24990,14 +26756,13 @@ module:
|
|
|
| @findex gdb.block_for_pc
|
| @defun gdb.block_for_pc (pc)
|
| -Return the @code{gdb.Block} containing the given @var{pc} value. If the
|
| -block cannot be found for the @var{pc} value specified, the function
|
| -will return @code{None}.
|
| +Return the innermost @code{gdb.Block} containing the given @var{pc}
|
| +value. If the block cannot be found for the @var{pc} value specified,
|
| +the function will return @code{None}.
|
| @end defun
|
|
|
| A @code{gdb.Block} object has the following methods:
|
|
|
| -@table @code
|
| @defun Block.is_valid ()
|
| Returns @code{True} if the @code{gdb.Block} object is valid,
|
| @code{False} if not. A block object can become invalid if the block it
|
| @@ -25006,11 +26771,9 @@ refers to doesn't exist anymore in the inferior. All other
|
| the time the method is called. The block's validity is also checked
|
| during iteration over symbols of the block.
|
| @end defun
|
| -@end table
|
|
|
| A @code{gdb.Block} object has the following attributes:
|
|
|
| -@table @code
|
| @defvar Block.start
|
| The start address of the block. This attribute is not writable.
|
| @end defvar
|
| @@ -25023,6 +26786,11 @@ The end address of the block. This attribute is not writable.
|
| The name of the block represented as a @code{gdb.Symbol}. If the
|
| block is not named, then this attribute holds @code{None}. This
|
| attribute is not writable.
|
| +
|
| +For ordinary function blocks, the superblock is the static block.
|
| +However, you should note that it is possible for a function block to
|
| +have a superblock that is not the static block -- for instance this
|
| +happens for an inlined function.
|
| @end defvar
|
|
|
| @defvar Block.superblock
|
| @@ -25050,7 +26818,6 @@ writable.
|
| @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
|
| @subsubsection Python representation of Symbols.
|
| @@ -25106,7 +26873,6 @@ is not found.
|
|
|
| A @code{gdb.Symbol} object has the following attributes:
|
|
|
| -@table @code
|
| @defvar Symbol.type
|
| The type of the symbol or @code{None} if no type is recorded.
|
| This attribute is represented as a @code{gdb.Type} object.
|
| @@ -25166,11 +26932,9 @@ local variables will require a frame, but other symbols will not.
|
| @defvar Symbol.is_variable
|
| @code{True} if the symbol is a variable.
|
| @end defvar
|
| -@end table
|
|
|
| A @code{gdb.Symbol} object has the following methods:
|
|
|
| -@table @code
|
| @defun Symbol.is_valid ()
|
| Returns @code{True} if the @code{gdb.Symbol} object is valid,
|
| @code{False} if not. A @code{gdb.Symbol} object can become invalid if
|
| @@ -25187,7 +26951,6 @@ 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
|
| as constants in the @code{gdb} module:
|
| @@ -25316,7 +27079,6 @@ For more information on @value{GDBN}'s symbol table management, see
|
|
|
| A @code{gdb.Symtab_and_line} object has the following attributes:
|
|
|
| -@table @code
|
| @defvar Symtab_and_line.symtab
|
| The symbol table object (@code{gdb.Symtab}) for this frame.
|
| This attribute is not writable.
|
| @@ -25336,11 +27098,9 @@ source line. This attribute is not writable.
|
| Indicates the current line number for this object. This
|
| attribute is not writable.
|
| @end defvar
|
| -@end table
|
|
|
| A @code{gdb.Symtab_and_line} object has the following methods:
|
|
|
| -@table @code
|
| @defun Symtab_and_line.is_valid ()
|
| Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
|
| @code{False} if not. A @code{gdb.Symtab_and_line} object can become
|
| @@ -25349,11 +27109,9 @@ exist in @value{GDBN} any longer. All other
|
| @code{gdb.Symtab_and_line} methods will throw an exception if it is
|
| invalid at the time the method is called.
|
| @end defun
|
| -@end table
|
|
|
| A @code{gdb.Symtab} object has the following attributes:
|
|
|
| -@table @code
|
| @defvar Symtab.filename
|
| The symbol table's source filename. This attribute is not writable.
|
| @end defvar
|
| @@ -25362,11 +27120,9 @@ The symbol table's source filename. This attribute is not writable.
|
| The symbol table's backing object file. @xref{Objfiles In Python}.
|
| This attribute is not writable.
|
| @end defvar
|
| -@end table
|
|
|
| A @code{gdb.Symtab} object has the following methods:
|
|
|
| -@table @code
|
| @defun Symtab.is_valid ()
|
| Returns @code{True} if the @code{gdb.Symtab} object is valid,
|
| @code{False} if not. A @code{gdb.Symtab} object can become invalid if
|
| @@ -25388,7 +27144,89 @@ Return the global block of the underlying symbol table.
|
| Return the static block of the underlying symbol table.
|
| @xref{Blocks In Python}.
|
| @end defun
|
| -@end table
|
| +
|
| +@defun Symtab.linetable ()
|
| +Return the line table associated with the symbol table.
|
| +@xref{Line Tables In Python}.
|
| +@end defun
|
| +
|
| +@node Line Tables In Python
|
| +@subsubsection Manipulating line tables using Python
|
| +
|
| +@cindex line tables in python
|
| +@tindex gdb.LineTable
|
| +
|
| +Python code can request and inspect line table information from a
|
| +symbol table that is loaded in @value{GDBN}. A line table is a
|
| +mapping of source lines to their executable locations in memory. To
|
| +acquire the line table information for a particular symbol table, use
|
| +the @code{linetable} function (@pxref{Symbol Tables In Python}).
|
| +
|
| +A @code{gdb.LineTable} is iterable. The iterator returns
|
| +@code{LineTableEntry} objects that correspond to the source line and
|
| +address for each line table entry. @code{LineTableEntry} objects have
|
| +the following attributes:
|
| +
|
| +@defvar LineTableEntry.line
|
| +The source line number for this line table entry. This number
|
| +corresponds to the actual line of source. This attribute is not
|
| +writable.
|
| +@end defvar
|
| +
|
| +@defvar LineTableEntry.pc
|
| +The address that is associated with the line table entry where the
|
| +executable code for that source line resides in memory. This
|
| +attribute is not writable.
|
| +@end defvar
|
| +
|
| +As there can be multiple addresses for a single source line, you may
|
| +receive multiple @code{LineTableEntry} objects with matching
|
| +@code{line} attributes, but with different @code{pc} attributes. The
|
| +iterator is sorted in ascending @code{pc} order. Here is a small
|
| +example illustrating iterating over a line table.
|
| +
|
| +@smallexample
|
| +symtab = gdb.selected_frame().find_sal().symtab
|
| +linetable = symtab.linetable()
|
| +for line in linetable:
|
| + print "Line: "+str(line.line)+" Address: "+hex(line.pc)
|
| +@end smallexample
|
| +
|
| +This will have the following output:
|
| +
|
| +@smallexample
|
| +Line: 33 Address: 0x4005c8L
|
| +Line: 37 Address: 0x4005caL
|
| +Line: 39 Address: 0x4005d2L
|
| +Line: 40 Address: 0x4005f8L
|
| +Line: 42 Address: 0x4005ffL
|
| +Line: 44 Address: 0x400608L
|
| +Line: 42 Address: 0x40060cL
|
| +Line: 45 Address: 0x400615L
|
| +@end smallexample
|
| +
|
| +In addition to being able to iterate over a @code{LineTable}, it also
|
| +has the following direct access methods:
|
| +
|
| +@defun LineTable.line (line)
|
| +Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
|
| +entries in the line table for the given @var{line}. @var{line} refers
|
| +to the source code line. If there are no entries for that source code
|
| +@var{line}, the Python @code{None} is returned.
|
| +@end defun
|
| +
|
| +@defun LineTable.has_line (line)
|
| +Return a Python @code{Boolean} indicating whether there is an entry in
|
| +the line table for this source line. Return @code{True} if an entry
|
| +is found, or @code{False} if not.
|
| +@end defun
|
| +
|
| +@defun LineTable.source_lines ()
|
| +Return a Python @code{List} of the source line numbers in the symbol
|
| +table. Only lines with executable code locations are returned. The
|
| +contents of the @code{List} will just be the source line entries
|
| +represented as Python @code{Long} values.
|
| +@end defun
|
|
|
| @node Breakpoints In Python
|
| @subsubsection Manipulating breakpoints using Python
|
| @@ -25399,28 +27237,33 @@ Return the static block of the underlying symbol table.
|
| Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
|
| class.
|
|
|
| -@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal@r{]]]})
|
| -Create a new breakpoint. @var{spec} is a string naming the
|
| -location of the breakpoint, or an expression that defines a
|
| -watchpoint. The contents can be any location recognized by the
|
| -@code{break} command, or in the case of a watchpoint, by the @code{watch}
|
| -command. The optional @var{type} denotes the breakpoint to create
|
| -from the types defined later in this chapter. This argument can be
|
| -either: @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
|
| -defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal} argument
|
| -allows the breakpoint to become invisible to the user. The breakpoint
|
| -will neither be reported when created, nor will it be listed in the
|
| -output from @code{info breakpoints} (but will be listed with the
|
| -@code{maint info breakpoints} command). The optional @var{wp_class}
|
| -argument defines the class of watchpoint to create, if @var{type} is
|
| -@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it is
|
| -assumed to be a @code{gdb.WP_WRITE} class.
|
| +@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
|
| +Create a new breakpoint. @var{spec} is a string naming the location
|
| +of the breakpoint, or an expression that defines a watchpoint. The
|
| +contents can be any location recognized by the @code{break} command,
|
| +or in the case of a watchpoint, by the @code{watch} command. The
|
| +optional @var{type} denotes the breakpoint to create from the types
|
| +defined later in this chapter. This argument can be either:
|
| +@code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
|
| +defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
|
| +argument allows the breakpoint to become invisible to the user. The
|
| +breakpoint will neither be reported when created, nor will it be
|
| +listed in the output from @code{info breakpoints} (but will be listed
|
| +with the @code{maint info breakpoints} command). The optional
|
| +@var{temporary} argument makes the breakpoint a temporary breakpoint.
|
| +Temporary breakpoints are deleted after they have been hit. Any
|
| +further access to the Python breakpoint after it has been hit will
|
| +result in a runtime error (as that breakpoint has now been
|
| +automatically deleted). The optional @var{wp_class} argument defines
|
| +the class of watchpoint to create, if @var{type} is
|
| +@code{gdb.BP_WATCHPOINT}. If a watchpoint class is not provided, it
|
| +is assumed to be a @code{gdb.WP_WRITE} class.
|
| @end defun
|
|
|
| @defun Breakpoint.stop (self)
|
| The @code{gdb.Breakpoint} class can be sub-classed and, in
|
| particular, you may choose to implement the @code{stop} method.
|
| -If this method is defined as a sub-class of @code{gdb.Breakpoint},
|
| +If this method is defined in a sub-class of @code{gdb.Breakpoint},
|
| it will be called when the inferior reaches any location of a
|
| breakpoint which instantiates that sub-class. If the method returns
|
| @code{True}, the inferior will be stopped at the location of the
|
| @@ -25535,6 +27378,16 @@ when set, or when the @samp{info breakpoints} command is run. This
|
| attribute is not writable.
|
| @end defvar
|
|
|
| +@defvar Breakpoint.temporary
|
| +This attribute indicates whether the breakpoint was created as a
|
| +temporary breakpoint. Temporary breakpoints are automatically deleted
|
| +after that breakpoint has been hit. Access to this attribute, and all
|
| +other attributes and functions other than the @code{is_valid}
|
| +function, will result in an error after the breakpoint has been hit
|
| +(as it has been automatically deleted). This attribute is not
|
| +writable.
|
| +@end defvar
|
| +
|
| The available types are represented by constants defined in the @code{gdb}
|
| module:
|
|
|
| @@ -25703,6 +27556,56 @@ resolve this to the lazy string's character type, use the type's
|
| writable.
|
| @end defvar
|
|
|
| +@node Architectures In Python
|
| +@subsubsection Python representation of architectures
|
| +@cindex Python architectures
|
| +
|
| +@value{GDBN} uses architecture specific parameters and artifacts in a
|
| +number of its various computations. An architecture is represented
|
| +by an instance of the @code{gdb.Architecture} class.
|
| +
|
| +A @code{gdb.Architecture} class has the following methods:
|
| +
|
| +@defun Architecture.name ()
|
| +Return the name (string value) of the architecture.
|
| +@end defun
|
| +
|
| +@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
|
| +Return a list of disassembled instructions starting from the memory
|
| +address @var{start_pc}. The optional arguments @var{end_pc} and
|
| +@var{count} determine the number of instructions in the returned list.
|
| +If both the optional arguments @var{end_pc} and @var{count} are
|
| +specified, then a list of at most @var{count} disassembled instructions
|
| +whose start address falls in the closed memory address interval from
|
| +@var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
|
| +specified, but @var{count} is specified, then @var{count} number of
|
| +instructions starting from the address @var{start_pc} are returned. If
|
| +@var{count} is not specified but @var{end_pc} is specified, then all
|
| +instructions whose start address falls in the closed memory address
|
| +interval from @var{start_pc} to @var{end_pc} are returned. If neither
|
| +@var{end_pc} nor @var{count} are specified, then a single instruction at
|
| +@var{start_pc} is returned. For all of these cases, each element of the
|
| +returned list is a Python @code{dict} with the following string keys:
|
| +
|
| +@table @code
|
| +
|
| +@item addr
|
| +The value corresponding to this key is a Python long integer capturing
|
| +the memory address of the instruction.
|
| +
|
| +@item asm
|
| +The value corresponding to this key is a string value which represents
|
| +the instruction with assembly language mnemonics. The assembly
|
| +language flavor used is the same as that specified by the current CLI
|
| +variable @code{disassembly-flavor}. @xref{Machine Code}.
|
| +
|
| +@item length
|
| +The value corresponding to this key is the length (integer value) of the
|
| +instruction in bytes.
|
| +
|
| +@end table
|
| +@end defun
|
| +
|
| @node Python Auto-loading
|
| @subsection Python Auto-loading
|
| @cindex Python auto-loading
|
| @@ -25760,7 +27663,7 @@ No my-foo-pretty-printers.py
|
| When reading an auto-loaded file, @value{GDBN} sets the
|
| @dfn{current objfile}. This is available via the @code{gdb.current_objfile}
|
| function (@pxref{Objfiles In Python}). This can be useful for
|
| -registering objfile-specific pretty-printers.
|
| +registering objfile-specific pretty-printers and frame-filters.
|
|
|
| @menu
|
| * objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
|
| @@ -25981,7 +27884,7 @@ if a printer with the same name already exists.
|
| @cindex gdb.types
|
|
|
| This module provides a collection of utilities for working with
|
| -@code{gdb.Types} objects.
|
| +@code{gdb.Type} objects.
|
|
|
| @table @code
|
| @item get_basic_type (@var{type})
|
| @@ -26042,6 +27945,37 @@ Then in @value{GDBN}:
|
| @{['a', 'b0', 'b1']@}
|
| @end smallexample
|
|
|
| +@item get_type_recognizers ()
|
| +Return a list of the enabled type recognizers for the current context.
|
| +This is called by @value{GDBN} during the type-printing process
|
| +(@pxref{Type Printing API}).
|
| +
|
| +@item apply_type_recognizers (recognizers, type_obj)
|
| +Apply the type recognizers, @var{recognizers}, to the type object
|
| +@var{type_obj}. If any recognizer returns a string, return that
|
| +string. Otherwise, return @code{None}. This is called by
|
| +@value{GDBN} during the type-printing process (@pxref{Type Printing
|
| +API}).
|
| +
|
| +@item register_type_printer (locus, printer)
|
| +This is a convenience function to register a type printer.
|
| +@var{printer} is the type printer to register. It must implement the
|
| +type printer protocol. @var{locus} is either a @code{gdb.Objfile}, in
|
| +which case the printer is registered with that objfile; a
|
| +@code{gdb.Progspace}, in which case the printer is registered with
|
| +that progspace; or @code{None}, in which case the printer is
|
| +registered globally.
|
| +
|
| +@item TypePrinter
|
| +This is a base class that implements the type printer protocol. Type
|
| +printers are encouraged, but not required, to derive from this class.
|
| +It defines a constructor:
|
| +
|
| +@defmethod TypePrinter __init__ (self, name)
|
| +Initialize the type printer with the given name. The new printer
|
| +starts in the enabled state.
|
| +@end defmethod
|
| +
|
| @end table
|
|
|
| @node gdb.prompt
|
| @@ -26821,21 +28755,6 @@ A more detailed description of Emacs' interaction with @value{GDBN} is
|
| given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu}
|
| Emacs Manual}).
|
|
|
| -@c The following dropped because Epoch is nonstandard. Reactivate
|
| -@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
|
| -@ignore
|
| -@kindex Emacs Epoch environment
|
| -@kindex Epoch
|
| -@kindex inspect
|
| -
|
| -Version 18 of @sc{gnu} Emacs has a built-in window system
|
| -called the @code{epoch}
|
| -environment. Users of this environment can use a new command,
|
| -@code{inspect} which performs identically to @code{print} except that
|
| -each value is printed in its own window.
|
| -@end ignore
|
| -
|
| -
|
| @node GDB/MI
|
| @chapter The @sc{gdb/mi} Interface
|
|
|
| @@ -26893,6 +28812,7 @@ may repeat one or more times.
|
| * GDB/MI Simple Examples::
|
| * GDB/MI Command Description Format::
|
| * GDB/MI Breakpoint Commands::
|
| +* GDB/MI Catchpoint Commands::
|
| * GDB/MI Program Context::
|
| * GDB/MI Thread Commands::
|
| * GDB/MI Ada Tasking Commands::
|
| @@ -26910,6 +28830,7 @@ may repeat one or more times.
|
| @end ignore
|
| * GDB/MI Target Manipulation::
|
| * GDB/MI File Transfer Commands::
|
| +* GDB/MI Ada Exceptions Commands::
|
| * GDB/MI Miscellaneous Commands::
|
| @end menu
|
|
|
| @@ -26975,6 +28896,8 @@ the user interface.
|
| @node Context management
|
| @subsection Context management
|
|
|
| +@subsubsection Threads and Frames
|
| +
|
| In most cases when @value{GDBN} accesses the target, this access is
|
| done in context of a specific thread and frame (@pxref{Frames}).
|
| Often, even when accessing global data, the target requires that a thread
|
| @@ -27025,6 +28948,25 @@ all subsequent commands. No frontend is known to do this exactly
|
| right, so it is suggested to just always pass the @samp{--thread} and
|
| @samp{--frame} options.
|
|
|
| +@subsubsection Language
|
| +
|
| +The execution of several commands depends on which language is selected.
|
| +By default, the current language (@pxref{show language}) is used.
|
| +But for commands known to be language-sensitive, it is recommended
|
| +to use the @samp{--language} option. This option takes one argument,
|
| +which is the name of the language to use while executing the command.
|
| +For instance:
|
| +
|
| +@smallexample
|
| +-data-evaluate-expression --language c "sizeof (void*)"
|
| +^done,value="4"
|
| +(gdb)
|
| +@end smallexample
|
| +
|
| +The valid language names are the same names accepted by the
|
| +@samp{set language} command (@pxref{Manually}), excluding @samp{auto},
|
| +@samp{local} or @samp{unknown}.
|
| +
|
| @node Asynchronous and non-stop modes
|
| @subsection Asynchronous command execution and non-stop mode
|
|
|
| @@ -27406,6 +29348,7 @@ follow development on @email{gdb@@sourceware.org} and
|
| * GDB/MI Result Records::
|
| * GDB/MI Stream Records::
|
| * GDB/MI Async Records::
|
| +* GDB/MI Breakpoint Information::
|
| * GDB/MI Frame Information::
|
| * GDB/MI Thread Information::
|
| * GDB/MI Ada Exception Information::
|
| @@ -27438,10 +29381,19 @@ which threads are resumed.
|
| @findex ^connected
|
| @value{GDBN} has connected to a remote target.
|
|
|
| -@item "^error" "," @var{c-string}
|
| +@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ]
|
| @findex ^error
|
| -The operation failed. The @code{@var{c-string}} contains the corresponding
|
| -error message.
|
| +The operation failed. The @code{msg=@var{c-string}} variable contains
|
| +the corresponding error message.
|
| +
|
| +If present, the @code{code=@var{c-string}} variable provides an error
|
| +code on which consumers can rely on to detect the corresponding
|
| +error condition. At present, only one error code is defined:
|
| +
|
| +@table @samp
|
| +@item "undefined-command"
|
| +Indicates that the command causing the error does not exist.
|
| +@end table
|
|
|
| @item "^exit"
|
| @findex ^exit
|
| @@ -27632,21 +29584,187 @@ thread group in whose context the library was unloaded. If the field is
|
| absent, it means the library was unloaded in the context of all present
|
| thread groups.
|
|
|
| +@item =traceframe-changed,num=@var{tfnum},tracepoint=@var{tpnum}
|
| +@itemx =traceframe-changed,end
|
| +Reports that the trace frame was changed and its new number is
|
| +@var{tfnum}. The number of the tracepoint associated with this trace
|
| +frame is @var{tpnum}.
|
| +
|
| +@item =tsv-created,name=@var{name},initial=@var{initial}
|
| +Reports that the new trace state variable @var{name} is created with
|
| +initial value @var{initial}.
|
| +
|
| +@item =tsv-deleted,name=@var{name}
|
| +@itemx =tsv-deleted
|
| +Reports that the trace state variable @var{name} is deleted or all
|
| +trace state variables are deleted.
|
| +
|
| +@item =tsv-modified,name=@var{name},initial=@var{initial}[,current=@var{current}]
|
| +Reports that the trace state variable @var{name} is modified with
|
| +the initial value @var{initial}. The current value @var{current} of
|
| +trace state variable is optional and is reported if the current
|
| +value of trace state variable is known.
|
| +
|
| @item =breakpoint-created,bkpt=@{...@}
|
| @itemx =breakpoint-modified,bkpt=@{...@}
|
| -@itemx =breakpoint-deleted,bkpt=@{...@}
|
| +@itemx =breakpoint-deleted,id=@var{number}
|
| Reports that a breakpoint was created, modified, or deleted,
|
| respectively. Only user-visible breakpoints are reported to the MI
|
| user.
|
|
|
| The @var{bkpt} argument is of the same form as returned by the various
|
| -breakpoint commands; @xref{GDB/MI Breakpoint Commands}.
|
| +breakpoint commands; @xref{GDB/MI Breakpoint Commands}. The
|
| +@var{number} is the ordinal number of the breakpoint.
|
|
|
| Note that if a breakpoint is emitted in the result record of a
|
| command, then it will not also be emitted in an async record.
|
|
|
| +@item =record-started,thread-group="@var{id}"
|
| +@itemx =record-stopped,thread-group="@var{id}"
|
| +Execution log recording was either started or stopped on an
|
| +inferior. The @var{id} is the @value{GDBN} identifier of the thread
|
| +group corresponding to the affected inferior.
|
| +
|
| +@item =cmd-param-changed,param=@var{param},value=@var{value}
|
| +Reports that a parameter of the command @code{set @var{param}} is
|
| +changed to @var{value}. In the multi-word @code{set} command,
|
| +the @var{param} is the whole parameter list to @code{set} command.
|
| +For example, In command @code{set check type on}, @var{param}
|
| +is @code{check type} and @var{value} is @code{on}.
|
| +
|
| +@item =memory-changed,thread-group=@var{id},addr=@var{addr},len=@var{len}[,type="code"]
|
| +Reports that bytes from @var{addr} to @var{data} + @var{len} were
|
| +written in an inferior. The @var{id} is the identifier of the
|
| +thread group corresponding to the affected inferior. The optional
|
| +@code{type="code"} part is reported if the memory written to holds
|
| +executable code.
|
| @end table
|
|
|
| +@node GDB/MI Breakpoint Information
|
| +@subsection @sc{gdb/mi} Breakpoint Information
|
| +
|
| +When @value{GDBN} reports information about a breakpoint, a
|
| +tracepoint, a watchpoint, or a catchpoint, it uses a tuple with the
|
| +following fields:
|
| +
|
| +@table @code
|
| +@item number
|
| +The breakpoint number. For a breakpoint that represents one location
|
| +of a multi-location breakpoint, this will be a dotted pair, like
|
| +@samp{1.2}.
|
| +
|
| +@item type
|
| +The type of the breakpoint. For ordinary breakpoints this will be
|
| +@samp{breakpoint}, but many values are possible.
|
| +
|
| +@item catch-type
|
| +If the type of the breakpoint is @samp{catchpoint}, then this
|
| +indicates the exact type of catchpoint.
|
| +
|
| +@item disp
|
| +This is the breakpoint disposition---either @samp{del}, meaning that
|
| +the breakpoint will be deleted at the next stop, or @samp{keep},
|
| +meaning that the breakpoint will not be deleted.
|
| +
|
| +@item enabled
|
| +This indicates whether the breakpoint is enabled, in which case the
|
| +value is @samp{y}, or disabled, in which case the value is @samp{n}.
|
| +Note that this is not the same as the field @code{enable}.
|
| +
|
| +@item addr
|
| +The address of the breakpoint. This may be a hexidecimal number,
|
| +giving the address; or the string @samp{<PENDING>}, for a pending
|
| +breakpoint; or the string @samp{<MULTIPLE>}, for a breakpoint with
|
| +multiple locations. This field will not be present if no address can
|
| +be determined. For example, a watchpoint does not have an address.
|
| +
|
| +@item func
|
| +If known, the function in which the breakpoint appears.
|
| +If not known, this field is not present.
|
| +
|
| +@item filename
|
| +The name of the source file which contains this function, if known.
|
| +If not known, this field is not present.
|
| +
|
| +@item fullname
|
| +The full file name of the source file which contains this function, if
|
| +known. If not known, this field is not present.
|
| +
|
| +@item line
|
| +The line number at which this breakpoint appears, if known.
|
| +If not known, this field is not present.
|
| +
|
| +@item at
|
| +If the source file is not known, this field may be provided. If
|
| +provided, this holds the address of the breakpoint, possibly followed
|
| +by a symbol name.
|
| +
|
| +@item pending
|
| +If this breakpoint is pending, this field is present and holds the
|
| +text used to set the breakpoint, as entered by the user.
|
| +
|
| +@item evaluated-by
|
| +Where this breakpoint's condition is evaluated, either @samp{host} or
|
| +@samp{target}.
|
| +
|
| +@item thread
|
| +If this is a thread-specific breakpoint, then this identifies the
|
| +thread in which the breakpoint can trigger.
|
| +
|
| +@item task
|
| +If this breakpoint is restricted to a particular Ada task, then this
|
| +field will hold the task identifier.
|
| +
|
| +@item cond
|
| +If the breakpoint is conditional, this is the condition expression.
|
| +
|
| +@item ignore
|
| +The ignore count of the breakpoint.
|
| +
|
| +@item enable
|
| +The enable count of the breakpoint.
|
| +
|
| +@item traceframe-usage
|
| +FIXME.
|
| +
|
| +@item static-tracepoint-marker-string-id
|
| +For a static tracepoint, the name of the static tracepoint marker.
|
| +
|
| +@item mask
|
| +For a masked watchpoint, this is the mask.
|
| +
|
| +@item pass
|
| +A tracepoint's pass count.
|
| +
|
| +@item original-location
|
| +The location of the breakpoint as originally specified by the user.
|
| +This field is optional.
|
| +
|
| +@item times
|
| +The number of times the breakpoint has been hit.
|
| +
|
| +@item installed
|
| +This field is only given for tracepoints. This is either @samp{y},
|
| +meaning that the tracepoint is installed, or @samp{n}, meaning that it
|
| +is not.
|
| +
|
| +@item what
|
| +Some extra data, the exact contents of which are type-dependent.
|
| +
|
| +@end table
|
| +
|
| +For example, here is what the output of @code{-break-insert}
|
| +(@pxref{GDB/MI Breakpoint Commands}) might be:
|
| +
|
| +@smallexample
|
| +-> -break-insert main
|
| +<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
|
| + enabled="y",addr="0x08048564",func="main",file="myprog.c",
|
| + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
|
| + times="0"@}
|
| +<- (gdb)
|
| +@end smallexample
|
| +
|
| @node GDB/MI Frame Information
|
| @subsection @sc{gdb/mi} Frame Information
|
|
|
| @@ -27738,7 +29856,8 @@ information of the breakpoint.
|
| -> -break-insert main
|
| <- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
|
| enabled="y",addr="0x08048564",func="main",file="myprog.c",
|
| - fullname="/home/nickrob/myprog.c",line="68",times="0"@}
|
| + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"],
|
| + times="0"@}
|
| <- (gdb)
|
| @end smallexample
|
|
|
| @@ -27862,7 +29981,8 @@ The corresponding @value{GDBN} command is @samp{ignore}.
|
| -break-insert main
|
| ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
|
| enabled="y",addr="0x000100d0",func="main",file="hello.c",
|
| -fullname="/home/foo/hello.c",line="5",times="0"@}
|
| +fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
|
| +times="0"@}
|
| (gdb)
|
| -break-after 1 3
|
| ~
|
| @@ -27878,7 +29998,7 @@ hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
|
| @{width="40",alignment="2",col_name="what",colhdr="What"@}],
|
| body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
| -line="5",times="0",ignore="3"@}]@}
|
| +line="5",thread-groups=["i1"],times="0",ignore="3"@}]@}
|
| (gdb)
|
| @end smallexample
|
|
|
| @@ -27914,7 +30034,8 @@ The corresponding @value{GDBN} command is @samp{commands}.
|
| -break-insert main
|
| ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
|
| enabled="y",addr="0x000100d0",func="main",file="hello.c",
|
| -fullname="/home/foo/hello.c",line="5",times="0"@}
|
| +fullname="/home/foo/hello.c",line="5",thread-groups=["i1"],
|
| +times="0"@}
|
| (gdb)
|
| -break-commands 1 "print v" "continue"
|
| ^done
|
| @@ -27956,7 +30077,7 @@ hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
|
| @{width="40",alignment="2",col_name="what",colhdr="What"@}],
|
| body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
| -line="5",cond="1",times="0",ignore="3"@}]@}
|
| +line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"@}]@}
|
| (gdb)
|
| @end smallexample
|
|
|
| @@ -28028,7 +30149,7 @@ hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
|
| @{width="40",alignment="2",col_name="what",colhdr="What"@}],
|
| body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
|
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
| -line="5",times="0"@}]@}
|
| +line="5",thread-groups=["i1"],times="0"@}]@}
|
| (gdb)
|
| @end smallexample
|
|
|
| @@ -28064,7 +30185,7 @@ hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
|
| @{width="40",alignment="2",col_name="what",colhdr="What"@}],
|
| body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
|
| -line="5",times="0"@}]@}
|
| +line="5",thread-groups=["i1"],times="0"@}]@}
|
| (gdb)
|
| @end smallexample
|
|
|
| @@ -28080,6 +30201,10 @@ line="5",times="0"@}]@}
|
| @c REDUNDANT???
|
| Get information about a single breakpoint.
|
|
|
| +The result is a table of breakpoints. @xref{GDB/MI Breakpoint
|
| +Information}, for details on the format of each breakpoint in the
|
| +table.
|
| +
|
| @subsubheading @value{GDBN} Command
|
|
|
| The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
|
| @@ -28139,23 +30264,8 @@ Restrict the breakpoint to the specified @var{thread-id}.
|
|
|
| @subsubheading Result
|
|
|
| -The result is in the form:
|
| -
|
| -@smallexample
|
| -^done,bkpt=@{number="@var{number}",type="@var{type}",disp="del"|"keep",
|
| -enabled="y"|"n",addr="@var{hex}",func="@var{funcname}",file="@var{filename}",
|
| -fullname="@var{full_filename}",line="@var{lineno}",[thread="@var{threadno},]
|
| -times="@var{times}"@}
|
| -@end smallexample
|
| -
|
| -@noindent
|
| -where @var{number} is the @value{GDBN} number for this breakpoint,
|
| -@var{funcname} is the name of the function where the breakpoint was
|
| -inserted, @var{filename} is the name of the source file which contains
|
| -this function, @var{lineno} is the source line number within that file
|
| -and @var{times} the number of times that the breakpoint has been hit
|
| -(always 0 for -break-insert but may be greater for -break-info or -break-list
|
| -which use the same output).
|
| +@xref{GDB/MI Breakpoint Information}, for details on the format of the
|
| +resulting breakpoint.
|
|
|
| Note: this format is open to change.
|
| @c An out-of-band breakpoint instead of part of the result?
|
| @@ -28171,11 +30281,13 @@ The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
|
| (gdb)
|
| -break-insert main
|
| ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
|
| -fullname="/home/foo/recursive2.c,line="4",times="0"@}
|
| +fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"],
|
| +times="0"@}
|
| (gdb)
|
| -break-insert -t foo
|
| ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
|
| -fullname="/home/foo/recursive2.c,line="11",times="0"@}
|
| +fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"],
|
| +times="0"@}
|
| (gdb)
|
| -break-list
|
| ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
|
| @@ -28187,18 +30299,99 @@ hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
|
| @{width="40",alignment="2",col_name="what",colhdr="What"@}],
|
| body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x0001072c", func="main",file="recursive2.c",
|
| -fullname="/home/foo/recursive2.c,"line="4",times="0"@},
|
| +fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"],
|
| +times="0"@},
|
| bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
|
| addr="0x00010774",func="foo",file="recursive2.c",
|
| -fullname="/home/foo/recursive2.c",line="11",times="0"@}]@}
|
| +fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
|
| +times="0"@}]@}
|
| (gdb)
|
| @c -break-insert -r foo.*
|
| @c ~int foo(int, int);
|
| @c ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
|
| -@c "fullname="/home/foo/recursive2.c",line="11",times="0"@}
|
| +@c "fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
|
| +@c times="0"@}
|
| @c (gdb)
|
| @end smallexample
|
|
|
| +@subheading The @code{-dprintf-insert} Command
|
| +@findex -dprintf-insert
|
| +
|
| +@subsubheading Synopsis
|
| +
|
| +@smallexample
|
| + -dprintf-insert [ -t ] [ -f ] [ -d ]
|
| + [ -c @var{condition} ] [ -i @var{ignore-count} ]
|
| + [ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ]
|
| + [ @var{argument} ]
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +If specified, @var{location}, can be one of:
|
| +
|
| +@itemize @bullet
|
| +@item @var{function}
|
| +@c @item +offset
|
| +@c @item -offset
|
| +@c @item @var{linenum}
|
| +@item @var{filename}:@var{linenum}
|
| +@item @var{filename}:function
|
| +@item *@var{address}
|
| +@end itemize
|
| +
|
| +The possible optional parameters of this command are:
|
| +
|
| +@table @samp
|
| +@item -t
|
| +Insert a temporary breakpoint.
|
| +@item -f
|
| +If @var{location} cannot be parsed (for example, if it
|
| +refers to unknown files or functions), create a pending
|
| +breakpoint. Without this flag, @value{GDBN} will report
|
| +an error, and won't create a breakpoint, if @var{location}
|
| +cannot be parsed.
|
| +@item -d
|
| +Create a disabled breakpoint.
|
| +@item -c @var{condition}
|
| +Make the breakpoint conditional on @var{condition}.
|
| +@item -i @var{ignore-count}
|
| +Set the ignore count of the breakpoint (@pxref{Conditions, ignore count})
|
| +to @var{ignore-count}.
|
| +@item -p @var{thread-id}
|
| +Restrict the breakpoint to the specified @var{thread-id}.
|
| +@end table
|
| +
|
| +@subsubheading Result
|
| +
|
| +@xref{GDB/MI Breakpoint Information}, for details on the format of the
|
| +resulting breakpoint.
|
| +
|
| +@c An out-of-band breakpoint instead of part of the result?
|
| +
|
| +@subsubheading @value{GDBN} Command
|
| +
|
| +The corresponding @value{GDBN} command is @samp{dprintf}.
|
| +
|
| +@subsubheading Example
|
| +
|
| +@smallexample
|
| +(gdb)
|
| +4-dprintf-insert foo "At foo entry\n"
|
| +4^done,bkpt=@{number="1",type="dprintf",disp="keep",enabled="y",
|
| +addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
|
| +fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
|
| +times="0",script=@{"printf \"At foo entry\\n\"","continue"@},
|
| +original-location="foo"@}
|
| +(gdb)
|
| +5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
|
| +5^done,bkpt=@{number="2",type="dprintf",disp="keep",enabled="y",
|
| +addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
|
| +fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
|
| +times="0",script=@{"printf \"arg=%d, g=%d\\n\", arg, g","continue"@},
|
| +original-location="mi-dprintf.c:26"@}
|
| +(gdb)
|
| +@end smallexample
|
| +
|
| @subheading The @code{-break-list} Command
|
| @findex -break-list
|
|
|
| @@ -28225,6 +30418,8 @@ memory location at which the breakpoint is set
|
| @item What
|
| logical location of the breakpoint, expressed by function name, file
|
| name, line number
|
| +@item Thread-groups
|
| +list of thread groups to which this breakpoint applies
|
| @item Times
|
| number of times the breakpoint has been hit
|
| @end table
|
| @@ -28249,10 +30444,11 @@ hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
|
| @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
|
| @{width="40",alignment="2",col_name="what",colhdr="What"@}],
|
| body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
|
| -addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
|
| +addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"],
|
| +times="0"@},
|
| bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
|
| -line="13",times="0"@}]@}
|
| +line="13",thread-groups=["i1"],times="0"@}]@}
|
| (gdb)
|
| @end smallexample
|
|
|
| @@ -28380,9 +30576,10 @@ hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
|
| body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x00010734",func="callee4",
|
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
| -fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"@},
|
| +fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"],
|
| +times="1"@},
|
| bkpt=@{number="2",type="watchpoint",disp="keep",
|
| -enabled="y",addr="",what="C",times="0"@}]@}
|
| +enabled="y",addr="",what="C",thread-groups=["i1"],times="0"@}]@}
|
| (gdb)
|
| -exec-continue
|
| ^running
|
| @@ -28404,9 +30601,10 @@ hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
|
| body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x00010734",func="callee4",
|
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
| -fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
|
| +fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"],
|
| +times="1"@},
|
| bkpt=@{number="2",type="watchpoint",disp="keep",
|
| -enabled="y",addr="",what="C",times="-5"@}]@}
|
| +enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"@}]@}
|
| (gdb)
|
| -exec-continue
|
| ^running
|
| @@ -28428,7 +30626,173 @@ body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x00010734",func="callee4",
|
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
|
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
|
| -times="1"@}]@}
|
| +thread-groups=["i1"],times="1"@}]@}
|
| +(gdb)
|
| +@end smallexample
|
| +
|
| +
|
| +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
| +@node GDB/MI Catchpoint Commands
|
| +@section @sc{gdb/mi} Catchpoint Commands
|
| +
|
| +This section documents @sc{gdb/mi} commands for manipulating
|
| +catchpoints.
|
| +
|
| +@menu
|
| +* Shared Library GDB/MI Catchpoint Commands::
|
| +* Ada Exception GDB/MI Catchpoint Commands::
|
| +@end menu
|
| +
|
| +@node Shared Library GDB/MI Catchpoint Commands
|
| +@subsection Shared Library @sc{gdb/mi} Catchpoints
|
| +
|
| +@subheading The @code{-catch-load} Command
|
| +@findex -catch-load
|
| +
|
| +@subsubheading Synopsis
|
| +
|
| +@smallexample
|
| + -catch-load [ -t ] [ -d ] @var{regexp}
|
| +@end smallexample
|
| +
|
| +Add a catchpoint for library load events. If the @samp{-t} option is used,
|
| +the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting
|
| +Breakpoints}). If the @samp{-d} option is used, the catchpoint is created
|
| +in a disabled state. The @samp{regexp} argument is a regular
|
| +expression used to match the name of the loaded library.
|
| +
|
| +
|
| +@subsubheading @value{GDBN} Command
|
| +
|
| +The corresponding @value{GDBN} command is @samp{catch load}.
|
| +
|
| +@subsubheading Example
|
| +
|
| +@smallexample
|
| +-catch-load -t foo.so
|
| +^done,bkpt=@{number="1",type="catchpoint",disp="del",enabled="y",
|
| +what="load of library matching foo.so",catch-type="load",times="0"@}
|
| +(gdb)
|
| +@end smallexample
|
| +
|
| +
|
| +@subheading The @code{-catch-unload} Command
|
| +@findex -catch-unload
|
| +
|
| +@subsubheading Synopsis
|
| +
|
| +@smallexample
|
| + -catch-unload [ -t ] [ -d ] @var{regexp}
|
| +@end smallexample
|
| +
|
| +Add a catchpoint for library unload events. If the @samp{-t} option is
|
| +used, the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting
|
| +Breakpoints}). If the @samp{-d} option is used, the catchpoint is
|
| +created in a disabled state. The @samp{regexp} argument is a regular
|
| +expression used to match the name of the unloaded library.
|
| +
|
| +@subsubheading @value{GDBN} Command
|
| +
|
| +The corresponding @value{GDBN} command is @samp{catch unload}.
|
| +
|
| +@subsubheading Example
|
| +
|
| +@smallexample
|
| +-catch-unload -d bar.so
|
| +^done,bkpt=@{number="2",type="catchpoint",disp="keep",enabled="n",
|
| +what="load of library matching bar.so",catch-type="unload",times="0"@}
|
| +(gdb)
|
| +@end smallexample
|
| +
|
| +@node Ada Exception GDB/MI Catchpoint Commands
|
| +@subsection Ada Exception @sc{gdb/mi} Catchpoints
|
| +
|
| +The following @sc{gdb/mi} commands can be used to create catchpoints
|
| +that stop the execution when Ada exceptions are being raised.
|
| +
|
| +@subheading The @code{-catch-assert} Command
|
| +@findex -catch-assert
|
| +
|
| +@subsubheading Synopsis
|
| +
|
| +@smallexample
|
| + -catch-assert [ -c @var{condition}] [ -d ] [ -t ]
|
| +@end smallexample
|
| +
|
| +Add a catchpoint for failed Ada assertions.
|
| +
|
| +The possible optional parameters for this command are:
|
| +
|
| +@table @samp
|
| +@item -c @var{condition}
|
| +Make the catchpoint conditional on @var{condition}.
|
| +@item -d
|
| +Create a disabled catchpoint.
|
| +@item -t
|
| +Create a temporary catchpoint.
|
| +@end table
|
| +
|
| +@subsubheading @value{GDBN} Command
|
| +
|
| +The corresponding @value{GDBN} command is @samp{catch assert}.
|
| +
|
| +@subsubheading Example
|
| +
|
| +@smallexample
|
| +-catch-assert
|
| +^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep",
|
| +enabled="y",addr="0x0000000000404888",what="failed Ada assertions",
|
| +thread-groups=["i1"],times="0",
|
| +original-location="__gnat_debug_raise_assert_failure"@}
|
| +(gdb)
|
| +@end smallexample
|
| +
|
| +@subheading The @code{-catch-exception} Command
|
| +@findex -catch-exception
|
| +
|
| +@subsubheading Synopsis
|
| +
|
| +@smallexample
|
| + -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
|
| + [ -t ] [ -u ]
|
| +@end smallexample
|
| +
|
| +Add a catchpoint stopping when Ada exceptions are raised.
|
| +By default, the command stops the program when any Ada exception
|
| +gets raised. But it is also possible, by using some of the
|
| +optional parameters described below, to create more selective
|
| +catchpoints.
|
| +
|
| +The possible optional parameters for this command are:
|
| +
|
| +@table @samp
|
| +@item -c @var{condition}
|
| +Make the catchpoint conditional on @var{condition}.
|
| +@item -d
|
| +Create a disabled catchpoint.
|
| +@item -e @var{exception-name}
|
| +Only stop when @var{exception-name} is raised. This option cannot
|
| +be used combined with @samp{-u}.
|
| +@item -t
|
| +Create a temporary catchpoint.
|
| +@item -u
|
| +Stop only when an unhandled exception gets raised. This option
|
| +cannot be used combined with @samp{-e}.
|
| +@end table
|
| +
|
| +@subsubheading @value{GDBN} Command
|
| +
|
| +The corresponding @value{GDBN} commands are @samp{catch exception}
|
| +and @samp{catch exception unhandled}.
|
| +
|
| +@subsubheading Example
|
| +
|
| +@smallexample
|
| +-catch-exception -e Program_Error
|
| +^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
|
| +enabled="y",addr="0x0000000000404874",
|
| +what="`Program_Error' Ada exception", thread-groups=["i1"],
|
| +times="0",original-location="__gnat_debug_raise_exception"@}
|
| (gdb)
|
| @end smallexample
|
|
|
| @@ -29176,7 +31540,7 @@ fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
|
| @subsubheading Synopsis
|
|
|
| @smallexample
|
| - -exec-run [--all | --thread-group N]
|
| + -exec-run [ --all | --thread-group N ] [ --start ]
|
| @end smallexample
|
|
|
| Starts execution of the inferior from the beginning. The inferior
|
| @@ -29184,11 +31548,17 @@ executes until either a breakpoint is encountered or the program
|
| exits. In the latter case the output will include an exit code, if
|
| the program has exited exceptionally.
|
|
|
| -When no option is specified, the current inferior is started. If the
|
| +When neither the @samp{--all} nor the @samp{--thread-group} option
|
| +is specified, the current inferior is started. If the
|
| @samp{--thread-group} option is specified, it should refer to a thread
|
| group of type @samp{process}, and that thread group will be started.
|
| If the @samp{--all} option is specified, then all inferiors will be started.
|
|
|
| +Using the @samp{--start} option instructs the debugger to stop
|
| +the execution at the start of the inferior's main subprogram,
|
| +following the same behavior as the @code{start} command
|
| +(@pxref{Starting}).
|
| +
|
| @subsubheading @value{GDBN} Command
|
|
|
| The corresponding @value{GDBN} command is @samp{run}.
|
| @@ -29378,6 +31748,22 @@ Is this going away????
|
| @node GDB/MI Stack Manipulation
|
| @section @sc{gdb/mi} Stack Manipulation Commands
|
|
|
| +@subheading The @code{-enable-frame-filters} Command
|
| +@findex -enable-frame-filters
|
| +
|
| +@smallexample
|
| +-enable-frame-filters
|
| +@end smallexample
|
| +
|
| +@value{GDBN} allows Python-based frame filters to affect the output of
|
| +the MI commands relating to stack traces. As there is no way to
|
| +implement this in a fully backward-compatible way, a front end must
|
| +request that this functionality be enabled.
|
| +
|
| +Once enabled, this feature cannot be disabled.
|
| +
|
| +Note that if Python support has not been compiled into @value{GDBN},
|
| +this command will still succeed (and do nothing).
|
|
|
| @subheading The @code{-stack-info-frame} Command
|
| @findex -stack-info-frame
|
| @@ -29445,13 +31831,14 @@ For a stack with frame levels 0 through 11:
|
| (gdb)
|
| @end smallexample
|
|
|
| +@anchor{-stack-list-arguments}
|
| @subheading The @code{-stack-list-arguments} Command
|
| @findex -stack-list-arguments
|
|
|
| @subsubheading Synopsis
|
|
|
| @smallexample
|
| - -stack-list-arguments @var{print-values}
|
| + -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
|
| [ @var{low-frame} @var{high-frame} ]
|
| @end smallexample
|
|
|
| @@ -29468,7 +31855,12 @@ If @var{print-values} is 0 or @code{--no-values}, print only the names of
|
| the variables; if it is 1 or @code{--all-values}, print also their
|
| values; and if it is 2 or @code{--simple-values}, print the name,
|
| type and value for simple data types, and the name and type for arrays,
|
| -structures and unions.
|
| +structures and unions. If the option @code{--no-frame-filters} is
|
| +supplied, then Python frame filters will not be executed.
|
| +
|
| +If the @code{--skip-unavailable} option is specified, arguments that
|
| +are not available are not listed. Partially available arguments
|
| +are still displayed, however.
|
|
|
| Use of this command to obtain arguments in a single frame is
|
| deprecated in favor of the @samp{-stack-list-variables} command.
|
| @@ -29539,13 +31931,14 @@ args=[@{name="intarg",value="2"@},
|
| @c @subheading -stack-list-exception-handlers
|
|
|
|
|
| +@anchor{-stack-list-frames}
|
| @subheading The @code{-stack-list-frames} Command
|
| @findex -stack-list-frames
|
|
|
| @subsubheading Synopsis
|
|
|
| @smallexample
|
| - -stack-list-frames [ @var{low-frame} @var{high-frame} ]
|
| + -stack-list-frames [ --no-frame-filters @var{low-frame} @var{high-frame} ]
|
| @end smallexample
|
|
|
| List the frames currently on the stack. For each frame it displays the
|
| @@ -29575,7 +31968,9 @@ levels are between the two arguments (inclusive). If the two arguments
|
| are equal, it shows the single frame at the corresponding level. It is
|
| an error if @var{low-frame} is larger than the actual number of
|
| frames. On the other hand, @var{high-frame} may be larger than the
|
| -actual number of frames, in which case only existing frames will be returned.
|
| +actual number of frames, in which case only existing frames will be
|
| +returned. If the option @code{--no-frame-filters} is supplied, then
|
| +Python frame filters will not be executed.
|
|
|
| @subsubheading @value{GDBN} Command
|
|
|
| @@ -29645,11 +32040,12 @@ Show a single frame:
|
|
|
| @subheading The @code{-stack-list-locals} Command
|
| @findex -stack-list-locals
|
| +@anchor{-stack-list-locals}
|
|
|
| @subsubheading Synopsis
|
|
|
| @smallexample
|
| - -stack-list-locals @var{print-values}
|
| + -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
|
| @end smallexample
|
|
|
| Display the local variable names for the selected frame. If
|
| @@ -29660,7 +32056,12 @@ type and value for simple data types, and the name and type for arrays,
|
| structures and unions. In this last case, a frontend can immediately
|
| display the value of simple data types and create variable objects for
|
| other data types when the user wishes to explore their values in
|
| -more detail.
|
| +more detail. If the option @code{--no-frame-filters} is supplied, then
|
| +Python frame filters will not be executed.
|
| +
|
| +If the @code{--skip-unavailable} option is specified, local variables
|
| +that are not available are not listed. Partially available local
|
| +variables are still displayed, however.
|
|
|
| This command is deprecated in favor of the
|
| @samp{-stack-list-variables} command.
|
| @@ -29685,13 +32086,14 @@ This command is deprecated in favor of the
|
| (gdb)
|
| @end smallexample
|
|
|
| +@anchor{-stack-list-variables}
|
| @subheading The @code{-stack-list-variables} Command
|
| @findex -stack-list-variables
|
|
|
| @subsubheading Synopsis
|
|
|
| @smallexample
|
| - -stack-list-variables @var{print-values}
|
| + -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values}
|
| @end smallexample
|
|
|
| Display the names of local variables and function arguments for the selected frame. If
|
| @@ -29699,7 +32101,12 @@ Display the names of local variables and function arguments for the selected fra
|
| the variables; if it is 1 or @code{--all-values}, print also their
|
| values; and if it is 2 or @code{--simple-values}, print the name,
|
| type and value for simple data types, and the name and type for arrays,
|
| -structures and unions.
|
| +structures and unions. If the option @code{--no-frame-filters} is
|
| +supplied, then Python frame filters will not be executed.
|
| +
|
| +If the @code{--skip-unavailable} option is specified, local variables
|
| +and arguments that are not available are not listed. Partially
|
| +available arguments and local variables are still displayed, however.
|
|
|
| @subsubheading Example
|
|
|
| @@ -30184,6 +32591,17 @@ Otherwise this result is not present.
|
|
|
| @item frozen
|
| If the variable object is frozen, this variable will be present with a value of 1.
|
| +
|
| +@item displayhint
|
| +A dynamic varobj can supply a display hint to the front end. The
|
| +value comes directly from the Python pretty-printer object's
|
| +@code{display_hint} method. @xref{Pretty Printing API}.
|
| +
|
| +@item dynamic
|
| +This attribute will be present and have the value @samp{1} if the
|
| +varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
|
| +then this attribute will not be present.
|
| +
|
| @end table
|
|
|
| The result may have its own attributes:
|
| @@ -30253,7 +32671,8 @@ For example, if @code{a} is an array, and variable object
|
| @end smallexample
|
|
|
| @noindent
|
| -Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}.
|
| +Here, the value of @code{lang} is the language name, which can be
|
| +found in @ref{Supported Languages}.
|
|
|
| Note that the output of the @code{-var-list-children} command also
|
| includes those expressions, so the @code{-var-info-expression} command
|
| @@ -30658,21 +33077,69 @@ mixed source and disassembly with raw opcodes).
|
|
|
| @subsubheading Result
|
|
|
| -The output for each instruction is composed of four fields:
|
| +The result of the @code{-data-disassemble} command will be a list named
|
| +@samp{asm_insns}, the contents of this list depend on the @var{mode}
|
| +used with the @code{-data-disassemble} command.
|
|
|
| -@itemize @bullet
|
| -@item Address
|
| -@item Func-name
|
| -@item Offset
|
| -@item Instruction
|
| -@end itemize
|
| +For modes 0 and 2 the @samp{asm_insns} list contains tuples with the
|
| +following fields:
|
| +
|
| +@table @code
|
| +@item address
|
| +The address at which this instruction was disassembled.
|
| +
|
| +@item func-name
|
| +The name of the function this instruction is within.
|
| +
|
| +@item offset
|
| +The decimal offset in bytes from the start of @samp{func-name}.
|
| +
|
| +@item inst
|
| +The text disassembly for this @samp{address}.
|
| +
|
| +@item opcodes
|
| +This field is only present for mode 2. This contains the raw opcode
|
| +bytes for the @samp{inst} field.
|
| +
|
| +@end table
|
| +
|
| +For modes 1 and 3 the @samp{asm_insns} list contains tuples named
|
| +@samp{src_and_asm_line}, each of which has the following fields:
|
| +
|
| +@table @code
|
| +@item line
|
| +The line number within @samp{file}.
|
| +
|
| +@item file
|
| +The file name from the compilation unit. This might be an absolute
|
| +file name or a relative file name depending on the compile command
|
| +used.
|
| +
|
| +@item fullname
|
| +Absolute file name of @samp{file}. It is converted to a canonical form
|
| +using the source file search path
|
| +(@pxref{Source Path, ,Specifying Source Directories})
|
| +and after resolving all the symbolic links.
|
| +
|
| +If the source file is not found this field will contain the path as
|
| +present in the debug information.
|
| +
|
| +@item line_asm_insn
|
| +This is a list of tuples containing the disassembly for @samp{line} in
|
| +@samp{file}. The fields of each tuple are the same as for
|
| +@code{-data-disassemble} in @var{mode} 0 and 2, so @samp{address},
|
| +@samp{func-name}, @samp{offset}, @samp{inst}, and optionally
|
| +@samp{opcodes}.
|
|
|
| -Note that whatever included in the instruction field, is not manipulated
|
| -directly by @sc{gdb/mi}, i.e., it is not possible to adjust its format.
|
| +@end table
|
| +
|
| +Note that whatever included in the @samp{inst} field, is not
|
| +manipulated directly by @sc{gdb/mi}, i.e., it is not possible to
|
| +adjust its format.
|
|
|
| @subsubheading @value{GDBN} Command
|
|
|
| -There's no direct mapping from this command to the CLI.
|
| +The corresponding @value{GDBN} command is @samp{disassemble}.
|
|
|
| @subsubheading Example
|
|
|
| @@ -30736,15 +33203,15 @@ Disassemble 3 instructions from the start of @code{main} in mixed mode:
|
| -data-disassemble -f basics.c -l 32 -n 3 -- 1
|
| ^done,asm_insns=[
|
| src_and_asm_line=@{line="31",
|
| -file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
|
| - testsuite/gdb.mi/basics.c",line_asm_insn=[
|
| -@{address="0x000107bc",func-name="main",offset="0",
|
| -inst="save %sp, -112, %sp"@}]@},
|
| +file="../../../src/gdb/testsuite/gdb.mi/basics.c",
|
| +fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
|
| +line_asm_insn=[@{address="0x000107bc",
|
| +func-name="main",offset="0",inst="save %sp, -112, %sp"@}]@},
|
| src_and_asm_line=@{line="32",
|
| -file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
|
| - testsuite/gdb.mi/basics.c",line_asm_insn=[
|
| -@{address="0x000107c0",func-name="main",offset="4",
|
| -inst="mov 2, %o0"@},
|
| +file="../../../src/gdb/testsuite/gdb.mi/basics.c",
|
| +fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
|
| +line_asm_insn=[@{address="0x000107c0",
|
| +func-name="main",offset="4",inst="mov 2, %o0"@},
|
| @{address="0x000107c4",func-name="main",offset="8",
|
| inst="sethi %hi(0x11800), %o2"@}]@}]
|
| (gdb)
|
| @@ -30878,13 +33345,16 @@ For the PPC MBX board:
|
| @subsubheading Synopsis
|
|
|
| @smallexample
|
| - -data-list-register-values @var{fmt} [ ( @var{regno} )*]
|
| + -data-list-register-values
|
| + [ @code{--skip-unavailable} ] @var{fmt} [ ( @var{regno} )*]
|
| @end smallexample
|
|
|
| Display the registers' contents. @var{fmt} is the format according to
|
| which the registers' contents are to be returned, followed by an optional
|
| list of numbers specifying the registers to display. A missing list of
|
| -numbers indicates that the contents of all the registers must be returned.
|
| +numbers indicates that the contents of all the registers must be
|
| +returned. The @code{--skip-unavailable} option indicates that only
|
| +the available registers are to be returned.
|
|
|
| Allowed formats for @var{fmt} are:
|
|
|
| @@ -31168,6 +33638,7 @@ The corresponding @value{GDBN} command is @samp{x}.
|
|
|
| @smallexample
|
| -data-write-memory-bytes @var{address} @var{contents}
|
| + -data-write-memory-bytes @var{address} @var{contents} @r{[}@var{count}@r{]}
|
| @end smallexample
|
|
|
| @noindent
|
| @@ -31182,6 +33653,11 @@ quoted using the C convention.
|
| @item @var{contents}
|
| The hex-encoded bytes to write.
|
|
|
| +@item @var{count}
|
| +Optional argument indicating the number of bytes to be written. If @var{count}
|
| +is greater than @var{contents}' length, @value{GDBN} will repeatedly
|
| +write @var{contents} until it fills @var{count} bytes.
|
| +
|
| @end table
|
|
|
| @subsubheading @value{GDBN} Command
|
| @@ -31197,6 +33673,12 @@ There's no corresponding @value{GDBN} command.
|
| (gdb)
|
| @end smallexample
|
|
|
| +@smallexample
|
| +(gdb)
|
| +-data-write-memory-bytes &a "aabbccdd" 16e
|
| +^done
|
| +(gdb)
|
| +@end smallexample
|
|
|
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
| @node GDB/MI Tracepoint Commands
|
| @@ -31298,6 +33780,123 @@ with the @samp{$} character.
|
|
|
| The corresponding @value{GDBN} command is @samp{tvariable}.
|
|
|
| +@subheading The @code{-trace-frame-collected} Command
|
| +@findex -trace-frame-collected
|
| +
|
| +@subsubheading Synopsis
|
| +
|
| +@smallexample
|
| + -trace-frame-collected
|
| + [--var-print-values @var{var_pval}]
|
| + [--comp-print-values @var{comp_pval}]
|
| + [--registers-format @var{regformat}]
|
| + [--memory-contents]
|
| +@end smallexample
|
| +
|
| +This command returns the set of collected objects, register names,
|
| +trace state variable names, memory ranges and computed expressions
|
| +that have been collected at a particular trace frame. The optional
|
| +parameters to the command affect the output format in different ways.
|
| +See the output description table below for more details.
|
| +
|
| +The reported names can be used in the normal manner to create
|
| +varobjs and inspect the objects themselves. The items returned by
|
| +this command are categorized so that it is clear which is a variable,
|
| +which is a register, which is a trace state variable, which is a
|
| +memory range and which is a computed expression.
|
| +
|
| +For instance, if the actions were
|
| +@smallexample
|
| +collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2
|
| +collect *(int*)0xaf02bef0@@40
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +the object collected in its entirety would be @code{myVar}. The
|
| +object @code{myArray} would be partially collected, because only the
|
| +element at index @code{myIndex} would be collected. The remaining
|
| +objects would be computed expressions.
|
| +
|
| +An example output would be:
|
| +
|
| +@smallexample
|
| +(gdb)
|
| +-trace-frame-collected
|
| +^done,
|
| + explicit-variables=[@{name="myVar",value="1"@}],
|
| + computed-expressions=[@{name="myArray[myIndex]",value="0"@},
|
| + @{name="myObj.field",value="0"@},
|
| + @{name="myPtr->field",value="1"@},
|
| + @{name="myCount + 2",value="3"@},
|
| + @{name="$tvar1 + 1",value="43970027"@}],
|
| + registers=[@{number="0",value="0x7fe2c6e79ec8"@},
|
| + @{number="1",value="0x0"@},
|
| + @{number="2",value="0x4"@},
|
| + ...
|
| + @{number="125",value="0x0"@}],
|
| + tvars=[@{name="$tvar1",current="43970026"@}],
|
| + memory=[@{address="0x0000000000602264",length="4"@},
|
| + @{address="0x0000000000615bc0",length="4"@}]
|
| +(gdb)
|
| +@end smallexample
|
| +
|
| +Where:
|
| +
|
| +@table @code
|
| +@item explicit-variables
|
| +The set of objects that have been collected in their entirety (as
|
| +opposed to collecting just a few elements of an array or a few struct
|
| +members). For each object, its name and value are printed.
|
| +The @code{--var-print-values} option affects how or whether the value
|
| +field is output. If @var{var_pval} is 0, then print only the names;
|
| +if it is 1, print also their values; and if it is 2, print the name,
|
| +type and value for simple data types, and the name and type for
|
| +arrays, structures and unions.
|
| +
|
| +@item computed-expressions
|
| +The set of computed expressions that have been collected at the
|
| +current trace frame. The @code{--comp-print-values} option affects
|
| +this set like the @code{--var-print-values} option affects the
|
| +@code{explicit-variables} set. See above.
|
| +
|
| +@item registers
|
| +The registers that have been collected at the current trace frame.
|
| +For each register collected, the name and current value are returned.
|
| +The value is formatted according to the @code{--registers-format}
|
| +option. See the @command{-data-list-register-values} command for a
|
| +list of the allowed formats. The default is @samp{x}.
|
| +
|
| +@item tvars
|
| +The trace state variables that have been collected at the current
|
| +trace frame. For each trace state variable collected, the name and
|
| +current value are returned.
|
| +
|
| +@item memory
|
| +The set of memory ranges that have been collected at the current trace
|
| +frame. Its content is a list of tuples. Each tuple represents a
|
| +collected memory range and has the following fields:
|
| +
|
| +@table @code
|
| +@item address
|
| +The start address of the memory range, as hexadecimal literal.
|
| +
|
| +@item length
|
| +The length of the memory range, as decimal literal.
|
| +
|
| +@item contents
|
| +The contents of the memory block, in hex. This field is only present
|
| +if the @code{--memory-contents} option is specified.
|
| +
|
| +@end table
|
| +
|
| +@end table
|
| +
|
| +@subsubheading @value{GDBN} Command
|
| +
|
| +There is no corresponding @value{GDBN} command.
|
| +
|
| +@subsubheading Example
|
| +
|
| @subheading -trace-list-variables
|
| @findex -trace-list-variables
|
|
|
| @@ -31444,6 +34043,10 @@ The value of the disconnected tracing flag. @code{1} means that
|
| tracing will continue after @value{GDBN} disconnects, @code{0} means
|
| that the trace run will stop.
|
|
|
| +@item trace-file
|
| +The filename of the trace file being examined. This field is
|
| +optional, and only present when examining a trace file.
|
| +
|
| @end table
|
|
|
| @subsubheading @value{GDBN} Command
|
| @@ -31824,8 +34427,8 @@ The @value{GDBN} equivalent is @samp{info source}
|
|
|
| List the source files for the current executable.
|
|
|
| -It will always output the filename, but only when @value{GDBN} can find
|
| -the absolute file name of a source file, will it output the fullname.
|
| +It will always output both the filename and fullname (absolute file
|
| +name) of a source file.
|
|
|
| @subsubheading @value{GDBN} Command
|
|
|
| @@ -32359,6 +34962,59 @@ The corresponding @value{GDBN} command is @samp{remote delete}.
|
|
|
|
|
| @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
| +@node GDB/MI Ada Exceptions Commands
|
| +@section Ada Exceptions @sc{gdb/mi} Commands
|
| +
|
| +@subheading The @code{-info-ada-exceptions} Command
|
| +@findex -info-ada-exceptions
|
| +
|
| +@subsubheading Synopsis
|
| +
|
| +@smallexample
|
| + -info-ada-exceptions [ @var{regexp}]
|
| +@end smallexample
|
| +
|
| +List all Ada exceptions defined within the program being debugged.
|
| +With a regular expression @var{regexp}, only those exceptions whose
|
| +names match @var{regexp} are listed.
|
| +
|
| +@subsubheading @value{GDBN} Command
|
| +
|
| +The corresponding @value{GDBN} command is @samp{info exceptions}.
|
| +
|
| +@subsubheading Result
|
| +
|
| +The result is a table of Ada exceptions. The following columns are
|
| +defined for each exception:
|
| +
|
| +@table @samp
|
| +@item name
|
| +The name of the exception.
|
| +
|
| +@item address
|
| +The address of the exception.
|
| +
|
| +@end table
|
| +
|
| +@subsubheading Example
|
| +
|
| +@smallexample
|
| +-info-ada-exceptions aint
|
| +^done,ada-exceptions=@{nr_rows="2",nr_cols="2",
|
| +hdr=[@{width="1",alignment="-1",col_name="name",colhdr="Name"@},
|
| +@{width="1",alignment="-1",col_name="address",colhdr="Address"@}],
|
| +body=[@{name="constraint_error",address="0x0000000000613da0"@},
|
| +@{name="const.aint_global_e",address="0x0000000000613b00"@}]@}
|
| +@end smallexample
|
| +
|
| +@subheading Catching Ada Exceptions
|
| +
|
| +The commands describing how to ask @value{GDBN} to stop when a program
|
| +raises an exception are described at @ref{Ada Exception GDB/MI
|
| +Catchpoint Commands}.
|
| +
|
| +
|
| +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
| @node GDB/MI Miscellaneous Commands
|
| @section Miscellaneous @sc{gdb/mi} Commands
|
|
|
| @@ -32499,6 +35155,57 @@ default shows this information when you start an interactive session.
|
| (gdb)
|
| @end smallexample
|
|
|
| +@subheading The @code{-info-gdb-mi-command} Command
|
| +@cindex @code{-info-gdb-mi-command}
|
| +@findex -info-gdb-mi-command
|
| +
|
| +@subsubheading Synopsis
|
| +
|
| +@smallexample
|
| + -info-gdb-mi-command @var{cmd_name}
|
| +@end smallexample
|
| +
|
| +Query support for the @sc{gdb/mi} command named @var{cmd_name}.
|
| +
|
| +Note that the dash (@code{-}) starting all @sc{gdb/mi} commands
|
| +is technically not part of the command name (@pxref{GDB/MI Input
|
| +Syntax}), and thus should be omitted in @var{cmd_name}. However,
|
| +for ease of use, this command also accepts the form with the leading
|
| +dash.
|
| +
|
| +@subsubheading @value{GDBN} Command
|
| +
|
| +There is no corresponding @value{GDBN} command.
|
| +
|
| +@subsubheading Result
|
| +
|
| +The result is a tuple. There is currently only one field:
|
| +
|
| +@table @samp
|
| +@item exists
|
| +This field is equal to @code{"true"} if the @sc{gdb/mi} command exists,
|
| +@code{"false"} otherwise.
|
| +
|
| +@end table
|
| +
|
| +@subsubheading Example
|
| +
|
| +Here is an example where the @sc{gdb/mi} command does not exist:
|
| +
|
| +@smallexample
|
| +-info-gdb-mi-command unsupported-command
|
| +^done,command=@{exists="false"@}
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +And here is an example where the @sc{gdb/mi} command is known
|
| +to the debugger:
|
| +
|
| +@smallexample
|
| +-info-gdb-mi-command symbol-list-lines
|
| +^done,command=@{exists="true"@}
|
| +@end smallexample
|
| +
|
| @subheading The @code{-list-features} Command
|
| @findex -list-features
|
|
|
| @@ -32545,6 +35252,18 @@ Indicates that changes to breakpoints and breakpoints created via the
|
| CLI will be announced via async records.
|
| @item ada-task-info
|
| Indicates support for the @code{-ada-task-info} command.
|
| +@item language-option
|
| +Indicates that all @sc{gdb/mi} commands accept the @option{--language}
|
| +option (@pxref{Context management}).
|
| +@item info-gdb-mi-command
|
| +Indicates support for the @code{-info-gdb-mi-command} command.
|
| +@item undefined-command-error-code
|
| +Indicates support for the "undefined-command" error code in error result
|
| +records, produced when trying to execute an undefined @sc{gdb/mi} command
|
| +(@pxref{GDB/MI Result Records}).
|
| +@item exec-run-start-option
|
| +Indicates that the @code{-exec-run} command supports the @option{--start}
|
| +option (@pxref{GDB/MI Program Execution}).
|
| @end table
|
|
|
| @subheading The @code{-list-target-features} Command
|
| @@ -32560,7 +35279,7 @@ may change, and the frontend should obtain it again.
|
| Example output:
|
|
|
| @smallexample
|
| -(gdb) -list-features
|
| +(gdb) -list-target-features
|
| ^done,result=["async"]
|
| @end smallexample
|
|
|
| @@ -32780,7 +35499,7 @@ Creates a new inferior (@pxref{Inferiors and Programs}). The created
|
| inferior is not associated with any executable. Such association may
|
| be established with the @samp{-file-exec-and-symbols} command
|
| (@pxref{GDB/MI File Commands}). The command response has a single
|
| -field, @samp{thread-group}, whose value is the identifier of the
|
| +field, @samp{inferior}, whose value is the identifier of the
|
| thread group corresponding to the new inferior.
|
|
|
| @subheading Example
|
| @@ -32788,7 +35507,7 @@ thread group corresponding to the new inferior.
|
| @smallexample
|
| @value{GDBP}
|
| -add-inferior
|
| -^done,thread-group="i3"
|
| +^done,inferior="i3"
|
| @end smallexample
|
|
|
| @subheading The @code{-interpreter-exec} Command
|
| @@ -32898,7 +35617,8 @@ No equivalent.
|
| -break-insert main
|
| ^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
|
| addr="0x080484ed",func="main",file="myprog.c",
|
| -fullname="/home/nickrob/myprog.c",line="73",times="0"@},
|
| +fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"],
|
| +times="0"@},
|
| time=@{wallclock="0.05185",user="0.00800",system="0.00000"@}
|
| (gdb)
|
| -enable-timings no
|
| @@ -33411,15 +36131,19 @@ 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-load @var{reader}
|
| +Load the JIT reader named @var{reader}. @var{reader} is a shared
|
| +object specified as either an absolute or a relative file name. In
|
| +the latter case, @value{GDBN} will try to load the reader from a
|
| +pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX
|
| +system (here @var{libdir} is the system library directory, often
|
| +@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-unload} and then invoking
|
| +@code{jit-reader-load}.
|
|
|
| @item jit-reader-unload
|
| Unload the currently loaded JIT reader.
|
| @@ -33680,6 +36404,10 @@ for an error
|
|
|
| @end table
|
|
|
| +@item close
|
| +Closes the in-process agent. This command is sent when @value{GDBN} or GDBserver
|
| +is about to kill inferiors.
|
| +
|
| @item qTfSTM
|
| @xref{qTfSTM}.
|
| @item qTsSTM
|
| @@ -33832,6 +36560,12 @@ The type of machine you are using, and the operating system name and
|
| version number.
|
|
|
| @item
|
| +The details of the @value{GDBN} build-time configuration.
|
| +@value{GDBN} shows these details if you invoke it with the
|
| +@option{--configuration} command-line option, or if you type
|
| +@code{show configuration} at @value{GDBN}'s prompt.
|
| +
|
| +@item
|
| What compiler (and its version) was used to compile @value{GDBN}---e.g.@:
|
| ``@value{GCC}--2.8.1''.
|
|
|
| @@ -34112,6 +36846,8 @@ or alternatively @pxref{Library List Format for SVR4 Targets})
|
| MS-Windows shared libraries (@pxref{Shared Libraries})
|
| @item
|
| Traceframe info (@pxref{Traceframe Info Format})
|
| +@item
|
| +Branch trace (@pxref{Branch Trace Format})
|
| @end itemize
|
|
|
| @item zlib
|
| @@ -34474,6 +37210,53 @@ then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit},
|
| wherever @value{GDBN} is installed.
|
| @end itemize
|
|
|
| +If the configured location of the system-wide init file (as given by the
|
| +@option{--with-system-gdbinit} option at configure time) is in the
|
| +data-directory (as specified by @option{--with-gdb-datadir} at configure
|
| +time) or in one of its subdirectories, then @value{GDBN} will look for the
|
| +system-wide init file in the directory specified by the
|
| +@option{--data-directory} command-line option.
|
| +Note that the system-wide init file is only read once, during @value{GDBN}
|
| +initialization. If the data-directory is changed after @value{GDBN} has
|
| +started with the @code{set data-directory} command, the file will not be
|
| +reread.
|
| +
|
| +@menu
|
| +* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
|
| +@end menu
|
| +
|
| +@node System-wide Configuration Scripts
|
| +@subsection Installed System-wide Configuration Scripts
|
| +@cindex system-wide configuration scripts
|
| +
|
| +The @file{system-gdbinit} directory, located inside the data-directory
|
| +(as specified by @option{--with-gdb-datadir} at configure time) contains
|
| +a number of scripts which can be used as system-wide init files. To
|
| +automatically source those scripts at startup, @value{GDBN} should be
|
| +configured with @option{--with-system-gdbinit}. Otherwise, any user
|
| +should be able to source them by hand as needed.
|
| +
|
| +The following scripts are currently available:
|
| +@itemize @bullet
|
| +
|
| +@item @file{elinos.py}
|
| +@pindex elinos.py
|
| +@cindex ELinOS system-wide configuration script
|
| +This script is useful when debugging a program on an ELinOS target.
|
| +It takes advantage of the environment variables defined in a standard
|
| +ELinOS environment in order to determine the location of the system
|
| +shared libraries, and then sets the @samp{solib-absolute-prefix}
|
| +and @samp{solib-search-path} variables appropriately.
|
| +
|
| +@item @file{wrs-linux.py}
|
| +@pindex wrs-linux.py
|
| +@cindex Wind River Linux system-wide configuration script
|
| +This script is useful when debugging a program on a target running
|
| +Wind River Linux. It expects the @env{ENV_PREFIX} to be set to
|
| +the host-side sysroot used by the target system.
|
| +
|
| +@end itemize
|
| +
|
| @node Maintenance Commands
|
| @appendix Maintenance Commands
|
| @cindex maintenance commands
|
| @@ -34508,7 +37291,7 @@ If not, generate remote agent bytecode for current frame PC address.
|
| Translate the given format string and list of argument expressions
|
| into remote agent bytecodes and display them as a disassembled list.
|
| This command is useful for debugging the agent version of dynamic
|
| -printf (@pxref{Dynamic Printf}.
|
| +printf (@pxref{Dynamic Printf}).
|
|
|
| @kindex maint info breakpoints
|
| @item @anchor{maint info breakpoints}maint info breakpoints
|
| @@ -34543,6 +37326,11 @@ Shared library events.
|
|
|
| @end table
|
|
|
| +@kindex maint info bfds
|
| +@item maint info bfds
|
| +This prints information about each @code{bfd} object that is known to
|
| +@value{GDBN}. @xref{Top, , BFD, bfd, The Binary File Descriptor Library}.
|
| +
|
| @kindex set displaced-stepping
|
| @kindex show displaced-stepping
|
| @cindex displaced stepping support
|
| @@ -34571,9 +37359,20 @@ only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target
|
| architecture supports displaced stepping.
|
| @end table
|
|
|
| +@kindex maint check-psymtabs
|
| +@item maint check-psymtabs
|
| +Check the consistency of currently expanded psymtabs versus symtabs.
|
| +Use this to check, for example, whether a symbol is in one but not the other.
|
| +
|
| @kindex maint check-symtabs
|
| @item maint check-symtabs
|
| -Check the consistency of psymtabs and symtabs.
|
| +Check the consistency of currently expanded symtabs.
|
| +
|
| +@kindex maint expand-symtabs
|
| +@item maint expand-symtabs [@var{regexp}]
|
| +Expand symbol tables.
|
| +If @var{regexp} is specified, only expand symbol tables for file
|
| +names matching @var{regexp}.
|
|
|
| @kindex maint cplus first_component
|
| @item maint cplus first_component @var{name}
|
| @@ -34717,8 +37516,7 @@ including registers which aren't available on the target nor visible
|
| to user; the command @code{maint print register-groups} includes the
|
| groups that each register is a member of; and the command @code{maint
|
| print remote-registers} includes the remote target's register numbers
|
| -and offsets in the `G' packets. @xref{Registers,, Registers, gdbint,
|
| -@value{GDBN} Internals}.
|
| +and offsets in the `G' packets.
|
|
|
| These commands take an optional parameter, a file name to which to
|
| write the information.
|
| @@ -34749,10 +37547,11 @@ This command forces @value{GDBN} to flush its internal register cache.
|
|
|
| @kindex maint print objfiles
|
| @cindex info for known object files
|
| -@item maint print objfiles
|
| -Print a dump of all known object files. For each object file, this
|
| -command prints its name, address in memory, and all of its psymtabs
|
| -and symtabs.
|
| +@item maint print objfiles @r{[}@var{regexp}@r{]}
|
| +Print a dump of all known object files.
|
| +If @var{regexp} is specified, only print object files whose names
|
| +match @var{regexp}. For each object file, this command prints its name,
|
| +address in memory, and all of its psymtabs and symtabs.
|
|
|
| @kindex maint print section-scripts
|
| @cindex info for known .debug_gdb_scripts-loaded scripts
|
| @@ -34866,7 +37665,7 @@ compiled with the @samp{-pg} compiler option.
|
| @item maint set show-debug-regs
|
| @itemx maint show show-debug-regs
|
| Control whether to show variables that mirror the hardware debug
|
| -registers. Use @code{ON} to enable, @code{OFF} to disable. If
|
| +registers. Use @code{on} to enable, @code{off} to disable. If
|
| enabled, the debug registers values are shown when @value{GDBN} inserts or
|
| removes a hardware breakpoint or watchpoint, and when the inferior
|
| triggers a hardware-assisted breakpoint or watchpoint.
|
| @@ -34879,24 +37678,33 @@ Control whether to show all non zero areas within a 1k block starting
|
| at thread local base, when using the @samp{info w32 thread-information-block}
|
| command.
|
|
|
| -@kindex maint space
|
| -@cindex memory used by commands
|
| -@item maint space
|
| -Control whether to display memory usage for each command. If set to a
|
| -nonzero value, @value{GDBN} will display how much memory each command
|
| -took, following the command's own output. This can also be requested
|
| -by invoking @value{GDBN} with the @option{--statistics} command-line
|
| -switch (@pxref{Mode Options}).
|
| +@kindex maint set per-command
|
| +@kindex maint show per-command
|
| +@item maint set per-command
|
| +@itemx maint show per-command
|
| +@cindex resources used by commands
|
|
|
| -@kindex maint time
|
| -@cindex time of command execution
|
| -@item maint time
|
| -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
|
| +@value{GDBN} can display the resources used by each command.
|
| +This is useful in debugging performance problems.
|
| +
|
| +@table @code
|
| +@item maint set per-command space [on|off]
|
| +@itemx maint show per-command space
|
| +Enable or disable the printing of the memory used by GDB for each command.
|
| +If enabled, @value{GDBN} will display how much memory each command
|
| +took, following the command's own output.
|
| +This can also be requested by invoking @value{GDBN} with the
|
| +@option{--statistics} command-line switch (@pxref{Mode Options}).
|
| +
|
| +@item maint set per-command time [on|off]
|
| +@itemx maint show per-command time
|
| +Enable or disable the printing of the execution time of @value{GDBN}
|
| +for each command.
|
| +If enabled, @value{GDBN} will display how much time it
|
| took to execute each command, following the command's own output.
|
| 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.
|
| +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
|
| @@ -34904,6 +37712,34 @@ 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}).
|
|
|
| +@item maint set per-command symtab [on|off]
|
| +@itemx maint show per-command symtab
|
| +Enable or disable the printing of basic symbol table statistics
|
| +for each command.
|
| +If enabled, @value{GDBN} will display the following information:
|
| +
|
| +@enumerate a
|
| +@item
|
| +number of symbol tables
|
| +@item
|
| +number of primary symbol tables
|
| +@item
|
| +number of blocks in the blockvector
|
| +@end enumerate
|
| +@end table
|
| +
|
| +@kindex maint space
|
| +@cindex memory used by commands
|
| +@item maint space @var{value}
|
| +An alias for @code{maint set per-command space}.
|
| +A non-zero value enables it, zero disables it.
|
| +
|
| +@kindex maint time
|
| +@cindex time of command execution
|
| +@item maint time @var{value}
|
| +An alias for @code{maint set per-command time}.
|
| +A non-zero value enables it, zero disables it.
|
| +
|
| @kindex maint translate-address
|
| @item maint translate-address @r{[}@var{section}@r{]} @var{addr}
|
| Find the symbol stored at the location specified by the address
|
| @@ -34957,6 +37793,7 @@ Show the current setting of the target wait timeout.
|
| * Memory Map Format::
|
| * Thread List Format::
|
| * Traceframe Info Format::
|
| +* Branch Trace Format::
|
| @end menu
|
|
|
| @node Overview
|
| @@ -35429,7 +38266,7 @@ Reply:
|
| the register's value
|
| @item E @var{NN}
|
| for an error
|
| -@item
|
| +@item @w{}
|
| Indicating an unrecognized @var{query}.
|
| @end table
|
|
|
| @@ -35567,6 +38404,22 @@ Step.
|
| Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
|
| @item t
|
| Stop.
|
| +@item r @var{start},@var{end}
|
| +Step once, and then keep stepping as long as the thread stops at
|
| +addresses between @var{start} (inclusive) and @var{end} (exclusive).
|
| +The remote stub reports a stop reply when either the thread goes out
|
| +of the range or is stopped due to an unrelated reason, such as hitting
|
| +a breakpoint. @xref{range stepping}.
|
| +
|
| +If the range is empty (@var{start} == @var{end}), then the action
|
| +becomes equivalent to the @samp{s} action. In other words,
|
| +single-step once, and report the stop (even if the stepped instruction
|
| +jumps to @var{start}).
|
| +
|
| +(A stop reply may be sent at any point even if the PC is still within
|
| +the stepping range; for example, it is valid to implement this packet
|
| +in a degenerate way as a single instruction step operation.)
|
| +
|
| @end table
|
|
|
| The optional argument @var{addr} normally associated with the
|
| @@ -35599,7 +38452,7 @@ Reply:
|
| @item vCont@r{[};@var{action}@dots{}@r{]}
|
| The @samp{vCont} packet is supported. Each @var{action} is a supported
|
| command in the @samp{vCont} packet.
|
| -@item
|
| +@item @w{}
|
| The @samp{vCont} packet is not supported.
|
| @end table
|
|
|
| @@ -35696,19 +38549,8 @@ for success (@pxref{Stop Reply Packets})
|
| @end table
|
|
|
| @item vStopped
|
| -@anchor{vStopped packet}
|
| @cindex @samp{vStopped} packet
|
| -
|
| -In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
|
| -reply and prompt for the stub to report another one.
|
| -
|
| -Reply:
|
| -@table @samp
|
| -@item @r{Any stop packet}
|
| -if there is another unreported stop event (@pxref{Stop Reply Packets})
|
| -@item OK
|
| -if there are no unreported stop events
|
| -@end table
|
| +@xref{Notification Packets}.
|
|
|
| @item X @var{addr},@var{length}:@var{XX@dots{}}
|
| @anchor{X packet}
|
| @@ -35799,7 +38641,7 @@ Reply:
|
| @table @samp
|
| @item OK
|
| success
|
| -@item
|
| +@item @w{}
|
| not supported
|
| @item E @var{NN}
|
| for an error
|
| @@ -35823,7 +38665,7 @@ Reply:
|
| @table @samp
|
| @item OK
|
| success
|
| -@item
|
| +@item @w{}
|
| not supported
|
| @item E @var{NN}
|
| for an error
|
| @@ -35840,7 +38682,7 @@ Reply:
|
| @table @samp
|
| @item OK
|
| success
|
| -@item
|
| +@item @w{}
|
| not supported
|
| @item E @var{NN}
|
| for an error
|
| @@ -35857,7 +38699,7 @@ Reply:
|
| @table @samp
|
| @item OK
|
| success
|
| -@item
|
| +@item @w{}
|
| not supported
|
| @item E @var{NN}
|
| for an error
|
| @@ -35874,7 +38716,7 @@ Reply:
|
| @table @samp
|
| @item OK
|
| success
|
| -@item
|
| +@item @w{}
|
| not supported
|
| @item E @var{NN}
|
| for an error
|
| @@ -36061,7 +38903,7 @@ Here are the currently defined query and set packets:
|
| @table @samp
|
|
|
| @item QAgent:1
|
| -@item QAgent:0
|
| +@itemx QAgent:0
|
| Turn on or off the agent as a helper to perform some debugging operations
|
| delegated from @value{GDBN} (@pxref{Control Agent}).
|
|
|
| @@ -36136,7 +38978,7 @@ The request succeeded.
|
| @item E @var{nn}
|
| An error occurred. @var{nn} are hex digits.
|
|
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that @samp{QDisableRandomization} is not supported
|
| by the stub.
|
| @end table
|
| @@ -36207,7 +39049,7 @@ local storage requested.
|
| @item E @var{nn}
|
| An error occurred. @var{nn} are hex digits.
|
|
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
|
| @end table
|
|
|
| @@ -36228,7 +39070,7 @@ thread information block.
|
| An error occured. This means that either the thread was not found, or the
|
| address could not be retrieved.
|
|
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub.
|
| @end table
|
|
|
| @@ -36296,7 +39138,7 @@ Don't use this packet; use the @samp{qThreadExtraInfo} query instead
|
| Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
|
|
|
| @item QNonStop:1
|
| -@item QNonStop:0
|
| +@itemx QNonStop:0
|
| @cindex non-stop mode, remote request
|
| @cindex @samp{QNonStop} packet
|
| @anchor{QNonStop}
|
| @@ -36311,7 +39153,7 @@ The request succeeded.
|
| @item E @var{nn}
|
| An error occurred. @var{nn} are hex digits.
|
|
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that @samp{QNonStop} is not supported by
|
| the stub.
|
| @end table
|
| @@ -36343,7 +39185,7 @@ The request succeeded.
|
| @item E @var{nn}
|
| An error occurred. @var{nn} are hex digits.
|
|
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that @samp{QPassSignals} is not supported by
|
| the stub.
|
| @end table
|
| @@ -36385,7 +39227,7 @@ The request succeeded.
|
| @item E @var{nn}
|
| An error occurred. @var{nn} are hex digits.
|
|
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that @samp{QProgramSignals} is not supported
|
| by the stub.
|
| @end table
|
| @@ -36413,7 +39255,7 @@ A command response with no output.
|
| A command response with the hex encoded output string @var{OUTPUT}.
|
| @item E @var{NN}
|
| Indicate a badly formed request.
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that @samp{qRcmd} is not recognized.
|
| @end table
|
|
|
| @@ -36424,7 +39266,10 @@ packets.)
|
|
|
| @item qSearch:memory:@var{address};@var{length};@var{search-pattern}
|
| @cindex searching memory, in remote debugging
|
| +@ifnotinfo
|
| @cindex @samp{qSearch:memory} packet
|
| +@end ifnotinfo
|
| +@cindex @samp{qSearch memory} packet
|
| @anchor{qSearch memory}
|
| Search @var{length} bytes at @var{address} for @var{search-pattern}.
|
| @var{address} and @var{length} are encoded in hex.
|
| @@ -36438,7 +39283,7 @@ The pattern was not found.
|
| The pattern was found at @var{address}.
|
| @item E @var{NN}
|
| A badly formed request or an error was encountered while searching memory.
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that @samp{qSearch:memory} is not recognized.
|
| @end table
|
|
|
| @@ -36455,7 +39300,7 @@ The stub has switched to no-acknowledgment mode.
|
| @value{GDBN} acknowledges this reponse,
|
| but neither the stub nor @value{GDBN} shall send or expect further
|
| @samp{+}/@samp{-} acknowledgments in the current connection.
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that the stub does not support no-acknowledgment mode.
|
| @end table
|
|
|
| @@ -36485,7 +39330,7 @@ Reply:
|
| The stub supports or does not support each returned @var{stubfeature},
|
| depending on the form of each @var{stubfeature} (see below for the
|
| possible forms).
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that @samp{qSupported} is not recognized,
|
| or that no features needed to be reported to @value{GDBN}.
|
| @end table
|
| @@ -36591,6 +39436,11 @@ These are the currently defined stub features and their properties:
|
| @tab @samp{-}
|
| @tab Yes
|
|
|
| +@item @samp{qXfer:btrace:read}
|
| +@tab No
|
| +@tab @samp{-}
|
| +@tab Yes
|
| +
|
| @item @samp{qXfer:features:read}
|
| @tab No
|
| @tab @samp{-}
|
| @@ -36601,6 +39451,16 @@ These are the currently defined stub features and their properties:
|
| @tab @samp{-}
|
| @tab Yes
|
|
|
| +@item @samp{qXfer:libraries-svr4:read}
|
| +@tab No
|
| +@tab @samp{-}
|
| +@tab Yes
|
| +
|
| +@item @samp{augmented-libraries-svr4-read}
|
| +@tab No
|
| +@tab @samp{-}
|
| +@tab No
|
| +
|
| @item @samp{qXfer:memory-map:read}
|
| @tab No
|
| @tab @samp{-}
|
| @@ -36651,6 +39511,16 @@ These are the currently defined stub features and their properties:
|
| @tab @samp{-}
|
| @tab Yes
|
|
|
| +@item @samp{Qbtrace:off}
|
| +@tab Yes
|
| +@tab @samp{-}
|
| +@tab Yes
|
| +
|
| +@item @samp{Qbtrace:bts}
|
| +@tab Yes
|
| +@tab @samp{-}
|
| +@tab Yes
|
| +
|
| @item @samp{QNonStop}
|
| @tab No
|
| @tab @samp{-}
|
| @@ -36716,6 +39586,11 @@ These are the currently defined stub features and their properties:
|
| @tab @samp{-}
|
| @tab No
|
|
|
| +@item @samp{QTBuffer:size}
|
| +@tab No
|
| +@tab @samp{-}
|
| +@tab No
|
| +
|
| @item @samp{tracenz}
|
| @tab No
|
| @tab @samp{-}
|
| @@ -36746,6 +39621,10 @@ byte in its buffer for the NUL. If this stub feature is not supported,
|
| The remote stub understands the @samp{qXfer:auxv:read} packet
|
| (@pxref{qXfer auxiliary vector read}).
|
|
|
| +@item qXfer:btrace:read
|
| +The remote stub understands the @samp{qXfer:btrace:read}
|
| +packet (@pxref{qXfer btrace read}).
|
| +
|
| @item qXfer:features:read
|
| The remote stub understands the @samp{qXfer:features:read} packet
|
| (@pxref{qXfer target description read}).
|
| @@ -36758,6 +39637,11 @@ The remote stub understands the @samp{qXfer:libraries:read} packet
|
| The remote stub understands the @samp{qXfer:libraries-svr4:read} packet
|
| (@pxref{qXfer svr4 library list read}).
|
|
|
| +@item augmented-libraries-svr4-read
|
| +The remote stub understands the augmented form of 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}).
|
| @@ -36870,6 +39754,10 @@ 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 QTBuffer:size
|
| +The remote stub supports the @samp{QTBuffer:size} (@pxref{QTBuffer-size})
|
| +packet that allows to change the size of the trace buffer.
|
| +
|
| @item tracenz
|
| @cindex string tracing, in remote protocol
|
| The remote stub supports the @samp{tracenz} bytecode for collecting strings.
|
| @@ -36880,6 +39768,12 @@ See @ref{Bytecode Descriptions} for details about the bytecode.
|
| The remote stub supports running a breakpoint's command list itself,
|
| rather than reporting the hit to @value{GDBN}.
|
|
|
| +@item Qbtrace:off
|
| +The remote stub understands the @samp{Qbtrace:off} packet.
|
| +
|
| +@item Qbtrace:bts
|
| +The remote stub understands the @samp{Qbtrace:bts} packet.
|
| +
|
| @end table
|
|
|
| @item qSymbol::
|
| @@ -36920,8 +39814,8 @@ encoded). @value{GDBN} will continue to supply the values of symbols
|
| @end table
|
|
|
| @item qTBuffer
|
| -@item QTBuffer
|
| -@item QTDisconnected
|
| +@itemx QTBuffer
|
| +@itemx QTDisconnected
|
| @itemx QTDP
|
| @itemx QTDPsrc
|
| @itemx QTDV
|
| @@ -36958,10 +39852,10 @@ conventions above. Please don't use this packet as a model for new
|
| packets.)
|
|
|
| @item QTNotes
|
| -@item qTP
|
| -@item QTSave
|
| -@item qTsP
|
| -@item qTsV
|
| +@itemx qTP
|
| +@itemx QTSave
|
| +@itemx qTsP
|
| +@itemx qTsV
|
| @itemx QTStart
|
| @itemx QTStop
|
| @itemx QTEnable
|
| @@ -36998,6 +39892,25 @@ auxiliary vector}. Note @var{annex} must be empty.
|
| This packet is not probed by default; the remote stub must request it,
|
| by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
|
|
|
| +@item qXfer:btrace:read:@var{annex}:@var{offset},@var{length}
|
| +@anchor{qXfer btrace read}
|
| +
|
| +Return a description of the current branch trace.
|
| +@xref{Branch Trace Format}. The annex part of the generic @samp{qXfer}
|
| +packet may have one of the following values:
|
| +
|
| +@table @code
|
| +@item all
|
| +Returns all available branch trace.
|
| +
|
| +@item new
|
| +Returns all available branch trace if the branch trace changed since
|
| +the last read request.
|
| +@end table
|
| +
|
| +This packet is not probed by default; the remote stub must request it
|
| +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
|
| +
|
| @item qXfer:features:read:@var{annex}:@var{offset},@var{length}
|
| @anchor{qXfer target description read}
|
| Access the @dfn{target description}. @xref{Target Descriptions}. The
|
| @@ -37024,7 +39937,10 @@ by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
|
| @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}).
|
| +of the generic @samp{qXfer} packet must be empty unless the remote
|
| +stub indicated it supports the augmented form of this packet
|
| +by supplying an appropriate @samp{qSupported} response
|
| +(@pxref{qXfer read}, @ref{qSupported}).
|
|
|
| This packet is optional for better performance on SVR4 targets.
|
| @value{GDBN} uses memory read packets to read the SVR4 library list otherwise.
|
| @@ -37032,6 +39948,30 @@ This packet is optional for better performance on SVR4 targets.
|
| This packet is not probed by default; the remote stub must request it,
|
| by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
|
|
|
| +If the remote stub indicates it supports the augmented form of this
|
| +packet then the annex part of the generic @samp{qXfer} packet may
|
| +contain a semicolon-separated list of @samp{@var{name}=@var{value}}
|
| +arguments. The currently supported arguments are:
|
| +
|
| +@table @code
|
| +@item start=@var{address}
|
| +A hexadecimal number specifying the address of the @samp{struct
|
| +link_map} to start reading the library list from. If unset or zero
|
| +then the first @samp{struct link_map} in the library list will be
|
| +chosen as the starting point.
|
| +
|
| +@item prev=@var{address}
|
| +A hexadecimal number specifying the address of the @samp{struct
|
| +link_map} immediately preceding the @samp{struct link_map}
|
| +specified by the @samp{start} argument. If unset or zero then
|
| +the remote stub will expect that no @samp{struct link_map}
|
| +exists prior to the starting point.
|
| +
|
| +@end table
|
| +
|
| +Arguments that are not understood by the remote stub will be silently
|
| +ignored.
|
| +
|
| @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
|
| @@ -37144,7 +40084,7 @@ The request was malformed, or @var{annex} was invalid.
|
| The offset was invalid, or there was an error encountered reading the data.
|
| @var{nn} is a hex-encoded @code{errno} value.
|
|
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates the @var{object} string was not recognized by
|
| the stub, or that the object does not support reading.
|
| @end table
|
| @@ -37199,7 +40139,7 @@ The request was malformed, or @var{annex} was invalid.
|
| The offset was invalid, or there was an error encountered writing the data.
|
| @var{nn} is a hex-encoded @code{errno} value.
|
|
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates the @var{object} string was not
|
| recognized by the stub, or that the object does not support writing.
|
| @end table
|
| @@ -37234,6 +40174,28 @@ The remote server created a new process.
|
| A badly formed request or an error was encountered.
|
| @end table
|
|
|
| +@item Qbtrace:bts
|
| +Enable branch tracing for the current thread using bts tracing.
|
| +
|
| +Reply:
|
| +@table @samp
|
| +@item OK
|
| +Branch tracing has been enabled.
|
| +@item E.errtext
|
| +A badly formed request or an error was encountered.
|
| +@end table
|
| +
|
| +@item Qbtrace:off
|
| +Disable branch tracing for the current thread.
|
| +
|
| +Reply:
|
| +@table @samp
|
| +@item OK
|
| +Branch tracing has been disabled.
|
| +@item E.errtext
|
| +A badly formed request or an error was encountered.
|
| +@end table
|
| +
|
| @end table
|
|
|
| @node Architecture-Specific Protocol Details
|
| @@ -37360,7 +40322,7 @@ Replies:
|
| The packet was understood and carried out.
|
| @item qRelocInsn
|
| @xref{Tracepoint Packets,,Relocate instruction reply packet}.
|
| -@item
|
| +@item @w{}
|
| The packet was not recognized.
|
| @end table
|
|
|
| @@ -37426,7 +40388,7 @@ Replies:
|
| The packet was understood and carried out.
|
| @item qRelocInsn
|
| @xref{Tracepoint Packets,,Relocate instruction reply packet}.
|
| -@item
|
| +@item @w{}
|
| The packet was not recognized.
|
| @end table
|
|
|
| @@ -37538,7 +40500,7 @@ 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
|
| +@item @w{}
|
| An empty reply indicates that the request is not supported by the stub.
|
| @end table
|
|
|
| @@ -37750,7 +40712,7 @@ a comma-separated list of markers
|
| (lower case letter @samp{L}) denotes end of list.
|
| @item E @var{nn}
|
| An error occurred. @var{nn} are hex digits.
|
| -@item
|
| +@item @w{}
|
| An empty reply indicates that the request is not supported by the
|
| stub.
|
| @end table
|
| @@ -37793,6 +40755,13 @@ 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.
|
|
|
| +@item QTBuffer:size:@var{size}
|
| +@anchor{QTBuffer-size}
|
| +@cindex @samp{QTBuffer size} packet
|
| +This packet directs the target to make the trace buffer be of size
|
| +@var{size} if possible. A value of @code{-1} tells the target to
|
| +use whatever size it prefers.
|
| +
|
| @item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{}
|
| @cindex @samp{QTNotes} packet
|
| This packet adds optional textual notes to the trace run. Allowable
|
| @@ -37887,7 +40856,7 @@ normal way (@pxref{Binary Data}). See the individual packet
|
| documentation for the interpretation of @var{result} and
|
| @var{attachment}.
|
|
|
| -@item
|
| +@item @w{}
|
| An empty response indicates that this operation is not recognized.
|
|
|
| @end table
|
| @@ -38029,17 +40998,91 @@ transmit notifications without fear of confusing older clients. There
|
| are no notifications defined for @value{GDBN} to send at the moment, but we
|
| assume that most older stubs would ignore them, as well.)
|
|
|
| -The following notification packets from the stub to @value{GDBN} are
|
| -defined:
|
| -
|
| +Each notification is comprised of three parts:
|
| @table @samp
|
| -@item Stop: @var{reply}
|
| -Report an asynchronous stop event in non-stop mode.
|
| -The @var{reply} has the form of a stop reply, as
|
| +@item @var{name}:@var{event}
|
| +The notification packet is sent by the side that initiates the
|
| +exchange (currently, only the stub does that), with @var{event}
|
| +carrying the specific information about the notification.
|
| +@var{name} is the name of the notification.
|
| +@item @var{ack}
|
| +The acknowledge sent by the other side, usually @value{GDBN}, to
|
| +acknowledge the exchange and request the event.
|
| +@end table
|
| +
|
| +The purpose of an asynchronous notification mechanism is to report to
|
| +@value{GDBN} that something interesting happened in the remote stub.
|
| +
|
| +The remote stub may send notification @var{name}:@var{event}
|
| +at any time, but @value{GDBN} acknowledges the notification when
|
| +appropriate. The notification event is pending before @value{GDBN}
|
| +acknowledges. Only one notification at a time may be pending; if
|
| +additional events occur before @value{GDBN} has acknowledged the
|
| +previous notification, they must be queued by the stub for later
|
| +synchronous transmission in response to @var{ack} packets from
|
| +@value{GDBN}. Because the notification mechanism is unreliable,
|
| +the stub is permitted to resend a notification if it believes
|
| +@value{GDBN} may not have received it.
|
| +
|
| +Specifically, notifications may appear when @value{GDBN} is not
|
| +otherwise reading input from the stub, or when @value{GDBN} is
|
| +expecting to read a normal synchronous response or a
|
| +@samp{+}/@samp{-} acknowledgment to a packet it has sent.
|
| +Notification packets are distinct from any other communication from
|
| +the stub so there is no ambiguity.
|
| +
|
| +After receiving a notification, @value{GDBN} shall acknowledge it by
|
| +sending a @var{ack} packet as a regular, synchronous request to the
|
| +stub. Such acknowledgment is not required to happen immediately, as
|
| +@value{GDBN} is permitted to send other, unrelated packets to the
|
| +stub first, which the stub should process normally.
|
| +
|
| +Upon receiving a @var{ack} packet, if the stub has other queued
|
| +events to report to @value{GDBN}, it shall respond by sending a
|
| +normal @var{event}. @value{GDBN} shall then send another @var{ack}
|
| +packet to solicit further responses; again, it is permitted to send
|
| +other, unrelated packets as well which the stub should process
|
| +normally.
|
| +
|
| +If the stub receives a @var{ack} packet and there are no additional
|
| +@var{event} to report, the stub shall return an @samp{OK} response.
|
| +At this point, @value{GDBN} has finished processing a notification
|
| +and the stub has completed sending any queued events. @value{GDBN}
|
| +won't accept any new notifications until the final @samp{OK} is
|
| +received . If further notification events occur, the stub shall send
|
| +a new notification, @value{GDBN} shall accept the notification, and
|
| +the process shall be repeated.
|
| +
|
| +The process of asynchronous notification can be illustrated by the
|
| +following example:
|
| +@smallexample
|
| +<- @code{%%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;}
|
| +@code{...}
|
| +-> @code{vStopped}
|
| +<- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;}
|
| +-> @code{vStopped}
|
| +<- @code{T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;}
|
| +-> @code{vStopped}
|
| +<- @code{OK}
|
| +@end smallexample
|
| +
|
| +The following notifications are defined:
|
| +@multitable @columnfractions 0.12 0.12 0.38 0.38
|
| +
|
| +@item Notification
|
| +@tab Ack
|
| +@tab Event
|
| +@tab Description
|
| +
|
| +@item Stop
|
| +@tab vStopped
|
| +@tab @var{reply}. The @var{reply} has the form of a stop reply, as
|
| described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop},
|
| for information on how these notifications are acknowledged by
|
| @value{GDBN}.
|
| -@end table
|
| +@tab Report an asynchronous stop event in non-stop mode.
|
| +
|
| +@end multitable
|
|
|
| @node Remote Non-Stop
|
| @section Remote Protocol Support for Non-Stop Mode
|
| @@ -38068,45 +41111,6 @@ affected thread is stopped; any other still-running threads continue
|
| to run. When reporting a @samp{W} or @samp{X} response, all running
|
| threads belonging to other attached processes continue to run.
|
|
|
| -Only one stop reply notification at a time may be pending; if
|
| -additional stop events occur before @value{GDBN} has acknowledged the
|
| -previous notification, they must be queued by the stub for later
|
| -synchronous transmission in response to @samp{vStopped} packets from
|
| -@value{GDBN}. Because the notification mechanism is unreliable,
|
| -the stub is permitted to resend a stop reply notification
|
| -if it believes @value{GDBN} may not have received it. @value{GDBN}
|
| -ignores additional stop reply notifications received before it has
|
| -finished processing a previous notification and the stub has completed
|
| -sending any queued stop events.
|
| -
|
| -Otherwise, @value{GDBN} must be prepared to receive a stop reply
|
| -notification at any time. Specifically, they may appear when
|
| -@value{GDBN} is not otherwise reading input from the stub, or when
|
| -@value{GDBN} is expecting to read a normal synchronous response or a
|
| -@samp{+}/@samp{-} acknowledgment to a packet it has sent.
|
| -Notification packets are distinct from any other communication from
|
| -the stub so there is no ambiguity.
|
| -
|
| -After receiving a stop reply notification, @value{GDBN} shall
|
| -acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
|
| -as a regular, synchronous request to the stub. Such acknowledgment
|
| -is not required to happen immediately, as @value{GDBN} is permitted to
|
| -send other, unrelated packets to the stub first, which the stub should
|
| -process normally.
|
| -
|
| -Upon receiving a @samp{vStopped} packet, if the stub has other queued
|
| -stop events to report to @value{GDBN}, it shall respond by sending a
|
| -normal stop reply response. @value{GDBN} shall then send another
|
| -@samp{vStopped} packet to solicit further responses; again, it is
|
| -permitted to send other, unrelated packets as well which the stub
|
| -should process normally.
|
| -
|
| -If the stub receives a @samp{vStopped} packet and there are no
|
| -additional stop events to report, the stub shall return an @samp{OK}
|
| -response. At this point, if further stop events occur, the stub shall
|
| -send a new stop reply notification, @value{GDBN} shall accept the
|
| -notification, and the process shall be repeated.
|
| -
|
| In non-stop mode, the target shall respond to the @samp{?} packet as
|
| follows. First, any incomplete stop reply notification/@samp{vStopped}
|
| sequence in progress is abandoned. The target must begin a new
|
| @@ -39637,17 +42641,77 @@ A region of collected memory starting at @var{addr} and extending for
|
| <memory start="@var{addr}" length="@var{length}"/>
|
| @end smallexample
|
|
|
| +@item
|
| +A block indicating trace state variable numbered @var{number} has been
|
| +collected:
|
| +
|
| +@smallexample
|
| +<tvar id="@var{number}"/>
|
| +@end smallexample
|
| +
|
| @end itemize
|
|
|
| The formal DTD for the traceframe info format is given below:
|
|
|
| @smallexample
|
| -<!ELEMENT traceframe-info (memory)* >
|
| +<!ELEMENT traceframe-info (memory | tvar)* >
|
| <!ATTLIST traceframe-info version CDATA #FIXED "1.0">
|
|
|
| <!ELEMENT memory EMPTY>
|
| <!ATTLIST memory start CDATA #REQUIRED
|
| length CDATA #REQUIRED>
|
| +<!ELEMENT tvar>
|
| +<!ATTLIST tvar id CDATA #REQUIRED>
|
| +@end smallexample
|
| +
|
| +@node Branch Trace Format
|
| +@section Branch Trace Format
|
| +@cindex branch trace format
|
| +
|
| +In order to display the branch trace of an inferior thread,
|
| +@value{GDBN} needs to obtain the list of branches. This list is
|
| +represented as list of sequential code blocks that are connected via
|
| +branches. The code in each block has been executed sequentially.
|
| +
|
| +This list is obtained using the @samp{qXfer:btrace:read}
|
| +(@pxref{qXfer btrace read}) packet and is an XML document.
|
| +
|
| +@value{GDBN} must be linked with the Expat library to support XML
|
| +traceframe info discovery. @xref{Expat}.
|
| +
|
| +The top-level structure of the document is shown below:
|
| +
|
| +@smallexample
|
| +<?xml version="1.0"?>
|
| +<!DOCTYPE btrace
|
| + PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
|
| + "http://sourceware.org/gdb/gdb-btrace.dtd">
|
| +<btrace>
|
| + block...
|
| +</btrace>
|
| +@end smallexample
|
| +
|
| +@itemize
|
| +
|
| +@item
|
| +A block of sequentially executed instructions starting at @var{begin}
|
| +and ending at @var{end}:
|
| +
|
| +@smallexample
|
| +<block begin="@var{begin}" end="@var{end}"/>
|
| +@end smallexample
|
| +
|
| +@end itemize
|
| +
|
| +The formal DTD for the branch trace format is given below:
|
| +
|
| +@smallexample
|
| +<!ELEMENT btrace (block)* >
|
| +<!ATTLIST btrace version CDATA #FIXED "1.0">
|
| +
|
| +<!ELEMENT block EMPTY>
|
| +<!ATTLIST block begin CDATA #REQUIRED
|
| + end CDATA #REQUIRED>
|
| @end smallexample
|
|
|
| @include agentexpr.texi
|
| @@ -40107,15 +43171,30 @@ of recognizing standard features, but @value{GDBN} will only display
|
| registers using the capitalization used in the description.
|
|
|
| @menu
|
| +* AArch64 Features::
|
| * ARM Features::
|
| * i386 Features::
|
| * MIPS Features::
|
| * M68K Features::
|
| +* Nios II Features::
|
| * PowerPC Features::
|
| +* S/390 and System z Features::
|
| * TIC6x Features::
|
| @end menu
|
|
|
|
|
| +@node AArch64 Features
|
| +@subsection AArch64 Features
|
| +@cindex target descriptions, AArch64 features
|
| +
|
| +The @samp{org.gnu.gdb.aarch64.core} feature is required for AArch64
|
| +targets. It should contain registers @samp{x0} through @samp{x30},
|
| +@samp{sp}, @samp{pc}, and @samp{cpsr}.
|
| +
|
| +The @samp{org.gnu.gdb.aarch64.fpu} feature is optional. If present,
|
| +it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr},
|
| +and @samp{fpcr}.
|
| +
|
| @node ARM Features
|
| @subsection ARM Features
|
| @cindex target descriptions, ARM features
|
| @@ -40198,6 +43277,16 @@ describe the upper 128 bits of @sc{ymm} registers:
|
| @samp{ymm0h} through @samp{ymm15h} for amd64
|
| @end itemize
|
|
|
| +The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel(R)
|
| +Memory Protection Extension (MPX). It should describe the following registers:
|
| +
|
| +@itemize @minus
|
| +@item
|
| +@samp{bnd0raw} through @samp{bnd3raw} for i386 and amd64.
|
| +@item
|
| +@samp{bndcfgu} and @samp{bndstatus} for i386 and amd64.
|
| +@end itemize
|
| +
|
| The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
|
| describe a single register, @samp{orig_eax}.
|
|
|
| @@ -40248,6 +43337,16 @@ This feature is optional. If present, it should contain registers
|
| @samp{fpiaddr}.
|
| @end table
|
|
|
| +@node Nios II Features
|
| +@subsection Nios II Features
|
| +@cindex target descriptions, Nios II features
|
| +
|
| +The @samp{org.gnu.gdb.nios2.cpu} feature is required for Nios II
|
| +targets. It should contain the 32 core registers (@samp{zero},
|
| +@samp{at}, @samp{r2} through @samp{r23}, @samp{et} through @samp{ra}),
|
| +@samp{pc}, and the 16 control registers (@samp{status} through
|
| +@samp{mpuacc}).
|
| +
|
| @node PowerPC Features
|
| @subsection PowerPC Features
|
| @cindex target descriptions, PowerPC features
|
| @@ -40279,6 +43378,39 @@ contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and
|
| these to present registers @samp{ev0} through @samp{ev31} to the
|
| user.
|
|
|
| +@node S/390 and System z Features
|
| +@subsection S/390 and System z Features
|
| +@cindex target descriptions, S/390 features
|
| +@cindex target descriptions, System z features
|
| +
|
| +The @samp{org.gnu.gdb.s390.core} feature is required for S/390 and
|
| +System z targets. It should contain the PSW and the 16 general
|
| +registers. In particular, System z targets should provide the 64-bit
|
| +registers @samp{pswm}, @samp{pswa}, and @samp{r0} through @samp{r15}.
|
| +S/390 targets should provide the 32-bit versions of these registers.
|
| +A System z target that runs in 31-bit addressing mode should provide
|
| +32-bit versions of @samp{pswm} and @samp{pswa}, as well as the general
|
| +register's upper halves @samp{r0h} through @samp{r15h}, and their
|
| +lower halves @samp{r0l} through @samp{r15l}.
|
| +
|
| +The @samp{org.gnu.gdb.s390.fpr} feature is required. It should
|
| +contain the 64-bit registers @samp{f0} through @samp{f15}, and
|
| +@samp{fpc}.
|
| +
|
| +The @samp{org.gnu.gdb.s390.acr} feature is required. It should
|
| +contain the 32-bit registers @samp{acr0} through @samp{acr15}.
|
| +
|
| +The @samp{org.gnu.gdb.s390.linux} feature is optional. It should
|
| +contain the register @samp{orig_r2}, which is 64-bit wide on System z
|
| +targets and 32-bit otherwise. In addition, the feature may contain
|
| +the @samp{last_break} register, whose width depends on the addressing
|
| +mode, as well as the @samp{system_call} register, which is always
|
| +32-bit wide.
|
| +
|
| +The @samp{org.gnu.gdb.s390.tdb} feature is optional. It should
|
| +contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct},
|
| +@samp{atia}, and @samp{tr0} through @samp{tr15}.
|
| +
|
| @node TIC6x Features
|
| @subsection TMS320C6x Features
|
| @cindex target descriptions, TIC6x features
|
| @@ -40425,12 +43557,18 @@ unless otherwise noted:
|
|
|
| @enumerate
|
| @item
|
| -The version number, currently 7. Versions 1, 2 and 3 are obsolete.
|
| +The version number, currently 8. 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. Version 7 adds attributes to the CU indices in the
|
| -symbol table. @value{GDBN} will only read version 4, 5, or 6 indices
|
| +symbol table. Version 8 specifies that symbols from DWARF type units
|
| +(@samp{DW_TAG_type_unit}) refer to the type unit's symbol table and not the
|
| +compilation unit (@samp{DW_TAG_comp_unit}) using the type.
|
| +
|
| +@value{GDBN} will only read version 4, 5, or 6 indices
|
| by specifying @code{set use-deprecated-index-sections on}.
|
| +GDB has a workaround for potentially broken version 7 indices so it is
|
| +currently not flagged as deprecated.
|
|
|
| @item
|
| The offset, from the start of the file, of the CU list.
|
| @@ -40626,6 +43764,679 @@ switch (die->tag)
|
| @}
|
| @end smallexample
|
|
|
| +@node Man Pages
|
| +@appendix Manual pages
|
| +@cindex Man pages
|
| +
|
| +@menu
|
| +* gdb man:: The GNU Debugger man page
|
| +* gdbserver man:: Remote Server for the GNU Debugger man page
|
| +* gcore man:: Generate a core file of a running program
|
| +* gdbinit man:: gdbinit scripts
|
| +@end menu
|
| +
|
| +@node gdb man
|
| +@heading gdb man
|
| +
|
| +@c man title gdb The GNU Debugger
|
| +
|
| +@c man begin SYNOPSIS gdb
|
| +gdb [@option{-help}] [@option{-nh}] [@option{-nx}] [@option{-q}]
|
| +[@option{-batch}] [@option{-cd=}@var{dir}] [@option{-f}]
|
| +[@option{-b}@w{ }@var{bps}]
|
| + [@option{-tty=}@var{dev}] [@option{-s} @var{symfile}]
|
| +[@option{-e}@w{ }@var{prog}] [@option{-se}@w{ }@var{prog}]
|
| +[@option{-c}@w{ }@var{core}] [@option{-p}@w{ }@var{procID}]
|
| + [@option{-x}@w{ }@var{cmds}] [@option{-d}@w{ }@var{dir}]
|
| +[@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}]
|
| +@c man end
|
| +
|
| +@c man begin DESCRIPTION gdb
|
| +The purpose of a debugger such as @value{GDBN} is to allow you to see what is
|
| +going on ``inside'' another program while it executes -- or what another
|
| +program was doing at the moment it crashed.
|
| +
|
| +@value{GDBN} can do four main kinds of things (plus other things in support of
|
| +these) to help you catch bugs in the act:
|
| +
|
| +@itemize @bullet
|
| +@item
|
| +Start your program, specifying anything that might affect its behavior.
|
| +
|
| +@item
|
| +Make your program stop on specified conditions.
|
| +
|
| +@item
|
| +Examine what has happened, when your program has stopped.
|
| +
|
| +@item
|
| +Change things in your program, so you can experiment with correcting the
|
| +effects of one bug and go on to learn about another.
|
| +@end itemize
|
| +
|
| +You can use @value{GDBN} to debug programs written in C, C@t{++}, Fortran and
|
| +Modula-2.
|
| +
|
| +@value{GDBN} is invoked with the shell command @code{gdb}. Once started, it reads
|
| +commands from the terminal until you tell it to exit with the @value{GDBN}
|
| +command @code{quit}. You can get online help from @value{GDBN} itself
|
| +by using the command @code{help}.
|
| +
|
| +You can run @code{gdb} with no arguments or options; but the most
|
| +usual way to start @value{GDBN} is with one argument or two, specifying an
|
| +executable program as the argument:
|
| +
|
| +@smallexample
|
| +gdb program
|
| +@end smallexample
|
| +
|
| +You can also start with both an executable program and a core file specified:
|
| +
|
| +@smallexample
|
| +gdb program core
|
| +@end smallexample
|
| +
|
| +You can, instead, specify a process ID as a second argument, if you want
|
| +to debug a running process:
|
| +
|
| +@smallexample
|
| +gdb program 1234
|
| +gdb -p 1234
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +would attach @value{GDBN} to process @code{1234} (unless you also have a file
|
| +named @file{1234}; @value{GDBN} does check for a core file first).
|
| +With option @option{-p} you can omit the @var{program} filename.
|
| +
|
| +Here are some of the most frequently needed @value{GDBN} commands:
|
| +
|
| +@c pod2man highlights the right hand side of the @item lines.
|
| +@table @env
|
| +@item break [@var{file}:]@var{functiop}
|
| +Set a breakpoint at @var{function} (in @var{file}).
|
| +
|
| +@item run [@var{arglist}]
|
| +Start your program (with @var{arglist}, if specified).
|
| +
|
| +@item bt
|
| +Backtrace: display the program stack.
|
| +
|
| +@item print @var{expr}
|
| +Display the value of an expression.
|
| +
|
| +@item c
|
| +Continue running your program (after stopping, e.g. at a breakpoint).
|
| +
|
| +@item next
|
| +Execute next program line (after stopping); step @emph{over} any
|
| +function calls in the line.
|
| +
|
| +@item edit [@var{file}:]@var{function}
|
| +look at the program line where it is presently stopped.
|
| +
|
| +@item list [@var{file}:]@var{function}
|
| +type the text of the program in the vicinity of where it is presently stopped.
|
| +
|
| +@item step
|
| +Execute next program line (after stopping); step @emph{into} any
|
| +function calls in the line.
|
| +
|
| +@item help [@var{name}]
|
| +Show information about @value{GDBN} command @var{name}, or general information
|
| +about using @value{GDBN}.
|
| +
|
| +@item quit
|
| +Exit from @value{GDBN}.
|
| +@end table
|
| +
|
| +@ifset man
|
| +For full details on @value{GDBN},
|
| +see @cite{Using GDB: A Guide to the GNU Source-Level Debugger},
|
| +by Richard M. Stallman and Roland H. Pesch. The same text is available online
|
| +as the @code{gdb} entry in the @code{info} program.
|
| +@end ifset
|
| +@c man end
|
| +
|
| +@c man begin OPTIONS gdb
|
| +Any arguments other than options specify an executable
|
| +file and core file (or process ID); that is, the first argument
|
| +encountered with no
|
| +associated option flag is equivalent to a @option{-se} option, and the second,
|
| +if any, is equivalent to a @option{-c} option if it's the name of a file.
|
| +Many options have
|
| +both long and short forms; both are shown here. The long forms are also
|
| +recognized if you truncate them, so long as enough of the option is
|
| +present to be unambiguous. (If you prefer, you can flag option
|
| +arguments with @option{+} rather than @option{-}, though we illustrate the
|
| +more usual convention.)
|
| +
|
| +All the options and command line arguments you give are processed
|
| +in sequential order. The order makes a difference when the @option{-x}
|
| +option is used.
|
| +
|
| +@table @env
|
| +@item -help
|
| +@itemx -h
|
| +List all options, with brief explanations.
|
| +
|
| +@item -symbols=@var{file}
|
| +@itemx -s @var{file}
|
| +Read symbol table from file @var{file}.
|
| +
|
| +@item -write
|
| +Enable writing into executable and core files.
|
| +
|
| +@item -exec=@var{file}
|
| +@itemx -e @var{file}
|
| +Use file @var{file} as the executable file to execute when
|
| +appropriate, and for examining pure data in conjunction with a core
|
| +dump.
|
| +
|
| +@item -se=@var{file}
|
| +Read symbol table from file @var{file} and use it as the executable
|
| +file.
|
| +
|
| +@item -core=@var{file}
|
| +@itemx -c @var{file}
|
| +Use file @var{file} as a core dump to examine.
|
| +
|
| +@item -command=@var{file}
|
| +@itemx -x @var{file}
|
| +Execute @value{GDBN} commands from file @var{file}.
|
| +
|
| +@item -ex @var{command}
|
| +Execute given @value{GDBN} @var{command}.
|
| +
|
| +@item -directory=@var{directory}
|
| +@itemx -d @var{directory}
|
| +Add @var{directory} to the path to search for source files.
|
| +
|
| +@item -nh
|
| +Do not execute commands from @file{~/.gdbinit}.
|
| +
|
| +@item -nx
|
| +@itemx -n
|
| +Do not execute commands from any @file{.gdbinit} initialization files.
|
| +
|
| +@item -quiet
|
| +@itemx -q
|
| +``Quiet''. Do not print the introductory and copyright messages. These
|
| +messages are also suppressed in batch mode.
|
| +
|
| +@item -batch
|
| +Run in batch mode. Exit with status @code{0} after processing all the command
|
| +files specified with @option{-x} (and @file{.gdbinit}, if not inhibited).
|
| +Exit with nonzero status if an error occurs in executing the @value{GDBN}
|
| +commands in the command files.
|
| +
|
| +Batch mode may be useful for running @value{GDBN} as a filter, for example to
|
| +download and run a program on another computer; in order to make this
|
| +more useful, the message
|
| +
|
| +@smallexample
|
| +Program exited normally.
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +(which is ordinarily issued whenever a program running under @value{GDBN} control
|
| +terminates) is not issued when running in batch mode.
|
| +
|
| +@item -cd=@var{directory}
|
| +Run @value{GDBN} using @var{directory} as its working directory,
|
| +instead of the current directory.
|
| +
|
| +@item -fullname
|
| +@itemx -f
|
| +Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells
|
| +@value{GDBN} to output the full file name and line number in a standard,
|
| +recognizable fashion each time a stack frame is displayed (which
|
| +includes each time the program stops). This recognizable format looks
|
| +like two @samp{\032} characters, followed by the file name, line number
|
| +and character position separated by colons, and a newline. The
|
| +Emacs-to-@value{GDBN} interface program uses the two @samp{\032}
|
| +characters as a signal to display the source code for the frame.
|
| +
|
| +@item -b @var{bps}
|
| +Set the line speed (baud rate or bits per second) of any serial
|
| +interface used by @value{GDBN} for remote debugging.
|
| +
|
| +@item -tty=@var{device}
|
| +Run using @var{device} for your program's standard input and output.
|
| +@end table
|
| +@c man end
|
| +
|
| +@c man begin SEEALSO gdb
|
| +@ifset man
|
| +The full documentation for @value{GDBN} is maintained as a Texinfo manual.
|
| +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
|
| +documentation are properly installed at your site, the command
|
| +
|
| +@smallexample
|
| +info gdb
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +should give you access to the complete manual.
|
| +
|
| +@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
|
| +Richard M. Stallman and Roland H. Pesch, July 1991.
|
| +@end ifset
|
| +@c man end
|
| +
|
| +@node gdbserver man
|
| +@heading gdbserver man
|
| +
|
| +@c man title gdbserver Remote Server for the GNU Debugger
|
| +@format
|
| +@c man begin SYNOPSIS gdbserver
|
| +gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
|
| +
|
| +gdbserver --attach @var{comm} @var{pid}
|
| +
|
| +gdbserver --multi @var{comm}
|
| +@c man end
|
| +@end format
|
| +
|
| +@c man begin DESCRIPTION gdbserver
|
| +@command{gdbserver} is a program that allows you to run @value{GDBN} on a different machine
|
| +than the one which is running the program being debugged.
|
| +
|
| +@ifclear man
|
| +@subheading Usage (server (target) side)
|
| +@end ifclear
|
| +@ifset man
|
| +Usage (server (target) side):
|
| +@end ifset
|
| +
|
| +First, you need to have a copy of the program you want to debug put onto
|
| +the target system. The program can be stripped to save space if needed, as
|
| +@command{gdbserver} doesn't care about symbols. All symbol handling is taken care of by
|
| +the @value{GDBN} running on the host system.
|
| +
|
| +To use the server, you log on to the target system, and run the @command{gdbserver}
|
| +program. You must tell it (a) how to communicate with @value{GDBN}, (b) the name of
|
| +your program, and (c) its arguments. The general syntax is:
|
| +
|
| +@smallexample
|
| +target> gdbserver @var{comm} @var{program} [@var{args} ...]
|
| +@end smallexample
|
| +
|
| +For example, using a serial port, you might say:
|
| +
|
| +@smallexample
|
| +@ifset man
|
| +@c @file would wrap it as F</dev/com1>.
|
| +target> gdbserver /dev/com1 emacs foo.txt
|
| +@end ifset
|
| +@ifclear man
|
| +target> gdbserver @file{/dev/com1} emacs foo.txt
|
| +@end ifclear
|
| +@end smallexample
|
| +
|
| +This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and
|
| +to communicate with @value{GDBN} via @file{/dev/com1}. @command{gdbserver} now
|
| +waits patiently for the host @value{GDBN} to communicate with it.
|
| +
|
| +To use a TCP connection, you could say:
|
| +
|
| +@smallexample
|
| +target> gdbserver host:2345 emacs foo.txt
|
| +@end smallexample
|
| +
|
| +This says pretty much the same thing as the last example, except that we are
|
| +going to communicate with the @code{host} @value{GDBN} via TCP. The @code{host:2345} argument means
|
| +that we are expecting to see a TCP connection from @code{host} to local TCP port
|
| +2345. (Currently, the @code{host} part is ignored.) You can choose any number you
|
| +want for the port number as long as it does not conflict with any existing TCP
|
| +ports on the target system. This same port number must be used in the host
|
| +@value{GDBN}s @code{target remote} command, which will be described shortly. Note that if
|
| +you chose a port number that conflicts with another service, @command{gdbserver} will
|
| +print an error message and exit.
|
| +
|
| +@command{gdbserver} can also attach to running programs.
|
| +This is accomplished via the @option{--attach} argument. The syntax is:
|
| +
|
| +@smallexample
|
| +target> gdbserver --attach @var{comm} @var{pid}
|
| +@end smallexample
|
| +
|
| +@var{pid} is the process ID of a currently running process. It isn't
|
| +necessary to point @command{gdbserver} at a binary for the running process.
|
| +
|
| +To start @code{gdbserver} without supplying an initial command to run
|
| +or process ID to attach, use the @option{--multi} command line option.
|
| +In such case you should connect using @kbd{target extended-remote} to start
|
| +the program you want to debug.
|
| +
|
| +@smallexample
|
| +target> gdbserver --multi @var{comm}
|
| +@end smallexample
|
| +
|
| +@ifclear man
|
| +@subheading Usage (host side)
|
| +@end ifclear
|
| +@ifset man
|
| +Usage (host side):
|
| +@end ifset
|
| +
|
| +You need an unstripped copy of the target program on your host system, since
|
| +@value{GDBN} needs to examine it's symbol tables and such. Start up @value{GDBN} as you normally
|
| +would, with the target program as the first argument. (You may need to use the
|
| +@option{--baud} option if the serial line is running at anything except 9600 baud.)
|
| +That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only
|
| +new command you need to know about is @code{target remote}
|
| +(or @code{target extended-remote}). Its argument is either
|
| +a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT}
|
| +descriptor. For example:
|
| +
|
| +@smallexample
|
| +@ifset man
|
| +@c @file would wrap it as F</dev/ttyb>.
|
| +(gdb) target remote /dev/ttyb
|
| +@end ifset
|
| +@ifclear man
|
| +(gdb) target remote @file{/dev/ttyb}
|
| +@end ifclear
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +communicates with the server via serial line @file{/dev/ttyb}, and:
|
| +
|
| +@smallexample
|
| +(gdb) target remote the-target:2345
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +communicates via a TCP connection to port 2345 on host `the-target', where
|
| +you previously started up @command{gdbserver} with the same port number. Note that for
|
| +TCP connections, you must start up @command{gdbserver} prior to using the `target remote'
|
| +command, otherwise you may get an error that looks something like
|
| +`Connection refused'.
|
| +
|
| +@command{gdbserver} can also debug multiple inferiors at once,
|
| +described in
|
| +@ifset man
|
| +the @value{GDBN} manual in node @code{Inferiors and Programs}
|
| +-- shell command @code{info -f gdb -n 'Inferiors and Programs'}.
|
| +@end ifset
|
| +@ifclear man
|
| +@ref{Inferiors and Programs}.
|
| +@end ifclear
|
| +In such case use the @code{extended-remote} @value{GDBN} command variant:
|
| +
|
| +@smallexample
|
| +(gdb) target extended-remote the-target:2345
|
| +@end smallexample
|
| +
|
| +The @command{gdbserver} option @option{--multi} may or may not be used in such
|
| +case.
|
| +@c man end
|
| +
|
| +@c man begin OPTIONS gdbserver
|
| +There are three different modes for invoking @command{gdbserver}:
|
| +
|
| +@itemize @bullet
|
| +
|
| +@item
|
| +Debug a specific program specified by its program name:
|
| +
|
| +@smallexample
|
| +gdbserver @var{comm} @var{prog} [@var{args}@dots{}]
|
| +@end smallexample
|
| +
|
| +The @var{comm} parameter specifies how should the server communicate
|
| +with @value{GDBN}; it is either a device name (to use a serial line),
|
| +a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use
|
| +stdin/stdout of @code{gdbserver}. Specify the name of the program to
|
| +debug in @var{prog}. Any remaining arguments will be passed to the
|
| +program verbatim. When the program exits, @value{GDBN} will close the
|
| +connection, and @code{gdbserver} will exit.
|
| +
|
| +@item
|
| +Debug a specific program by specifying the process ID of a running
|
| +program:
|
| +
|
| +@smallexample
|
| +gdbserver --attach @var{comm} @var{pid}
|
| +@end smallexample
|
| +
|
| +The @var{comm} parameter is as described above. Supply the process ID
|
| +of a running program in @var{pid}; @value{GDBN} will do everything
|
| +else. Like with the previous mode, when the process @var{pid} exits,
|
| +@value{GDBN} will close the connection, and @code{gdbserver} will exit.
|
| +
|
| +@item
|
| +Multi-process mode -- debug more than one program/process:
|
| +
|
| +@smallexample
|
| +gdbserver --multi @var{comm}
|
| +@end smallexample
|
| +
|
| +In this mode, @value{GDBN} can instruct @command{gdbserver} which
|
| +command(s) to run. Unlike the other 2 modes, @value{GDBN} will not
|
| +close the connection when a process being debugged exits, so you can
|
| +debug several processes in the same session.
|
| +@end itemize
|
| +
|
| +In each of the modes you may specify these options:
|
| +
|
| +@table @env
|
| +
|
| +@item --help
|
| +List all options, with brief explanations.
|
| +
|
| +@item --version
|
| +This option causes @command{gdbserver} to print its version number and exit.
|
| +
|
| +@item --attach
|
| +@command{gdbserver} will attach to a running program. The syntax is:
|
| +
|
| +@smallexample
|
| +target> gdbserver --attach @var{comm} @var{pid}
|
| +@end smallexample
|
| +
|
| +@var{pid} is the process ID of a currently running process. It isn't
|
| +necessary to point @command{gdbserver} at a binary for the running process.
|
| +
|
| +@item --multi
|
| +To start @code{gdbserver} without supplying an initial command to run
|
| +or process ID to attach, use this command line option.
|
| +Then you can connect using @kbd{target extended-remote} and start
|
| +the program you want to debug. The syntax is:
|
| +
|
| +@smallexample
|
| +target> gdbserver --multi @var{comm}
|
| +@end smallexample
|
| +
|
| +@item --debug
|
| +Instruct @code{gdbserver} to display extra status information about the debugging
|
| +process.
|
| +This option is intended for @code{gdbserver} development and for bug reports to
|
| +the developers.
|
| +
|
| +@item --remote-debug
|
| +Instruct @code{gdbserver} to display remote protocol debug output.
|
| +This option is intended for @code{gdbserver} development and for bug reports to
|
| +the developers.
|
| +
|
| +@item --wrapper
|
| +Specify a wrapper to launch programs
|
| +for debugging. The option should be followed by the name of the
|
| +wrapper, then any command-line arguments to pass to the wrapper, then
|
| +@kbd{--} indicating the end of the wrapper arguments.
|
| +
|
| +@item --once
|
| +By default, @command{gdbserver} keeps the listening TCP port open, so that
|
| +additional connections are possible. However, if you start @code{gdbserver}
|
| +with the @option{--once} option, it will stop listening for any further
|
| +connection attempts after connecting to the first @value{GDBN} session.
|
| +
|
| +@c --disable-packet is not documented for users.
|
| +
|
| +@c --disable-randomization and --no-disable-randomization are superseded by
|
| +@c QDisableRandomization.
|
| +
|
| +@end table
|
| +@c man end
|
| +
|
| +@c man begin SEEALSO gdbserver
|
| +@ifset man
|
| +The full documentation for @value{GDBN} is maintained as a Texinfo manual.
|
| +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
|
| +documentation are properly installed at your site, the command
|
| +
|
| +@smallexample
|
| +info gdb
|
| +@end smallexample
|
| +
|
| +should give you access to the complete manual.
|
| +
|
| +@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
|
| +Richard M. Stallman and Roland H. Pesch, July 1991.
|
| +@end ifset
|
| +@c man end
|
| +
|
| +@node gcore man
|
| +@heading gcore
|
| +
|
| +@c man title gcore Generate a core file of a running program
|
| +
|
| +@format
|
| +@c man begin SYNOPSIS gcore
|
| +gcore [-o @var{filename}] @var{pid}
|
| +@c man end
|
| +@end format
|
| +
|
| +@c man begin DESCRIPTION gcore
|
| +Generate a core dump of a running program with process ID @var{pid}.
|
| +Produced file is equivalent to a kernel produced core file as if the process
|
| +crashed (and if @kbd{ulimit -c} were used to set up an appropriate core dump
|
| +limit). Unlike after a crash, after @command{gcore} the program remains
|
| +running without any change.
|
| +@c man end
|
| +
|
| +@c man begin OPTIONS gcore
|
| +@table @env
|
| +@item -o @var{filename}
|
| +The optional argument
|
| +@var{filename} specifies the file name where to put the core dump.
|
| +If not specified, the file name defaults to @file{core.@var{pid}},
|
| +where @var{pid} is the running program process ID.
|
| +@end table
|
| +@c man end
|
| +
|
| +@c man begin SEEALSO gcore
|
| +@ifset man
|
| +The full documentation for @value{GDBN} is maintained as a Texinfo manual.
|
| +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
|
| +documentation are properly installed at your site, the command
|
| +
|
| +@smallexample
|
| +info gdb
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +should give you access to the complete manual.
|
| +
|
| +@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
|
| +Richard M. Stallman and Roland H. Pesch, July 1991.
|
| +@end ifset
|
| +@c man end
|
| +
|
| +@node gdbinit man
|
| +@heading gdbinit
|
| +
|
| +@c man title gdbinit GDB initialization scripts
|
| +
|
| +@format
|
| +@c man begin SYNOPSIS gdbinit
|
| +@ifset SYSTEM_GDBINIT
|
| +@value{SYSTEM_GDBINIT}
|
| +@end ifset
|
| +
|
| +~/.gdbinit
|
| +
|
| +./.gdbinit
|
| +@c man end
|
| +@end format
|
| +
|
| +@c man begin DESCRIPTION gdbinit
|
| +These files contain @value{GDBN} commands to automatically execute during
|
| +@value{GDBN} startup. The lines of contents are canned sequences of commands,
|
| +described in
|
| +@ifset man
|
| +the @value{GDBN} manual in node @code{Sequences}
|
| +-- shell command @code{info -f gdb -n Sequences}.
|
| +@end ifset
|
| +@ifclear man
|
| +@ref{Sequences}.
|
| +@end ifclear
|
| +
|
| +Please read more in
|
| +@ifset man
|
| +the @value{GDBN} manual in node @code{Startup}
|
| +-- shell command @code{info -f gdb -n Startup}.
|
| +@end ifset
|
| +@ifclear man
|
| +@ref{Startup}.
|
| +@end ifclear
|
| +
|
| +@table @env
|
| +@ifset SYSTEM_GDBINIT
|
| +@item @value{SYSTEM_GDBINIT}
|
| +@end ifset
|
| +@ifclear SYSTEM_GDBINIT
|
| +@item (not enabled with @code{--with-system-gdbinit} during compilation)
|
| +@end ifclear
|
| +System-wide initialization file. It is executed unless user specified
|
| +@value{GDBN} option @code{-nx} or @code{-n}.
|
| +See more in
|
| +@ifset man
|
| +the @value{GDBN} manual in node @code{System-wide configuration}
|
| +-- shell command @code{info -f gdb -n 'System-wide configuration'}.
|
| +@end ifset
|
| +@ifclear man
|
| +@ref{System-wide configuration}.
|
| +@end ifclear
|
| +
|
| +@item ~/.gdbinit
|
| +User initialization file. It is executed unless user specified
|
| +@value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}.
|
| +
|
| +@item ./.gdbinit
|
| +Initialization file for current directory. It may need to be enabled with
|
| +@value{GDBN} security command @code{set auto-load local-gdbinit}.
|
| +See more in
|
| +@ifset man
|
| +the @value{GDBN} manual in node @code{Init File in the Current Directory}
|
| +-- shell command @code{info -f gdb -n 'Init File in the Current Directory'}.
|
| +@end ifset
|
| +@ifclear man
|
| +@ref{Init File in the Current Directory}.
|
| +@end ifclear
|
| +@end table
|
| +@c man end
|
| +
|
| +@c man begin SEEALSO gdbinit
|
| +@ifset man
|
| +gdb(1), @code{info -f gdb -n Startup}
|
| +
|
| +The full documentation for @value{GDBN} is maintained as a Texinfo manual.
|
| +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
|
| +documentation are properly installed at your site, the command
|
| +
|
| +@smallexample
|
| +info gdb
|
| +@end smallexample
|
| +
|
| +should give you access to the complete manual.
|
| +
|
| +@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
|
| +Richard M. Stallman and Roland H. Pesch, July 1991.
|
| +@end ifset
|
| +@c man end
|
| +
|
| @include gpl.texi
|
|
|
| @node GNU Free Documentation License
|
|
|
Chromium Code Reviews
Issue 124383005:
GDB 7.6.50 (Closed)
Base URL: http://git.chromium.org/native_client/nacl-gdb.git@upstream