| Index: gdb/doc/gdb.texinfo
|
| diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
|
| index 95ae00048505b7a29ae3d385b6491f83945ddd1c..a404d42396b44e7bd63daa7aaf824c68cb45c384 100644
|
| --- a/gdb/doc/gdb.texinfo
|
| +++ b/gdb/doc/gdb.texinfo
|
| @@ -18,13 +18,17 @@
|
| @end iftex
|
|
|
| @finalout
|
| -@syncodeindex ky cp
|
| -@syncodeindex tp cp
|
| +@c To avoid file-name clashes between index.html and Index.html, when
|
| +@c the manual is produced on a Posix host and then moved to a
|
| +@c case-insensitive filesystem (e.g., MS-Windows), we separate the
|
| +@c indices into two: Concept Index and all the rest.
|
| +@syncodeindex ky fn
|
| +@syncodeindex tp fn
|
|
|
| @c readline appendices use @vindex, @findex and @ftable,
|
| @c annotate.texi and gdbmi use @findex.
|
| -@syncodeindex vr cp
|
| -@syncodeindex fn cp
|
| +@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.
|
| @@ -45,6 +49,7 @@
|
| @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.
|
|
|
| Permission is granted to copy, distribute and/or modify this document
|
| @@ -114,7 +119,7 @@ This is the @value{EDITION} Edition, for @value{GDBN}
|
| @end ifset
|
| Version @value{GDBVN}.
|
|
|
| -Copyright (C) 1988-2010 Free Software Foundation, Inc.
|
| +Copyright (C) 1988-2012 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
|
| @@ -154,6 +159,7 @@ software in general. We will miss him.
|
| * GDB/MI:: @value{GDBN}'s Machine Interface.
|
| * Annotations:: @value{GDBN}'s annotation interface.
|
| * JIT Interface:: Using the JIT debugging interface.
|
| +* In-Process Agent:: In-Process Agent
|
|
|
| * GDB Bugs:: Reporting bugs in @value{GDBN}
|
|
|
| @@ -180,7 +186,9 @@ software in general. We will miss him.
|
| * Copying:: GNU General Public License says
|
| how you can copy and share GDB
|
| * GNU Free Documentation License:: The license for this documentation
|
| -* Index:: Index
|
| +* Concept Index:: Index of @value{GDBN} concepts
|
| +* Command and Variable Index:: Index of @value{GDBN} commands, variables,
|
| + functions, and Python data types
|
| @end menu
|
|
|
| @end ifnottex
|
| @@ -242,6 +250,7 @@ using either the Apple/NeXT or the GNU Objective-C runtime.
|
|
|
| @menu
|
| * Free Software:: Freely redistributable software
|
| +* Free Documentation:: Free Software Needs Free Documentation
|
| * Contributors:: Contributors to GDB
|
| @end menu
|
|
|
| @@ -261,6 +270,7 @@ Fundamentally, the General Public License is a license which says that
|
| you have these freedoms and that you cannot take these freedoms away
|
| from anyone else.
|
|
|
| +@node Free Documentation
|
| @unnumberedsec Free Software Needs Free Documentation
|
|
|
| The biggest deficiency in the free software community today is not in
|
| @@ -989,6 +999,22 @@ also be interleaved with @samp{-command} as required.
|
| -x setbreakpoints -ex 'run' a.out
|
| @end smallexample
|
|
|
| +@item -init-command @var{file}
|
| +@itemx -ix @var{file}
|
| +@cindex @code{--init-command}
|
| +@cindex @code{-ix}
|
| +Execute commands from file @var{file} before loading the inferior (but
|
| +after loading gdbinit files).
|
| +@xref{Startup}.
|
| +
|
| +@item -init-eval-command @var{command}
|
| +@itemx -iex @var{command}
|
| +@cindex @code{--init-eval-command}
|
| +@cindex @code{-iex}
|
| +Execute a single @value{GDBN} command before loading the inferior (but
|
| +after loading gdbinit files).
|
| +@xref{Startup}.
|
| +
|
| @item -directory @var{directory}
|
| @itemx -d @var{directory}
|
| @cindex @code{--directory}
|
| @@ -1012,6 +1038,7 @@ You can run @value{GDBN} in various alternative modes---for example, in
|
| batch mode or quiet mode.
|
|
|
| @table @code
|
| +@anchor{-nx}
|
| @item -nx
|
| @itemx -n
|
| @cindex @code{--nx}
|
| @@ -1179,10 +1206,9 @@ Run using @var{device} for your program's standard input and output.
|
| Activate the @dfn{Text User Interface} when starting. The Text User
|
| Interface manages several text windows on the terminal, showing
|
| source, assembly, registers and @value{GDBN} command outputs
|
| -(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the
|
| -Text User Interface can be enabled by invoking the program
|
| -@samp{@value{GDBTUI}}. Do not use this option if you run @value{GDBN} from
|
| -Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
|
| +(@pxref{TUI, ,@value{GDBN} Text User Interface}). Do not use this
|
| +option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
|
| +Using @value{GDBN} under @sc{gnu} Emacs}).
|
|
|
| @c @item -xdb
|
| @c @cindex @code{--xdb}
|
| @@ -1241,18 +1267,30 @@ used when building @value{GDBN}; @pxref{System-wide configuration,
|
| ,System-wide configuration and settings}) and executes all the commands in
|
| that file.
|
|
|
| +@anchor{Home Directory Init File}
|
| @item
|
| Reads the init file (if any) in your home directory@footnote{On
|
| DOS/Windows systems, the home directory is the one pointed to by the
|
| @code{HOME} environment variable.} and executes all the commands in
|
| that file.
|
|
|
| +@anchor{Option -init-eval-command}
|
| +@item
|
| +Executes commands and command files specified by the @samp{-iex} and
|
| +@samp{-ix} options in their specified order. Usually you should use the
|
| +@samp{-ex} and @samp{-x} options instead, but this way you can apply
|
| +settings before @value{GDBN} init files get executed and before inferior
|
| +gets loaded.
|
| +
|
| @item
|
| Processes command line options and operands.
|
|
|
| +@anchor{Init File in the Current Directory during Startup}
|
| @item
|
| Reads and executes the commands from init file (if any) in the current
|
| -working directory. This is only done if the current directory is
|
| +working directory as long as @samp{set auto-load local-gdbinit} is set to
|
| +@samp{on} (@pxref{Init File in the Current Directory}).
|
| +This is only done if the current directory is
|
| different from your home directory. Thus, you can have more than one
|
| init file, one generic in your home directory, and another, specific
|
| to the program you are debugging, in the directory where you invoke
|
| @@ -1268,18 +1306,16 @@ If you wish to disable the auto-loading during startup,
|
| you must do something like the following:
|
|
|
| @smallexample
|
| -$ gdb -ex "set auto-load-scripts off" -ex "file myprogram"
|
| +$ gdb -iex "set auto-load python-scripts off" myprogram
|
| @end smallexample
|
|
|
| -The following does not work because the auto-loading is turned off too late:
|
| -
|
| -@smallexample
|
| -$ gdb -ex "set auto-load-scripts off" myprogram
|
| -@end smallexample
|
| +Option @samp{-ex} does not work because the auto-loading is then turned
|
| +off too late.
|
|
|
| @item
|
| -Reads command files specified by the @samp{-x} option. @xref{Command
|
| -Files}, for more details about @value{GDBN} command files.
|
| +Executes commands and command files specified by the @samp{-ex} and
|
| +@samp{-x} options in their specified order. @xref{Command Files}, for
|
| +more details about @value{GDBN} command files.
|
|
|
| @item
|
| Reads the command history recorded in the @dfn{history file}.
|
| @@ -1699,7 +1735,7 @@ commands, and their documentation, for the regular expression specified in
|
| @var{args}. It prints out all matches found. For example:
|
|
|
| @smallexample
|
| -apropos reload
|
| +apropos alias
|
| @end smallexample
|
|
|
| @noindent
|
| @@ -1707,10 +1743,11 @@ results in:
|
|
|
| @smallexample
|
| @c @group
|
| -set symbol-reloading -- Set dynamic symbol table reloading
|
| - multiple times in one run
|
| -show symbol-reloading -- Show dynamic symbol table reloading
|
| - multiple times in one run
|
| +alias -- Define a new command that is an alias of an existing command
|
| +aliases -- Aliases of other commands
|
| +d -- Delete some breakpoints or auto-display expressions
|
| +del -- Delete some breakpoints or auto-display expressions
|
| +delete -- Delete some breakpoints or auto-display expressions
|
| @c @end group
|
| @end smallexample
|
|
|
| @@ -1742,8 +1779,9 @@ In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
|
| and @code{show} to inquire about the state of your program, or the state
|
| of @value{GDBN} itself. Each command supports many topics of inquiry; this
|
| manual introduces each of them in the appropriate context. The listings
|
| -under @code{info} and under @code{show} in the Index point to
|
| -all the sub-commands. @xref{Index}.
|
| +under @code{info} and under @code{show} in the Command, Variable, and
|
| +Function Index point to all the sub-commands. @xref{Command and Variable
|
| +Index}.
|
|
|
| @c @group
|
| @table @code
|
| @@ -2856,6 +2894,7 @@ programs with multiple threads.
|
| @xref{Set Watchpoints,,Setting Watchpoints}, for information about
|
| watchpoints in programs with multiple threads.
|
|
|
| +@anchor{set libthread-db-search-path}
|
| @table @code
|
| @kindex set libthread-db-search-path
|
| @cindex search path for @code{libthread_db}
|
| @@ -2870,11 +2909,15 @@ macro.
|
| On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper''
|
| @code{libthread_db} library to obtain information about threads in the
|
| inferior process. @value{GDBN} will use @samp{libthread-db-search-path}
|
| -to find @code{libthread_db}.
|
| +to find @code{libthread_db}. @value{GDBN} also consults first if inferior
|
| +specific thread debugging library loading is enabled
|
| +by @samp{set auto-load libthread-db} (@pxref{libthread_db.so.1 file}).
|
|
|
| A special entry @samp{$sdir} for @samp{libthread-db-search-path}
|
| refers to the default system directories that are
|
| -normally searched for loading shared libraries.
|
| +normally searched for loading shared libraries. The @samp{$sdir} entry
|
| +is the only kind not needing to be enabled by @samp{set auto-load libthread-db}
|
| +(@pxref{libthread_db.so.1 file}).
|
|
|
| A special entry @samp{$pdir} for @samp{libthread-db-search-path}
|
| refers to the directory from which @code{libpthread}
|
| @@ -3301,7 +3344,9 @@ all breakpoints in that range are operated on.
|
| * Disabling:: Disabling breakpoints
|
| * Conditions:: Break conditions
|
| * Break Commands:: Breakpoint command lists
|
| +* Dynamic Printf:: Dynamic printf
|
| * Save Breakpoints:: How to save breakpoints in a file
|
| +* Static Probe Points:: Listing static probe points
|
| * Error in Breakpoints:: ``Cannot insert breakpoints''
|
| * Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
|
| @end menu
|
| @@ -3485,12 +3530,17 @@ the appropriate shared library is loaded in the future.
|
| @end table
|
|
|
| @noindent
|
| -If a breakpoint is conditional, @code{info break} shows the condition on
|
| -the line following the affected breakpoint; breakpoint commands, if any,
|
| -are listed after that. A pending breakpoint is allowed to have a condition
|
| -specified for it. The condition is not parsed for validity until a shared
|
| -library is loaded that allows the pending breakpoint to resolve to a
|
| -valid location.
|
| +If a breakpoint is conditional, there are two evaluation modes: ``host'' and
|
| +``target''. If mode is ``host'', breakpoint condition evaluation is done by
|
| +@value{GDBN} on the host's side. If it is ``target'', then the condition
|
| +is evaluated by the target. The @code{info break} command shows
|
| +the condition on the line following the affected breakpoint, together with
|
| +its condition evaluation mode in between parentheses.
|
| +
|
| +Breakpoint commands, if any, are listed after that. A pending breakpoint is
|
| +allowed to have a condition specified for it. The condition is not parsed for
|
| +validity until a shared library is loaded that allows the pending
|
| +breakpoint to resolve to a valid location.
|
|
|
| @noindent
|
| @code{info break} with a breakpoint
|
| @@ -3506,6 +3556,11 @@ has been hit. This is especially useful in conjunction with the
|
| hits, look at the breakpoint info to see how many times the breakpoint
|
| was hit, and then run again, ignoring one less than that number. This
|
| will get you quickly to the last hit of that breakpoint.
|
| +
|
| +@noindent
|
| +For a breakpoints with an enable count (xref) greater than 1,
|
| +@code{info break} also displays that count.
|
| +
|
| @end table
|
|
|
| @value{GDBN} allows you to set any number of breakpoints at the same place in
|
| @@ -3682,6 +3737,47 @@ controlling the inferior in all-stop mode, @value{GDBN} behaves as if
|
| @code{breakpoint always-inserted} mode is off.
|
| @end table
|
|
|
| +@value{GDBN} handles conditional breakpoints by evaluating these conditions
|
| +when a breakpoint breaks. If the condition is true, then the process being
|
| +debugged stops, otherwise the process is resumed.
|
| +
|
| +If the target supports evaluating conditions on its end, @value{GDBN} may
|
| +download the breakpoint, together with its conditions, to it.
|
| +
|
| +This feature can be controlled via the following commands:
|
| +
|
| +@kindex set breakpoint condition-evaluation
|
| +@kindex show breakpoint condition-evaluation
|
| +@table @code
|
| +@item set breakpoint condition-evaluation host
|
| +This option commands @value{GDBN} to evaluate the breakpoint
|
| +conditions on the host's side. Unconditional breakpoints are sent to
|
| +the target which in turn receives the triggers and reports them back to GDB
|
| +for condition evaluation. This is the standard evaluation mode.
|
| +
|
| +@item set breakpoint condition-evaluation target
|
| +This option commands @value{GDBN} to download breakpoint conditions
|
| +to the target at the moment of their insertion. The target
|
| +is responsible for evaluating the conditional expression and reporting
|
| +breakpoint stop events back to @value{GDBN} whenever the condition
|
| +is true. Due to limitations of target-side evaluation, some conditions
|
| +cannot be evaluated there, e.g., conditions that depend on local data
|
| +that is only known to the host. Examples include
|
| +conditional expressions involving convenience variables, complex types
|
| +that cannot be handled by the agent expression parser and expressions
|
| +that are too long to be sent over to the target, specially when the
|
| +target is a remote system. In these cases, the conditions will be
|
| +evaluated by @value{GDBN}.
|
| +
|
| +@item set breakpoint condition-evaluation auto
|
| +This is the default mode. If the target supports evaluating breakpoint
|
| +conditions on its end, @value{GDBN} will download breakpoint conditions to
|
| +the target (limitations mentioned previously apply). If the target does
|
| +not support breakpoint condition evaluation, then @value{GDBN} will fallback
|
| +to evaluating all these conditions on the host's side.
|
| +@end table
|
| +
|
| +
|
| @cindex negative breakpoint numbers
|
| @cindex internal @value{GDBN} breakpoints
|
| @value{GDBN} itself sometimes sets breakpoints in your program for
|
| @@ -4114,6 +4210,12 @@ and @sc{gnu}/Linux.
|
| A call to @code{vfork}. This is currently only available for HP-UX
|
| and @sc{gnu}/Linux.
|
|
|
| +@item load @r{[}regexp@r{]}
|
| +@itemx unload @r{[}regexp@r{]}
|
| +The loading or unloading of a shared library. If @var{regexp} is
|
| +given, then the catchpoint will stop only if the regular expression
|
| +matches one of the affected libraries.
|
| +
|
| @end table
|
|
|
| @item tcatch @var{event}
|
| @@ -4247,8 +4349,8 @@ do not know which numbers to use.
|
| Disabling and enabling a breakpoint that has multiple locations
|
| affects all of its locations.
|
|
|
| -A breakpoint, watchpoint, or catchpoint can have any of four different
|
| -states of enablement:
|
| +A breakpoint, watchpoint, or catchpoint can have any of several
|
| +different states of enablement:
|
|
|
| @itemize @bullet
|
| @item
|
| @@ -4260,6 +4362,9 @@ Disabled. The breakpoint has no effect on your program.
|
| Enabled once. The breakpoint stops your program, but then becomes
|
| disabled.
|
| @item
|
| +Enabled for a count. The breakpoint stops your program for the next
|
| +N times, then becomes disabled.
|
| +@item
|
| Enabled for deletion. The breakpoint stops your program, but
|
| immediately after it does so it is deleted permanently. A breakpoint
|
| set with the @code{tbreak} command starts out in this state.
|
| @@ -4287,6 +4392,14 @@ become effective once again in stopping your program.
|
| Enable the specified breakpoints temporarily. @value{GDBN} disables any
|
| of these breakpoints immediately after stopping your program.
|
|
|
| +@item enable @r{[}breakpoints@r{]} count @var{count} @var{range}@dots{}
|
| +Enable the specified breakpoints temporarily. @value{GDBN} records
|
| +@var{count} with each of the specified breakpoints, and decrements a
|
| +breakpoint's count when it is hit. When any count reaches 0,
|
| +@value{GDBN} disables that breakpoint. If a breakpoint has an ignore
|
| +count (@pxref{Conditions, ,Break Conditions}), that will be
|
| +decremented to 0 before @var{count} is affected.
|
| +
|
| @item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
|
| Enable the specified breakpoints to work once, then die. @value{GDBN}
|
| deletes any of these breakpoints as soon as your program stops there.
|
| @@ -4341,6 +4454,19 @@ conditions for the
|
| purpose of performing side effects when a breakpoint is reached
|
| (@pxref{Break Commands, ,Breakpoint Command Lists}).
|
|
|
| +Breakpoint conditions can also be evaluated on the target's side if
|
| +the target supports it. Instead of evaluating the conditions locally,
|
| +@value{GDBN} encodes the expression into an agent expression
|
| +(@pxref{Agent Expressions}) suitable for execution on the target,
|
| +independently of @value{GDBN}. Global variables become raw memory
|
| +locations, locals become stack accesses, and so forth.
|
| +
|
| +In this case, @value{GDBN} will only be notified of a breakpoint trigger
|
| +when its condition evaluates to true. This mechanism may provide faster
|
| +response times depending on the performance characteristics of the target
|
| +since it does not need to keep @value{GDBN} informed about
|
| +every breakpoint trigger, even those with false conditions.
|
| +
|
| Break conditions can be specified when a breakpoint is set, by using
|
| @samp{if} in the arguments to the @code{break} command. @xref{Set
|
| Breaks, ,Setting Breakpoints}. They can also be changed at any time
|
| @@ -4506,6 +4632,114 @@ cont
|
| end
|
| @end smallexample
|
|
|
| +@node Dynamic Printf
|
| +@subsection Dynamic Printf
|
| +
|
| +@cindex dynamic printf
|
| +@cindex dprintf
|
| +The dynamic printf command @code{dprintf} combines a breakpoint with
|
| +formatted printing of your program's data to give you the effect of
|
| +inserting @code{printf} calls into your program on-the-fly, without
|
| +having to recompile it.
|
| +
|
| +In its most basic form, the output goes to the GDB console. However,
|
| +you can set the variable @code{dprintf-style} for alternate handling.
|
| +For instance, you can ask to format the output by calling your
|
| +program's @code{printf} function. This has the advantage that the
|
| +characters go to the program's output device, so they can recorded in
|
| +redirects to files and so forth.
|
| +
|
| +If you are doing remote debugging with a stub or agent, you can also
|
| +ask to have the printf handled by the remote agent. In addition to
|
| +ensuring that the output goes to the remote program's device along
|
| +with any other output the program might produce, you can also ask that
|
| +the dprintf remain active even after disconnecting from the remote
|
| +target. Using the stub/agent is also more efficient, as it can do
|
| +everything without needing to communicate with @value{GDBN}.
|
| +
|
| +@table @code
|
| +@kindex dprintf
|
| +@item dprintf @var{location},@var{template},@var{expression}[,@var{expression}@dots{}]
|
| +Whenever execution reaches @var{location}, print the values of one or
|
| +more @var{expressions} under the control of the string @var{template}.
|
| +To print several values, separate them with commas.
|
| +
|
| +@item set dprintf-style @var{style}
|
| +Set the dprintf output to be handled in one of several different
|
| +styles enumerated below. A change of style affects all existing
|
| +dynamic printfs immediately. (If you need individual control over the
|
| +print commands, simply define normal breakpoints with
|
| +explicitly-supplied command lists.)
|
| +
|
| +@item gdb
|
| +@kindex dprintf-style gdb
|
| +Handle the output using the @value{GDBN} @code{printf} command.
|
| +
|
| +@item call
|
| +@kindex dprintf-style call
|
| +Handle the output by calling a function in your program (normally
|
| +@code{printf}).
|
| +
|
| +@item agent
|
| +@kindex dprintf-style agent
|
| +Have the remote debugging agent (such as @code{gdbserver}) handle
|
| +the output itself. This style is only available for agents that
|
| +support running commands on the target.
|
| +
|
| +@item set dprintf-function @var{function}
|
| +Set the function to call if the dprintf style is @code{call}. By
|
| +default its value is @code{printf}. You may set it to any expression.
|
| +that @value{GDBN} can evaluate to a function, as per the @code{call}
|
| +command.
|
| +
|
| +@item set dprintf-channel @var{channel}
|
| +Set a ``channel'' for dprintf. If set to a non-empty value,
|
| +@value{GDBN} will evaluate it as an expression and pass the result as
|
| +a first argument to the @code{dprintf-function}, in the manner of
|
| +@code{fprintf} and similar functions. Otherwise, the dprintf format
|
| +string will be the first argument, in the manner of @code{printf}.
|
| +
|
| +As an example, if you wanted @code{dprintf} output to go to a logfile
|
| +that is a standard I/O stream assigned to the variable @code{mylog},
|
| +you could do the following:
|
| +
|
| +@example
|
| +(gdb) set dprintf-style call
|
| +(gdb) set dprintf-function fprintf
|
| +(gdb) set dprintf-channel mylog
|
| +(gdb) dprintf 25,"at line 25, glob=%d\n",glob
|
| +Dprintf 1 at 0x123456: file main.c, line 25.
|
| +(gdb) info break
|
| +1 dprintf keep y 0x00123456 in main at main.c:25
|
| + call (void) fprintf (mylog,"at line 25, glob=%d\n",glob)
|
| + continue
|
| +(gdb)
|
| +@end example
|
| +
|
| +Note that the @code{info break} displays the dynamic printf commands
|
| +as normal breakpoint commands; you can thus easily see the effect of
|
| +the variable settings.
|
| +
|
| +@item set disconnected-dprintf on
|
| +@itemx set disconnected-dprintf off
|
| +@kindex set disconnected-dprintf
|
| +Choose whether @code{dprintf} commands should continue to run if
|
| +@value{GDBN} has disconnected from the target. This only applies
|
| +if the @code{dprintf-style} is @code{agent}.
|
| +
|
| +@item show disconnected-dprintf off
|
| +@kindex show disconnected-dprintf
|
| +Show the current choice for disconnected @code{dprintf}.
|
| +
|
| +@end table
|
| +
|
| +@value{GDBN} does not check the validity of function and channel,
|
| +relying on you to supply values that are meaningful for the contexts
|
| +in which they are being used. For instance, the function and channel
|
| +may be the values of local variables, but if that is the case, then
|
| +all enabled dynamic prints must be at locations within the scope of
|
| +those locals. If evaluation fails, @value{GDBN} will report an error.
|
| +
|
| @node Save Breakpoints
|
| @subsection How to save breakpoints to a file
|
|
|
| @@ -4531,6 +4765,69 @@ and remove the breakpoint definitions you're not interested in, or
|
| that can no longer be recreated.
|
| @end table
|
|
|
| +@node Static Probe Points
|
| +@subsection Static Probe Points
|
| +
|
| +@cindex static probe point, SystemTap
|
| +@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands
|
| +for Statically Defined Tracing, and the probes are designed to have a tiny
|
| +runtime code and data footprint, and no dynamic relocations. They are
|
| +usable from assembly, C and C@t{++} languages. See
|
| +@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation}
|
| +for a good reference on how the @acronym{SDT} probes are implemented.
|
| +
|
| +Currently, @code{SystemTap} (@uref{http://sourceware.org/systemtap/})
|
| +@acronym{SDT} probes are supported on ELF-compatible systems. See
|
| +@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps}
|
| +for more information on how to add @code{SystemTap} @acronym{SDT} probes
|
| +in your applications.
|
| +
|
| +@cindex semaphores on static probe points
|
| +Some probes have an associated semaphore variable; for instance, this
|
| +happens automatically if you defined your probe using a DTrace-style
|
| +@file{.d} file. If your probe has a semaphore, @value{GDBN} will
|
| +automatically enable it when you specify a breakpoint using the
|
| +@samp{-probe-stap} notation. But, if you put a breakpoint at a probe's
|
| +location by some other method (e.g., @code{break file:line}), then
|
| +@value{GDBN} will not automatically set the semaphore.
|
| +
|
| +You can examine the available static static probes using @code{info
|
| +probes}, with optional arguments:
|
| +
|
| +@table @code
|
| +@kindex info probes
|
| +@item info probes stap @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
|
| +If given, @var{provider} is a regular expression used to match against provider
|
| +names when selecting which probes to list. If omitted, probes by all
|
| +probes from all providers are listed.
|
| +
|
| +If given, @var{name} is a regular expression to match against probe names
|
| +when selecting which probes to list. If omitted, probe names are not
|
| +considered when deciding whether to display them.
|
| +
|
| +If given, @var{objfile} is a regular expression used to select which
|
| +object files (executable or shared libraries) to examine. If not
|
| +given, all object files are considered.
|
| +
|
| +@item info probes all
|
| +List the available static probes, from all types.
|
| +@end table
|
| +
|
| +@vindex $_probe_arg@r{, convenience variable}
|
| +A probe may specify up to twelve arguments. These are available at the
|
| +point at which the probe is defined---that is, when the current PC is
|
| +at the probe's location. The arguments are available using the
|
| +convenience variables (@pxref{Convenience Vars})
|
| +@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. Each probe argument is
|
| +an integer of the appropriate size; types are not preserved. The
|
| +convenience variable @code{$_probe_argc} holds the number of arguments
|
| +at the current probe point.
|
| +
|
| +These variables are always available, but attempts to access them at
|
| +any location other than a probe point will cause @value{GDBN} to give
|
| +an error message.
|
| +
|
| +
|
| @c @ifclear BARETARGET
|
| @node Error in Breakpoints
|
| @subsection ``Cannot insert breakpoints''
|
| @@ -4688,7 +4985,7 @@ called within the line.
|
| Also, the @code{step} command only enters a function if there is line
|
| number information for the function. Otherwise it acts like the
|
| @code{next} command. This avoids problems when using @code{cc -gl}
|
| -on MIPS machines. Previously, @code{step} entered subroutines if there
|
| +on @acronym{MIPS} machines. Previously, @code{step} entered subroutines if there
|
| was any debugging information about the routine.
|
|
|
| @item step @var{count}
|
| @@ -4824,7 +5121,7 @@ invocations have returned.
|
|
|
|
|
| @kindex advance @var{location}
|
| -@itemx advance @var{location}
|
| +@item advance @var{location}
|
| Continue running the program up to the given @var{location}. An argument is
|
| required, which should be of one of the forms described in
|
| @ref{Specify Location}.
|
| @@ -5719,7 +6016,7 @@ function invocation, you end up at the beginning.
|
| @kindex set exec-direction
|
| @item set exec-direction
|
| Set the direction of target execution.
|
| -@itemx set exec-direction reverse
|
| +@item set exec-direction reverse
|
| @cindex execute forward or backward in time
|
| @value{GDBN} will perform all execution commands in reverse, until the
|
| exec-direction mode is changed to ``forward''. Affected commands include
|
| @@ -6220,7 +6517,7 @@ switches between them.
|
| On the SPARC architecture, @code{frame} needs two addresses to
|
| select an arbitrary frame: a frame pointer and a stack pointer.
|
|
|
| -On the MIPS and Alpha architecture, it needs two addresses: a stack
|
| +On the @acronym{MIPS} and Alpha architecture, it needs two addresses: a stack
|
| pointer and a program counter.
|
|
|
| On the 29k architecture, it needs three addresses: a register stack
|
| @@ -6340,16 +6637,6 @@ Print the local variables of the selected frame, each on a separate
|
| line. These are all variables (declared either static or automatic)
|
| accessible at the point of execution of the selected frame.
|
|
|
| -@kindex info catch
|
| -@cindex catch exceptions, list active handlers
|
| -@cindex exception handlers, how to list
|
| -@item info catch
|
| -Print a list of all the exception handlers that are active in the
|
| -current stack frame at the current point of execution. To see other
|
| -exception handlers, visit the associated frame (using the @code{up},
|
| -@code{down}, or @code{frame} commands); then type @code{info catch}.
|
| -@xref{Set Catchpoints, , Setting Catchpoints}.
|
| -
|
| @end table
|
|
|
|
|
| @@ -6493,6 +6780,11 @@ linespec.
|
|
|
| @item @var{filename}:@var{linenum}
|
| Specifies the line @var{linenum} in the source file @var{filename}.
|
| +If @var{filename} is a relative file name, then it will match any
|
| +source file name with the same trailing components. For example, if
|
| +@var{filename} is @samp{gcc/expr.c}, then it will match source file
|
| +name of @file{/build/trunk/gcc/expr.c}, but not
|
| +@file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}.
|
|
|
| @item @var{function}
|
| Specifies the line that begins the body of the function @var{function}.
|
| @@ -6551,6 +6843,19 @@ specify the function unambiguously, e.g., if there are several
|
| functions with identical names in different source files.
|
| @end table
|
|
|
| +@cindex breakpoint at static probe point
|
| +@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name}
|
| +The @sc{gnu}/Linux tool @code{SystemTap} provides a way for
|
| +applications to embed static probes. @xref{Static Probe Points}, for more
|
| +information on finding and using static probes. This form of linespec
|
| +specifies the location of such a static probe.
|
| +
|
| +If @var{objfile} is given, only probes coming from that shared library
|
| +or executable matching @var{objfile} as a regular expression are considered.
|
| +If @var{provider} is given, then only probes from that provider are considered.
|
| +If several probes match the spec, @value{GDBN} will insert a breakpoint at
|
| +each one of those probes.
|
| +
|
| @end table
|
|
|
|
|
| @@ -7093,6 +7398,153 @@ fields of a struct or a class are declared, use the @code{ptype @var{exp}}
|
| command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
|
| Table}.
|
|
|
| +@cindex exploring hierarchical data structures
|
| +@kindex explore
|
| +Another way of examining values of expressions and type information is
|
| +through the Python extension command @code{explore} (available only if
|
| +the @value{GDBN} build is configured with @code{--with-python}). It
|
| +offers an interactive way to start at the highest level (or, the most
|
| +abstract level) of the data type of an expression (or, the data type
|
| +itself) and explore all the way down to leaf scalar values/fields
|
| +embedded in the higher level data types.
|
| +
|
| +@table @code
|
| +@item explore @var{arg}
|
| +@var{arg} is either an expression (in the source language), or a type
|
| +visible in the current context of the program being debugged.
|
| +@end table
|
| +
|
| +The working of the @code{explore} command can be illustrated with an
|
| +example. If a data type @code{struct ComplexStruct} is defined in your
|
| +C program as
|
| +
|
| +@smallexample
|
| +struct SimpleStruct
|
| +@{
|
| + int i;
|
| + double d;
|
| +@};
|
| +
|
| +struct ComplexStruct
|
| +@{
|
| + struct SimpleStruct *ss_p;
|
| + int arr[10];
|
| +@};
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +followed by variable declarations as
|
| +
|
| +@smallexample
|
| +struct SimpleStruct ss = @{ 10, 1.11 @};
|
| +struct ComplexStruct cs = @{ &ss, @{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 @} @};
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +then, the value of the variable @code{cs} can be explored using the
|
| +@code{explore} command as follows.
|
| +
|
| +@smallexample
|
| +(gdb) explore cs
|
| +The value of `cs' is a struct/class of type `struct ComplexStruct' with
|
| +the following fields:
|
| +
|
| + ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'>
|
| + arr = <Enter 1 to explore this field of type `int [10]'>
|
| +
|
| +Enter the field number of choice:
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +Since the fields of @code{cs} are not scalar values, you are being
|
| +prompted to chose the field you want to explore. Let's say you choose
|
| +the field @code{ss_p} by entering @code{0}. Then, since this field is a
|
| +pointer, you will be asked if it is pointing to a single value. From
|
| +the declaration of @code{cs} above, it is indeed pointing to a single
|
| +value, hence you enter @code{y}. If you enter @code{n}, then you will
|
| +be asked if it were pointing to an array of values, in which case this
|
| +field will be explored as if it were an array.
|
| +
|
| +@smallexample
|
| +`cs.ss_p' is a pointer to a value of type `struct SimpleStruct'
|
| +Continue exploring it as a pointer to a single value [y/n]: y
|
| +The value of `*(cs.ss_p)' is a struct/class of type `struct
|
| +SimpleStruct' with the following fields:
|
| +
|
| + i = 10 .. (Value of type `int')
|
| + d = 1.1100000000000001 .. (Value of type `double')
|
| +
|
| +Press enter to return to parent value:
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +If the field @code{arr} of @code{cs} was chosen for exploration by
|
| +entering @code{1} earlier, then since it is as array, you will be
|
| +prompted to enter the index of the element in the array that you want
|
| +to explore.
|
| +
|
| +@smallexample
|
| +`cs.arr' is an array of `int'.
|
| +Enter the index of the element you want to explore in `cs.arr': 5
|
| +
|
| +`(cs.arr)[5]' is a scalar value of type `int'.
|
| +
|
| +(cs.arr)[5] = 4
|
| +
|
| +Press enter to return to parent value:
|
| +@end smallexample
|
| +
|
| +In general, at any stage of exploration, you can go deeper towards the
|
| +leaf values by responding to the prompts appropriately, or hit the
|
| +return key to return to the enclosing data structure (the @i{higher}
|
| +level data structure).
|
| +
|
| +Similar to exploring values, you can use the @code{explore} command to
|
| +explore types. Instead of specifying a value (which is typically a
|
| +variable name or an expression valid in the current context of the
|
| +program being debugged), you specify a type name. If you consider the
|
| +same example as above, your can explore the type
|
| +@code{struct ComplexStruct} by passing the argument
|
| +@code{struct ComplexStruct} to the @code{explore} command.
|
| +
|
| +@smallexample
|
| +(gdb) explore struct ComplexStruct
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +By responding to the prompts appropriately in the subsequent interactive
|
| +session, you can explore the type @code{struct ComplexStruct} in a
|
| +manner similar to how the value @code{cs} was explored in the above
|
| +example.
|
| +
|
| +The @code{explore} command also has two sub-commands,
|
| +@code{explore value} and @code{explore type}. The former sub-command is
|
| +a way to explicitly specify that value exploration of the argument is
|
| +being invoked, while the latter is a way to explicitly specify that type
|
| +exploration of the argument is being invoked.
|
| +
|
| +@table @code
|
| +@item explore value @var{expr}
|
| +@cindex explore value
|
| +This sub-command of @code{explore} explores the value of the
|
| +expression @var{expr} (if @var{expr} is an expression valid in the
|
| +current context of the program being debugged). The behavior of this
|
| +command is identical to that of the behavior of the @code{explore}
|
| +command being passed the argument @var{expr}.
|
| +
|
| +@item explore type @var{arg}
|
| +@cindex explore type
|
| +This sub-command of @code{explore} explores the type of @var{arg} (if
|
| +@var{arg} is a type visible in the current context of program being
|
| +debugged), or the type of the value/expression @var{arg} (if @var{arg}
|
| +is an expression valid in the current context of the program being
|
| +debugged). If @var{arg} is a type, then the behavior of this command is
|
| +identical to that of the @code{explore} command being passed the
|
| +argument @var{arg}. If @var{arg} is an expression, then the behavior of
|
| +this command will be identical to that of the @code{explore} command
|
| +being passed the type of @var{arg} as the argument.
|
| +@end table
|
| +
|
| @menu
|
| * Expressions:: Expressions
|
| * Ambiguous Expressions:: Ambiguous Expressions
|
| @@ -7307,7 +7759,7 @@ scope is a single source file even if the current execution point is not
|
| in this file. But it is possible to have more than one such variable or
|
| function with the same name (in different source files). If that
|
| happens, referring to that name has unpredictable effects. If you wish,
|
| -you can specify a static variable in a particular function or file,
|
| +you can specify a static variable in a particular function or file by
|
| using the colon-colon (@code{::}) notation:
|
|
|
| @cindex colon-colon, context for variables/functions
|
| @@ -7330,8 +7782,49 @@ to print a global value of @code{x} defined in @file{f2.c}:
|
| (@value{GDBP}) p 'f2.c'::x
|
| @end smallexample
|
|
|
| +The @code{::} notation is normally used for referring to
|
| +static variables, since you typically disambiguate uses of local variables
|
| +in functions by selecting the appropriate frame and using the
|
| +simple name of the variable. However, you may also use this notation
|
| +to refer to local variables in frames enclosing the selected frame:
|
| +
|
| +@smallexample
|
| +void
|
| +foo (int a)
|
| +@{
|
| + if (a < 10)
|
| + bar (a);
|
| + else
|
| + process (a); /* Stop here */
|
| +@}
|
| +
|
| +int
|
| +bar (int a)
|
| +@{
|
| + foo (a + 5);
|
| +@}
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +For example, if there is a breakpoint at the commented line,
|
| +here is what you might see
|
| +when the program stops after executing the call @code{bar(0)}:
|
| +
|
| +@smallexample
|
| +(@value{GDBP}) p a
|
| +$1 = 10
|
| +(@value{GDBP}) p bar::a
|
| +$2 = 5
|
| +(@value{GDBP}) up 2
|
| +#2 0x080483d0 in foo (a=5) at foobar.c:12
|
| +(@value{GDBP}) p a
|
| +$3 = 5
|
| +(@value{GDBP}) p bar::a
|
| +$4 = 0
|
| +@end smallexample
|
| +
|
| @cindex C@t{++} scope resolution
|
| -This use of @samp{::} is very rarely in conflict with the very similar
|
| +These uses of @samp{::} are very rarely in conflict with the very similar
|
| use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
|
| scope resolution operator in @value{GDBN} expressions.
|
| @c FIXME: Um, so what happens in one of those rare cases where it's in
|
| @@ -7970,6 +8463,24 @@ does not show the symbol name and filename of the referent, even with
|
| the appropriate @code{set print} options turned on.
|
| @end quotation
|
|
|
| +You can also enable @samp{/a}-like formatting all the time using
|
| +@samp{set print symbol on}:
|
| +
|
| +@table @code
|
| +@item set print symbol on
|
| +Tell @value{GDBN} to print the symbol corresponding to an address, if
|
| +one exists.
|
| +
|
| +@item set print symbol off
|
| +Tell @value{GDBN} not to print the symbol corresponding to an
|
| +address. In this mode, @value{GDBN} will still print the symbol
|
| +corresponding to pointers to functions. This is the default.
|
| +
|
| +@item show print symbol
|
| +Show whether @value{GDBN} will display the symbol corresponding to an
|
| +address.
|
| +@end table
|
| +
|
| Other settings control how different kinds of objects are printed:
|
|
|
| @table @code
|
| @@ -8373,7 +8884,8 @@ When displaying a pointer to an object, identify the @emph{actual}
|
| the virtual function table. Note that the virtual function table is
|
| required---this feature can only work for objects that have run-time
|
| type identification; a single virtual method in the object's declared
|
| -type is sufficient.
|
| +type is sufficient. Note that this setting is also taken into account when
|
| +working with variable objects via MI (@pxref{GDB/MI}).
|
|
|
| @item set print object off
|
| Display only the declared type of objects, without reference to the
|
| @@ -8766,6 +9278,10 @@ to match the format in which the data was printed.
|
| The variable @code{$_exitcode} is automatically set to the exit code when
|
| the program being debugged terminates.
|
|
|
| +@item $_probe_argc
|
| +@itemx $_probe_arg0@dots{}$_probe_arg11
|
| +Arguments to a static probe. @xref{Static Probe Points}.
|
| +
|
| @item $_sdata
|
| @vindex $_sdata@r{, inspect, convenience variable}
|
| The variable @code{$_sdata} contains extra collected static tracepoint
|
| @@ -9023,23 +9539,109 @@ most appropriate form for a recognized tag, and in hexadecimal for
|
| an unrecognized tag.
|
| @end table
|
|
|
| -On some targets, @value{GDBN} can access operating-system-specific information
|
| -and display it to user, without interpretation. For remote targets,
|
| -this functionality depends on the remote stub's support of the
|
| +On some targets, @value{GDBN} can access operating system-specific
|
| +information and show it to you. The types of information available
|
| +will differ depending on the type of operating system running on the
|
| +target. The mechanism used to fetch the data is described in
|
| +@ref{Operating System Information}. For remote targets, this
|
| +functionality depends on the remote stub's support of the
|
| @samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}.
|
|
|
| @table @code
|
| @kindex info os
|
| -@item info os
|
| -List the types of OS information available for the target. If the
|
| -target does not return a list of possible types, this command will
|
| -report an error.
|
| +@item info os @var{infotype}
|
| +
|
| +Display OS information of the requested type.
|
| +
|
| +On @sc{gnu}/Linux, the following values of @var{infotype} are valid:
|
|
|
| +@anchor{linux info os infotypes}
|
| +@table @code
|
| @kindex info os processes
|
| -@item info os processes
|
| +@item processes
|
| Display the list of processes on the target. For each process,
|
| -@value{GDBN} prints the process identifier, the name of the user, and
|
| -the command corresponding to the process.
|
| +@value{GDBN} prints the process identifier, the name of the user, the
|
| +command corresponding to the process, and the list of processor cores
|
| +that the process is currently running on. (To understand what these
|
| +properties mean, for this and the following info types, please consult
|
| +the general @sc{gnu}/Linux documentation.)
|
| +
|
| +@kindex info os procgroups
|
| +@item procgroups
|
| +Display the list of process groups on the target. For each process,
|
| +@value{GDBN} prints the identifier of the process group that it belongs
|
| +to, the command corresponding to the process group leader, the process
|
| +identifier, and the command line of the process. The list is sorted
|
| +first by the process group identifier, then by the process identifier,
|
| +so that processes belonging to the same process group are grouped together
|
| +and the process group leader is listed first.
|
| +
|
| +@kindex info os threads
|
| +@item threads
|
| +Display the list of threads running on the target. For each thread,
|
| +@value{GDBN} prints the identifier of the process that the thread
|
| +belongs to, the command of the process, the thread identifier, and the
|
| +processor core that it is currently running on. The main thread of a
|
| +process is not listed.
|
| +
|
| +@kindex info os files
|
| +@item files
|
| +Display the list of open file descriptors on the target. For each
|
| +file descriptor, @value{GDBN} prints the identifier of the process
|
| +owning the descriptor, the command of the owning process, the value
|
| +of the descriptor, and the target of the descriptor.
|
| +
|
| +@kindex info os sockets
|
| +@item sockets
|
| +Display the list of Internet-domain sockets on the target. For each
|
| +socket, @value{GDBN} prints the address and port of the local and
|
| +remote endpoints, the current state of the connection, the creator of
|
| +the socket, the IP address family of the socket, and the type of the
|
| +connection.
|
| +
|
| +@kindex info os shm
|
| +@item shm
|
| +Display the list of all System V shared-memory regions on the target.
|
| +For each shared-memory region, @value{GDBN} prints the region key,
|
| +the shared-memory identifier, the access permissions, the size of the
|
| +region, the process that created the region, the process that last
|
| +attached to or detached from the region, the current number of live
|
| +attaches to the region, and the times at which the region was last
|
| +attached to, detach from, and changed.
|
| +
|
| +@kindex info os semaphores
|
| +@item semaphores
|
| +Display the list of all System V semaphore sets on the target. For each
|
| +semaphore set, @value{GDBN} prints the semaphore set key, the semaphore
|
| +set identifier, the access permissions, the number of semaphores in the
|
| +set, the user and group of the owner and creator of the semaphore set,
|
| +and the times at which the semaphore set was operated upon and changed.
|
| +
|
| +@kindex info os msg
|
| +@item msg
|
| +Display the list of all System V message queues on the target. For each
|
| +message queue, @value{GDBN} prints the message queue key, the message
|
| +queue identifier, the access permissions, the current number of bytes
|
| +on the queue, the current number of messages on the queue, the processes
|
| +that last sent and received a message on the queue, the user and group
|
| +of the owner and creator of the message queue, the times at which a
|
| +message was last sent and received on the queue, and the time at which
|
| +the message queue was last changed.
|
| +
|
| +@kindex info os modules
|
| +@item modules
|
| +Display the list of all loaded kernel modules on the target. For each
|
| +module, @value{GDBN} prints the module name, the size of the module in
|
| +bytes, the number of times the module is used, the dependencies of the
|
| +module, the status of the module, and the address of the loaded module
|
| +in memory.
|
| +@end table
|
| +
|
| +@item info os
|
| +If @var{infotype} is omitted, then list the possible values for
|
| +@var{infotype} and the kind of OS information available for each
|
| +@var{infotype}. If the target does not return a list of possible
|
| +types, this command will report an error.
|
| @end table
|
|
|
| @node Memory Region Attributes
|
| @@ -9771,14 +10373,6 @@ function calls are the same as normal calls:
|
|
|
| @itemize @bullet
|
| @item
|
| -You cannot set breakpoints on inlined functions. @value{GDBN}
|
| -either reports that there is no symbol with that name, or else sets the
|
| -breakpoint only on non-inlined copies of the function. This limitation
|
| -will be removed in a future version of @value{GDBN}; until then,
|
| -set a breakpoint by line number on the first line of the inlined
|
| -function instead.
|
| -
|
| -@item
|
| Setting breakpoints at the call site of an inlined function may not
|
| work, because the call site does not contain any code. @value{GDBN}
|
| may incorrectly move the breakpoint to the next line of the enclosing
|
| @@ -10718,6 +11312,16 @@ Collect all local variables.
|
| Collect the return address. This is helpful if you want to see more
|
| of a backtrace.
|
|
|
| +@item $_probe_argc
|
| +Collects the number of arguments from the static probe at which the
|
| +tracepoint is located.
|
| +@xref{Static Probe Points}.
|
| +
|
| +@item $_probe_arg@var{n}
|
| +@var{n} is an integer between 0 and 11. Collects the @var{n}th argument
|
| +from the static probe at which the tracepoint is located.
|
| +@xref{Static Probe Points}.
|
| +
|
| @item $_sdata
|
| @vindex $_sdata@r{, collect}
|
| Collect static tracepoint marker specific data. Only available for
|
| @@ -12190,8 +12794,8 @@ being set automatically by @value{GDBN}.
|
| @node Supported Languages
|
| @section Supported Languages
|
|
|
| -@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, OpenCL C, Pascal,
|
| -assembly, Modula-2, and Ada.
|
| +@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, Java,
|
| +OpenCL C, Pascal, assembly, Modula-2, and Ada.
|
| @c This is false ...
|
| Some @value{GDBN} features may be used in expressions regardless of the
|
| language you use: the @value{GDBN} @code{@@} and @code{::} operators,
|
| @@ -12210,6 +12814,7 @@ language reference or tutorial.
|
| @menu
|
| * C:: C and C@t{++}
|
| * D:: D
|
| +* Go:: Go
|
| * Objective-C:: Objective-C
|
| * OpenCL C:: OpenCL C
|
| * Fortran:: Fortran
|
| @@ -12669,6 +13274,12 @@ Print inheritance relationships as well as other information for type
|
| @var{typename}.
|
| @xref{Symbols, ,Examining the Symbol Table}.
|
|
|
| +@item info vtbl @var{expression}.
|
| +The @code{info vtbl} command can be used to display the virtual
|
| +method tables of the object computed by @var{expression}. This shows
|
| +one entry per virtual table; there may be multiple virtual tables when
|
| +multiple inheritance is in use.
|
| +
|
| @cindex C@t{++} symbol display
|
| @item set print demangle
|
| @itemx show print demangle
|
| @@ -12756,6 +13367,55 @@ See @ref{PowerPC,,PowerPC} for more details.
|
| GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D
|
| specific feature --- dynamic arrays.
|
|
|
| +@node Go
|
| +@subsection Go
|
| +
|
| +@cindex Go (programming language)
|
| +@value{GDBN} can be used to debug programs written in Go and compiled with
|
| +@file{gccgo} or @file{6g} compilers.
|
| +
|
| +Here is a summary of the Go-specific features and restrictions:
|
| +
|
| +@table @code
|
| +@cindex current Go package
|
| +@item The current Go package
|
| +The name of the current package does not need to be specified when
|
| +specifying global variables and functions.
|
| +
|
| +For example, given the program:
|
| +
|
| +@example
|
| +package main
|
| +var myglob = "Shall we?"
|
| +func main () @{
|
| + // ...
|
| +@}
|
| +@end example
|
| +
|
| +When stopped inside @code{main} either of these work:
|
| +
|
| +@example
|
| +(gdb) p myglob
|
| +(gdb) p main.myglob
|
| +@end example
|
| +
|
| +@cindex builtin Go types
|
| +@item Builtin Go types
|
| +The @code{string} type is recognized by @value{GDBN} and is printed
|
| +as a string.
|
| +
|
| +@cindex builtin Go functions
|
| +@item Builtin Go functions
|
| +The @value{GDBN} expression parser recognizes the @code{unsafe.Sizeof}
|
| +function and handles it internally.
|
| +
|
| +@cindex restrictions on Go expressions
|
| +@item Restrictions on Go expressions
|
| +All Go operators are supported except @code{&^}.
|
| +The Go @code{_} ``blank identifier'' is not supported.
|
| +Automatic dereferencing of pointers is not supported.
|
| +@end table
|
| +
|
| @node Objective-C
|
| @subsection Objective-C
|
|
|
| @@ -14603,33 +15263,6 @@ from the @code{ptype} command can be overwhelming and hard to use. The
|
| which match the regular-expression @var{regexp}.
|
| @end ignore
|
|
|
| -@cindex reloading symbols
|
| -Some systems allow individual object files that make up your program to
|
| -be replaced without stopping and restarting your program. For example,
|
| -in VxWorks you can simply recompile a defective object file and keep on
|
| -running. If you are running on one of these systems, you can allow
|
| -@value{GDBN} to reload the symbols for automatically relinked modules:
|
| -
|
| -@table @code
|
| -@kindex set symbol-reloading
|
| -@item set symbol-reloading on
|
| -Replace symbol definitions for the corresponding source file when an
|
| -object file with a particular name is seen again.
|
| -
|
| -@item set symbol-reloading off
|
| -Do not replace symbol definitions when encountering object files of the
|
| -same name more than once. This is the default state; if you are not
|
| -running on a system that permits automatic relinking of modules, you
|
| -should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
|
| -may discard symbols when linking large programs, that may contain
|
| -several modules (from different directories or libraries) with the same
|
| -name.
|
| -
|
| -@kindex show symbol-reloading
|
| -@item show symbol-reloading
|
| -Show the current @code{on} or @code{off} setting.
|
| -@end table
|
| -
|
| @cindex opaque data types
|
| @kindex set opaque-type-resolution
|
| @item set opaque-type-resolution on
|
| @@ -15553,8 +16186,14 @@ discarded.
|
| @end table
|
|
|
| Sometimes you may wish that @value{GDBN} stops and gives you control
|
| -when any of shared library events happen. Use the @code{set
|
| -stop-on-solib-events} command for this:
|
| +when any of shared library events happen. The best way to do this is
|
| +to use @code{catch load} and @code{catch unload} (@pxref{Set
|
| +Catchpoints}).
|
| +
|
| +@value{GDBN} also supports the the @code{set stop-on-solib-events}
|
| +command for this. This command exists for historical reasons. It is
|
| +less useful than setting a catchpoint, because it does not allow for
|
| +conditions or commands as a catchpoint does.
|
|
|
| @table @code
|
| @item set stop-on-solib-events
|
| @@ -15778,7 +16417,7 @@ Show whether a source file may have multiple base names.
|
| @cindex debugging information in separate files
|
| @cindex @file{.debug} subdirectories
|
| @cindex debugging information directory, global
|
| -@cindex global debugging information directory
|
| +@cindex global debugging information directories
|
| @cindex build ID, and separate debugging files
|
| @cindex @file{.build-id} directory
|
|
|
| @@ -15823,14 +16462,14 @@ uses two different methods of looking for the debug file:
|
| @item
|
| For the ``debug link'' method, @value{GDBN} looks up the named file in
|
| the directory of the executable file, then in a subdirectory of that
|
| -directory named @file{.debug}, and finally under the global debug
|
| -directory, in a subdirectory whose name is identical to the leading
|
| +directory named @file{.debug}, and finally under each one of the global debug
|
| +directories, in a subdirectory whose name is identical to the leading
|
| directories of the executable's absolute file name.
|
|
|
| @item
|
| For the ``build ID'' method, @value{GDBN} looks in the
|
| -@file{.build-id} subdirectory of the global debug directory for a file
|
| -named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the
|
| +@file{.build-id} subdirectory of each one of the global debug directories for
|
| +a file named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the
|
| first 2 hex characters of the build ID bit string, and @var{nnnnnnnn}
|
| are the rest of the bit string. (Real build ID strings are 32 or more
|
| hex characters, not 10.)
|
| @@ -15839,7 +16478,7 @@ hex characters, not 10.)
|
| So, for example, suppose you ask @value{GDBN} to debug
|
| @file{/usr/bin/ls}, which has a debug link that specifies the
|
| file @file{ls.debug}, and a build ID whose value in hex is
|
| -@code{abcdef1234}. If the global debug directory is
|
| +@code{abcdef1234}. If the list of the global debug directories includes
|
| @file{/usr/lib/debug}, then @value{GDBN} will look for the following
|
| debug information files, in the indicated order:
|
|
|
| @@ -15854,16 +16493,19 @@ debug information files, in the indicated order:
|
| @file{/usr/lib/debug/usr/bin/ls.debug}.
|
| @end itemize
|
|
|
| -You can set the global debugging info directory's name, and view the
|
| -name @value{GDBN} is currently using.
|
| +@anchor{debug-file-directory}
|
| +Global debugging info directories default to what is set by @value{GDBN}
|
| +configure option @option{--with-separate-debug-dir}. During @value{GDBN} run
|
| +you can also set the global debugging info directories, and view the list
|
| +@value{GDBN} is currently using.
|
|
|
| @table @code
|
|
|
| @kindex set debug-file-directory
|
| @item set debug-file-directory @var{directories}
|
| Set the directories which @value{GDBN} searches for separate debugging
|
| -information files to @var{directory}. Multiple directory components can be set
|
| -concatenating them by a directory separator.
|
| +information files to @var{directory}. Multiple path components can be set
|
| +concatenating them by a path separator.
|
|
|
| @kindex show debug-file-directory
|
| @item show debug-file-directory
|
| @@ -16104,6 +16746,28 @@ $ objcopy --add-section .gdb_index=symfile.gdb-index \
|
| --set-section-flags .gdb_index=readonly symfile symfile
|
| @end smallexample
|
|
|
| +@value{GDBN} will normally ignore older versions of @file{.gdb_index}
|
| +sections that have been deprecated. Usually they are deprecated because
|
| +they are missing a new feature or have performance issues.
|
| +To tell @value{GDBN} to use a deprecated index section anyway
|
| +specify @code{set use-deprecated-index-sections on}.
|
| +The default is @code{off}.
|
| +This can speed up startup, but may result in some functionality being lost.
|
| +@xref{Index Section Format}.
|
| +
|
| +@emph{Warning:} Setting @code{use-deprecated-index-sections} to @code{on}
|
| +must be done before gdb reads the file. The following will not work:
|
| +
|
| +@smallexample
|
| +$ gdb -ex "set use-deprecated-index-sections on" <program>
|
| +@end smallexample
|
| +
|
| +Instead you must do, for example,
|
| +
|
| +@smallexample
|
| +$ gdb -iex "set use-deprecated-index-sections on" <program>
|
| +@end smallexample
|
| +
|
| There are currently some limitation on indices. They only work when
|
| for DWARF debugging information, not stabs. And, they do not
|
| currently work for programs using Ada.
|
| @@ -16479,7 +17143,7 @@ load programs into flash memory.
|
| @cindex choosing target byte order
|
| @cindex target byte order
|
|
|
| -Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
|
| +Some types of processors, such as the @acronym{MIPS}, PowerPC, and Renesas SH,
|
| offer the ability to run either big-endian or little-endian byte
|
| orders. Usually the executable or symbol will include a bit to
|
| designate the endian-ness, and you will not need to worry about
|
| @@ -16764,8 +17428,10 @@ syntax is:
|
| target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
|
| @end smallexample
|
|
|
| -@var{comm} is either a device name (to use a serial line) or a TCP
|
| -hostname and portnumber. For example, to debug Emacs with the argument
|
| +@var{comm} is either a device name (to use a serial line), or a TCP
|
| +hostname and portnumber, or @code{-} or @code{stdio} to use
|
| +stdin/stdout of @code{gdbserver}.
|
| +For example, to debug Emacs with the argument
|
| @samp{foo.txt} and communicate with @value{GDBN} over the serial port
|
| @file{/dev/com1}:
|
|
|
| @@ -16794,6 +17460,23 @@ conflicts with another service, @code{gdbserver} prints an error message
|
| and exits.} You must use the same port number with the host @value{GDBN}
|
| @code{target remote} command.
|
|
|
| +The @code{stdio} connection is useful when starting @code{gdbserver}
|
| +with ssh:
|
| +
|
| +@smallexample
|
| +(gdb) target remote | ssh -T hostname gdbserver - hello
|
| +@end smallexample
|
| +
|
| +The @samp{-T} option to ssh is provided because we don't need a remote pty,
|
| +and we don't want escape-character handling. Ssh does this by default when
|
| +a command is provided, the flag is provided to make it explicit.
|
| +You could elide it if you want to.
|
| +
|
| +Programs started with stdio-connected gdbserver have @file{/dev/null} for
|
| +@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for
|
| +display through a pipe connected to gdbserver.
|
| +Both @code{stdout} and @code{stderr} use the same pipe.
|
| +
|
| @subsubsection Attaching to a Running Program
|
| @cindex attach to a program, @code{gdbserver}
|
| @cindex @option{--attach}, @code{gdbserver} option
|
| @@ -17371,6 +18054,10 @@ are:
|
| @tab @code{QPassSignals}
|
| @tab @code{handle @var{signal}}
|
|
|
| +@item @code{program-signals}
|
| +@tab @code{QProgramSignals}
|
| +@tab @code{handle @var{signal}}
|
| +
|
| @item @code{hostio-close-packet}
|
| @tab @code{vFile:close}
|
| @tab @code{remote get}, @code{remote put}
|
| @@ -17391,6 +18078,10 @@ are:
|
| @tab @code{vFile:unlink}
|
| @tab @code{remote delete}
|
|
|
| +@item @code{hostio-readlink-packet}
|
| +@tab @code{vFile:readlink}
|
| +@tab Host I/O
|
| +
|
| @item @code{noack-packet}
|
| @tab @code{QStartNoAckMode}
|
| @tab Packet acknowledgment
|
| @@ -17414,6 +18105,10 @@ are:
|
| @item @code{disable-randomization}
|
| @tab @code{QDisableRandomization}
|
| @tab @code{set disable-randomization}
|
| +
|
| +@item @code{conditional-breakpoints-packet}
|
| +@tab @code{Z0 and Z1}
|
| +@tab @code{Support for target-side breakpoint condition evaluation}
|
| @end multitable
|
|
|
| @node Remote Stub
|
| @@ -17534,8 +18229,8 @@ subroutines:
|
| @findex set_debug_traps
|
| @cindex remote serial stub, initialization
|
| This routine arranges for @code{handle_exception} to run when your
|
| -program stops. You must call this subroutine explicitly near the
|
| -beginning of your program.
|
| +program stops. You must call this subroutine explicitly in your
|
| +program's startup code.
|
|
|
| @item handle_exception
|
| @findex handle_exception
|
| @@ -17681,13 +18376,22 @@ Make sure you have defined the supporting low-level routines
|
| @end display
|
|
|
| @item
|
| -Insert these lines near the top of your program:
|
| +Insert these lines in your program's startup code, before the main
|
| +procedure is called:
|
|
|
| @smallexample
|
| set_debug_traps();
|
| breakpoint();
|
| @end smallexample
|
|
|
| +On some machines, when a breakpoint trap is raised, the hardware
|
| +automatically makes the PC point to the instruction after the
|
| +breakpoint. If your machine doesn't do that, you may need to adjust
|
| +@code{handle_exception} to arrange for it to return to the instruction
|
| +after the breakpoint on this first invocation, so that your program
|
| +doesn't keep hitting the initial breakpoint instead of making
|
| +progress.
|
| +
|
| @item
|
| For the 680x0 stub only, you need to provide a variable called
|
| @code{exceptionHook}. Normally you just use:
|
| @@ -18799,8 +19503,8 @@ acceptable commands.
|
| * MicroBlaze:: Xilinx MicroBlaze
|
| * MIPS Embedded:: MIPS Embedded
|
| * OpenRISC 1000:: OpenRisc 1000
|
| -* PA:: HP PA Embedded
|
| * PowerPC Embedded:: PowerPC Embedded
|
| +* PA:: HP PA Embedded
|
| * Sparclet:: Tsqware Sparclet
|
| * Sparclite:: Fujitsu Sparclite
|
| * Z8000:: Zilog Z8000
|
| @@ -19106,12 +19810,12 @@ Show MicroBlaze-specific debugging level.
|
| @end table
|
|
|
| @node MIPS Embedded
|
| -@subsection MIPS Embedded
|
| +@subsection @acronym{MIPS} Embedded
|
|
|
| -@cindex MIPS boards
|
| -@value{GDBN} can use the MIPS remote debugging protocol to talk to a
|
| -MIPS board attached to a serial line. This is available when
|
| -you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
|
| +@cindex @acronym{MIPS} boards
|
| +@value{GDBN} can use the @acronym{MIPS} remote debugging protocol to talk to a
|
| +@acronym{MIPS} board attached to a serial line. This is available when
|
| +you configure @value{GDBN} with @samp{--target=mips-elf}.
|
|
|
| @need 1000
|
| Use these @value{GDBN} commands to specify the connection to your target board:
|
| @@ -19168,7 +19872,7 @@ Array Tech LSI33K RAID controller board.
|
|
|
|
|
| @noindent
|
| -@value{GDBN} also supports these special commands for MIPS targets:
|
| +@value{GDBN} also supports these special commands for @acronym{MIPS} targets:
|
|
|
| @table @code
|
| @item set mipsfpu double
|
| @@ -19178,9 +19882,9 @@ Array Tech LSI33K RAID controller board.
|
| @itemx show mipsfpu
|
| @kindex set mipsfpu
|
| @kindex show mipsfpu
|
| -@cindex MIPS remote floating point
|
| -@cindex floating point, MIPS remote
|
| -If your target board does not support the MIPS floating point
|
| +@cindex @acronym{MIPS} remote floating point
|
| +@cindex floating point, @acronym{MIPS} remote
|
| +If your target board does not support the @acronym{MIPS} floating point
|
| coprocessor, you should use the command @samp{set mipsfpu none} (if you
|
| need this, you may wish to put the command in your @value{GDBN} init
|
| file). This tells @value{GDBN} how to find the return value of
|
| @@ -19203,20 +19907,20 @@ As usual, you can inquire about the @code{mipsfpu} variable with
|
| @itemx set retransmit-timeout @var{seconds}
|
| @itemx show timeout
|
| @itemx show retransmit-timeout
|
| -@cindex @code{timeout}, MIPS protocol
|
| -@cindex @code{retransmit-timeout}, MIPS protocol
|
| +@cindex @code{timeout}, @acronym{MIPS} protocol
|
| +@cindex @code{retransmit-timeout}, @acronym{MIPS} protocol
|
| @kindex set timeout
|
| @kindex show timeout
|
| @kindex set retransmit-timeout
|
| @kindex show retransmit-timeout
|
| -You can control the timeout used while waiting for a packet, in the MIPS
|
| +You can control the timeout used while waiting for a packet, in the @acronym{MIPS}
|
| remote protocol, with the @code{set timeout @var{seconds}} command. The
|
| default is 5 seconds. Similarly, you can control the timeout used while
|
| waiting for an acknowledgment of a packet with the @code{set
|
| retransmit-timeout @var{seconds}} command. The default is 3 seconds.
|
| You can inspect both values with @code{show timeout} and @code{show
|
| retransmit-timeout}. (These commands are @emph{only} available when
|
| -@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
|
| +@value{GDBN} is configured for @samp{--target=mips-elf}.)
|
|
|
| The timeout set by @code{set timeout} does not apply when @value{GDBN}
|
| is waiting for your program to stop. In that case, @value{GDBN} waits
|
| @@ -19224,19 +19928,19 @@ forever because it has no way of knowing how long the program is going
|
| to run before stopping.
|
|
|
| @item set syn-garbage-limit @var{num}
|
| -@kindex set syn-garbage-limit@r{, MIPS remote}
|
| -@cindex synchronize with remote MIPS target
|
| +@kindex set syn-garbage-limit@r{, @acronym{MIPS} remote}
|
| +@cindex synchronize with remote @acronym{MIPS} target
|
| Limit the maximum number of characters @value{GDBN} should ignore when
|
| it tries to synchronize with the remote target. The default is 10
|
| characters. Setting the limit to -1 means there's no limit.
|
|
|
| @item show syn-garbage-limit
|
| -@kindex show syn-garbage-limit@r{, MIPS remote}
|
| +@kindex show syn-garbage-limit@r{, @acronym{MIPS} remote}
|
| Show the current limit on the number of characters to ignore when
|
| trying to synchronize with the remote system.
|
|
|
| @item set monitor-prompt @var{prompt}
|
| -@kindex set monitor-prompt@r{, MIPS remote}
|
| +@kindex set monitor-prompt@r{, @acronym{MIPS} remote}
|
| @cindex remote monitor prompt
|
| Tell @value{GDBN} to expect the specified @var{prompt} string from the
|
| remote monitor. The default depends on the target:
|
| @@ -19250,23 +19954,23 @@ remote monitor. The default depends on the target:
|
| @end table
|
|
|
| @item show monitor-prompt
|
| -@kindex show monitor-prompt@r{, MIPS remote}
|
| +@kindex show monitor-prompt@r{, @acronym{MIPS} remote}
|
| Show the current strings @value{GDBN} expects as the prompt from the
|
| remote monitor.
|
|
|
| @item set monitor-warnings
|
| -@kindex set monitor-warnings@r{, MIPS remote}
|
| +@kindex set monitor-warnings@r{, @acronym{MIPS} remote}
|
| Enable or disable monitor warnings about hardware breakpoints. This
|
| has effect only for the @code{lsi} target. When on, @value{GDBN} will
|
| display warning messages whose codes are returned by the @code{lsi}
|
| PMON monitor for breakpoint commands.
|
|
|
| @item show monitor-warnings
|
| -@kindex show monitor-warnings@r{, MIPS remote}
|
| +@kindex show monitor-warnings@r{, @acronym{MIPS} remote}
|
| Show the current setting of printing monitor warnings.
|
|
|
| @item pmon @var{command}
|
| -@kindex pmon@r{, MIPS remote}
|
| +@kindex pmon@r{, @acronym{MIPS} remote}
|
| @cindex send PMON command
|
| This command allows sending an arbitrary @var{command} string to the
|
| monitor. The monitor must be in debug mode for this to work.
|
| @@ -19789,6 +20493,9 @@ 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}
|
| @@ -19819,7 +20526,6 @@ all uses of @value{GDBN} with the architecture, both native and cross.
|
|
|
| @menu
|
| * i386::
|
| -* A29K::
|
| * Alpha::
|
| * MIPS::
|
| * HPPA:: HP PA architecture
|
| @@ -19849,56 +20555,30 @@ Show the current setting of the convention to return @code{struct}s
|
| from functions.
|
| @end table
|
|
|
| -@node A29K
|
| -@subsection A29K
|
| -
|
| -@table @code
|
| -
|
| -@kindex set rstack_high_address
|
| -@cindex AMD 29K register stack
|
| -@cindex register stack, AMD29K
|
| -@item set rstack_high_address @var{address}
|
| -On AMD 29000 family processors, registers are saved in a separate
|
| -@dfn{register stack}. There is no way for @value{GDBN} to determine the
|
| -extent of this stack. Normally, @value{GDBN} just assumes that the
|
| -stack is ``large enough''. This may result in @value{GDBN} referencing
|
| -memory locations that do not exist. If necessary, you can get around
|
| -this problem by specifying the ending address of the register stack with
|
| -the @code{set rstack_high_address} command. The argument should be an
|
| -address, which you probably want to precede with @samp{0x} to specify in
|
| -hexadecimal.
|
| -
|
| -@kindex show rstack_high_address
|
| -@item show rstack_high_address
|
| -Display the current limit of the register stack, on AMD 29000 family
|
| -processors.
|
| -
|
| -@end table
|
| -
|
| @node Alpha
|
| @subsection Alpha
|
|
|
| See the following section.
|
|
|
| @node MIPS
|
| -@subsection MIPS
|
| +@subsection @acronym{MIPS}
|
|
|
| @cindex stack on Alpha
|
| -@cindex stack on MIPS
|
| +@cindex stack on @acronym{MIPS}
|
| @cindex Alpha stack
|
| -@cindex MIPS stack
|
| -Alpha- and MIPS-based computers use an unusual stack frame, which
|
| +@cindex @acronym{MIPS} stack
|
| +Alpha- and @acronym{MIPS}-based computers use an unusual stack frame, which
|
| sometimes requires @value{GDBN} to search backward in the object code to
|
| find the beginning of a function.
|
|
|
| -@cindex response time, MIPS debugging
|
| +@cindex response time, @acronym{MIPS} debugging
|
| To improve response time (especially for embedded applications, where
|
| @value{GDBN} may be restricted to a slow serial line for this search)
|
| you may want to limit the size of this search, using one of these
|
| commands:
|
|
|
| @table @code
|
| -@cindex @code{heuristic-fence-post} (Alpha, MIPS)
|
| +@cindex @code{heuristic-fence-post} (Alpha, @acronym{MIPS})
|
| @item set heuristic-fence-post @var{limit}
|
| Restrict @value{GDBN} to examining at most @var{limit} bytes in its
|
| search for the beginning of a function. A value of @var{0} (the
|
| @@ -19913,16 +20593,16 @@ Display the current limit.
|
|
|
| @noindent
|
| These commands are available @emph{only} when @value{GDBN} is configured
|
| -for debugging programs on Alpha or MIPS processors.
|
| +for debugging programs on Alpha or @acronym{MIPS} processors.
|
|
|
| -Several MIPS-specific commands are available when debugging MIPS
|
| +Several @acronym{MIPS}-specific commands are available when debugging @acronym{MIPS}
|
| programs:
|
|
|
| @table @code
|
| @item set mips abi @var{arg}
|
| @kindex set mips abi
|
| -@cindex set ABI for MIPS
|
| -Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible
|
| +@cindex set ABI for @acronym{MIPS}
|
| +Tell @value{GDBN} which @acronym{MIPS} ABI is used by the inferior. Possible
|
| values of @var{arg} are:
|
|
|
| @table @samp
|
| @@ -19939,7 +20619,39 @@ default).
|
|
|
| @item show mips abi
|
| @kindex show mips abi
|
| -Show the MIPS ABI used by @value{GDBN} to debug the inferior.
|
| +Show the @acronym{MIPS} ABI used by @value{GDBN} to debug the inferior.
|
| +
|
| +@item set mips compression @var{arg}
|
| +@kindex set mips compression
|
| +@cindex code compression, @acronym{MIPS}
|
| +Tell @value{GDBN} which @acronym{MIPS} compressed
|
| +@acronym{ISA, Instruction Set Architecture} encoding is used by the
|
| +inferior. @value{GDBN} uses this for code disassembly and other
|
| +internal interpretation purposes. This setting is only referred to
|
| +when no executable has been associated with the debugging session or
|
| +the executable does not provide information about the encoding it uses.
|
| +Otherwise this setting is automatically updated from information
|
| +provided by the executable.
|
| +
|
| +Possible values of @var{arg} are @samp{mips16} and @samp{micromips}.
|
| +The default compressed @acronym{ISA} encoding is @samp{mips16}, as
|
| +executables containing @acronym{MIPS16} code frequently are not
|
| +identified as such.
|
| +
|
| +This setting is ``sticky''; that is, it retains its value across
|
| +debugging sessions until reset either explicitly with this command or
|
| +implicitly from an executable.
|
| +
|
| +The compiler and/or assembler typically add symbol table annotations to
|
| +identify functions compiled for the @acronym{MIPS16} or
|
| +@acronym{microMIPS} @acronym{ISA}s. If these function-scope annotations
|
| +are present, @value{GDBN} uses them in preference to the global
|
| +compressed @acronym{ISA} encoding setting.
|
| +
|
| +@item show mips compression
|
| +@kindex show mips compression
|
| +Show the @acronym{MIPS} compressed @acronym{ISA} encoding used by
|
| +@value{GDBN} to debug the inferior.
|
|
|
| @item set mipsfpu
|
| @itemx show mipsfpu
|
| @@ -19947,36 +20659,36 @@ Show the MIPS ABI used by @value{GDBN} to debug the inferior.
|
|
|
| @item set mips mask-address @var{arg}
|
| @kindex set mips mask-address
|
| -@cindex MIPS addresses, masking
|
| +@cindex @acronym{MIPS} addresses, masking
|
| This command determines whether the most-significant 32 bits of 64-bit
|
| -MIPS addresses are masked off. The argument @var{arg} can be
|
| +@acronym{MIPS} addresses are masked off. The argument @var{arg} can be
|
| @samp{on}, @samp{off}, or @samp{auto}. The latter is the default
|
| setting, which lets @value{GDBN} determine the correct value.
|
|
|
| @item show mips mask-address
|
| @kindex show mips mask-address
|
| -Show whether the upper 32 bits of MIPS addresses are masked off or
|
| +Show whether the upper 32 bits of @acronym{MIPS} addresses are masked off or
|
| not.
|
|
|
| @item set remote-mips64-transfers-32bit-regs
|
| @kindex set remote-mips64-transfers-32bit-regs
|
| -This command controls compatibility with 64-bit MIPS targets that
|
| -transfer data in 32-bit quantities. If you have an old MIPS 64 target
|
| +This command controls compatibility with 64-bit @acronym{MIPS} targets that
|
| +transfer data in 32-bit quantities. If you have an old @acronym{MIPS} 64 target
|
| that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr},
|
| and 64 bits for other registers, set this option to @samp{on}.
|
|
|
| @item show remote-mips64-transfers-32bit-regs
|
| @kindex show remote-mips64-transfers-32bit-regs
|
| -Show the current setting of compatibility with older MIPS 64 targets.
|
| +Show the current setting of compatibility with older @acronym{MIPS} 64 targets.
|
|
|
| @item set debug mips
|
| @kindex set debug mips
|
| -This command turns on and off debugging messages for the MIPS-specific
|
| +This command turns on and off debugging messages for the @acronym{MIPS}-specific
|
| target code in @value{GDBN}.
|
|
|
| @item show debug mips
|
| @kindex show debug mips
|
| -Show the current setting of MIPS debugging messages.
|
| +Show the current setting of @acronym{MIPS} debugging messages.
|
| @end table
|
|
|
|
|
| @@ -20100,6 +20812,7 @@ described here.
|
| * Screen Size:: Screen size
|
| * Numbers:: Numbers
|
| * ABI:: Configuring the current ABI
|
| +* Auto-loading:: Automatically loading associated files
|
| * Messages/Warnings:: Optional warnings and messages
|
| * Debugging Output:: Optional messages about internal happenings
|
| * Other Misc Settings:: Other Miscellaneous Settings
|
| @@ -20525,6 +21238,412 @@ With no argument, show the list of supported C@t{++} ABI's.
|
| Set the current C@t{++} ABI to @var{abi}, or return to automatic detection.
|
| @end table
|
|
|
| +@node Auto-loading
|
| +@section Automatically loading associated files
|
| +@cindex auto-loading
|
| +
|
| +@value{GDBN} sometimes reads files with commands and settings automatically,
|
| +without being explicitly told so by the user. We call this feature
|
| +@dfn{auto-loading}. While auto-loading is useful for automatically adapting
|
| +@value{GDBN} to the needs of your project, it can sometimes produce unexpected
|
| +results or introduce security risks (e.g., if the file comes from untrusted
|
| +sources).
|
| +
|
| +Note that loading of these associated files (including the local @file{.gdbinit}
|
| +file) requires accordingly configured @code{auto-load safe-path}
|
| +(@pxref{Auto-loading safe path}).
|
| +
|
| +For these reasons, @value{GDBN} includes commands and options to let you
|
| +control when to auto-load files and which files should be auto-loaded.
|
| +
|
| +@table @code
|
| +@anchor{set auto-load off}
|
| +@kindex set auto-load off
|
| +@item set auto-load off
|
| +Globally disable loading of all auto-loaded files.
|
| +You may want to use this command with the @samp{-iex} option
|
| +(@pxref{Option -init-eval-command}) such as:
|
| +@smallexample
|
| +$ @kbd{gdb -iex "set auto-load off" untrusted-executable corefile}
|
| +@end smallexample
|
| +
|
| +Be aware that system init file (@pxref{System-wide configuration})
|
| +and init files from your home directory (@pxref{Home Directory Init File})
|
| +still get read (as they come from generally trusted directories).
|
| +To prevent @value{GDBN} from auto-loading even those init files, use the
|
| +@option{-nx} option (@pxref{Mode Options}), in addition to
|
| +@code{set auto-load no}.
|
| +
|
| +@anchor{show auto-load}
|
| +@kindex show auto-load
|
| +@item show auto-load
|
| +Show whether auto-loading of each specific @samp{auto-load} file(s) is enabled
|
| +or disabled.
|
| +
|
| +@smallexample
|
| +(gdb) show auto-load
|
| +gdb-scripts: Auto-loading of canned sequences of commands scripts is on.
|
| +libthread-db: Auto-loading of inferior specific libthread_db is on.
|
| +local-gdbinit: Auto-loading of .gdbinit script from current directory
|
| + is on.
|
| +python-scripts: Auto-loading of Python scripts is on.
|
| +safe-path: List of directories from which it is safe to auto-load files
|
| + is $debugdir:$datadir/auto-load.
|
| +scripts-directory: List of directories from which to load auto-loaded scripts
|
| + is $debugdir:$datadir/auto-load.
|
| +@end smallexample
|
| +
|
| +@anchor{info auto-load}
|
| +@kindex info auto-load
|
| +@item info auto-load
|
| +Print whether each specific @samp{auto-load} file(s) have been auto-loaded or
|
| +not.
|
| +
|
| +@smallexample
|
| +(gdb) info auto-load
|
| +gdb-scripts:
|
| +Loaded Script
|
| +Yes /home/user/gdb/gdb-gdb.gdb
|
| +libthread-db: No auto-loaded libthread-db.
|
| +local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been
|
| + loaded.
|
| +python-scripts:
|
| +Loaded Script
|
| +Yes /home/user/gdb/gdb-gdb.py
|
| +@end smallexample
|
| +@end table
|
| +
|
| +These are various kinds of files @value{GDBN} can automatically load:
|
| +
|
| +@itemize @bullet
|
| +@item
|
| +@xref{objfile-gdb.py file}, controlled by @ref{set auto-load python-scripts}.
|
| +@item
|
| +@xref{objfile-gdb.gdb file}, controlled by @ref{set auto-load gdb-scripts}.
|
| +@item
|
| +@xref{dotdebug_gdb_scripts section},
|
| +controlled by @ref{set auto-load python-scripts}.
|
| +@item
|
| +@xref{Init File in the Current Directory},
|
| +controlled by @ref{set auto-load local-gdbinit}.
|
| +@item
|
| +@xref{libthread_db.so.1 file}, controlled by @ref{set auto-load libthread-db}.
|
| +@end itemize
|
| +
|
| +These are @value{GDBN} control commands for the auto-loading:
|
| +
|
| +@multitable @columnfractions .5 .5
|
| +@item @xref{set auto-load off}.
|
| +@tab Disable auto-loading globally.
|
| +@item @xref{show auto-load}.
|
| +@tab Show setting of all kinds of files.
|
| +@item @xref{info auto-load}.
|
| +@tab Show state of all kinds of files.
|
| +@item @xref{set auto-load gdb-scripts}.
|
| +@tab Control for @value{GDBN} command scripts.
|
| +@item @xref{show auto-load gdb-scripts}.
|
| +@tab Show setting of @value{GDBN} command scripts.
|
| +@item @xref{info auto-load gdb-scripts}.
|
| +@tab Show state of @value{GDBN} command scripts.
|
| +@item @xref{set auto-load python-scripts}.
|
| +@tab Control for @value{GDBN} Python scripts.
|
| +@item @xref{show auto-load python-scripts}.
|
| +@tab Show setting of @value{GDBN} Python scripts.
|
| +@item @xref{info auto-load python-scripts}.
|
| +@tab Show state of @value{GDBN} Python scripts.
|
| +@item @xref{set auto-load scripts-directory}.
|
| +@tab Control for @value{GDBN} auto-loaded scripts location.
|
| +@item @xref{show auto-load scripts-directory}.
|
| +@tab Show @value{GDBN} auto-loaded scripts location.
|
| +@item @xref{set auto-load local-gdbinit}.
|
| +@tab Control for init file in the current directory.
|
| +@item @xref{show auto-load local-gdbinit}.
|
| +@tab Show setting of init file in the current directory.
|
| +@item @xref{info auto-load local-gdbinit}.
|
| +@tab Show state of init file in the current directory.
|
| +@item @xref{set auto-load libthread-db}.
|
| +@tab Control for thread debugging library.
|
| +@item @xref{show auto-load libthread-db}.
|
| +@tab Show setting of thread debugging library.
|
| +@item @xref{info auto-load libthread-db}.
|
| +@tab Show state of thread debugging library.
|
| +@item @xref{set auto-load safe-path}.
|
| +@tab Control directories trusted for automatic loading.
|
| +@item @xref{show auto-load safe-path}.
|
| +@tab Show directories trusted for automatic loading.
|
| +@item @xref{add-auto-load-safe-path}.
|
| +@tab Add directory trusted for automatic loading.
|
| +@end multitable
|
| +
|
| +@menu
|
| +* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit}
|
| +* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db}
|
| +* objfile-gdb.gdb file:: @samp{set/show/info auto-load gdb-script}
|
| +* Auto-loading safe path:: @samp{set/show/info auto-load safe-path}
|
| +* Auto-loading verbose mode:: @samp{set/show debug auto-load}
|
| +@xref{Python Auto-loading}.
|
| +@end menu
|
| +
|
| +@node Init File in the Current Directory
|
| +@subsection Automatically loading init file in the current directory
|
| +@cindex auto-loading init file in the current directory
|
| +
|
| +By default, @value{GDBN} reads and executes the canned sequences of commands
|
| +from init file (if any) in the current working directory,
|
| +see @ref{Init File in the Current Directory during Startup}.
|
| +
|
| +Note that loading of this local @file{.gdbinit} file also requires accordingly
|
| +configured @code{auto-load safe-path} (@pxref{Auto-loading safe path}).
|
| +
|
| +@table @code
|
| +@anchor{set auto-load local-gdbinit}
|
| +@kindex set auto-load local-gdbinit
|
| +@item set auto-load local-gdbinit [on|off]
|
| +Enable or disable the auto-loading of canned sequences of commands
|
| +(@pxref{Sequences}) found in init file in the current directory.
|
| +
|
| +@anchor{show auto-load local-gdbinit}
|
| +@kindex show auto-load local-gdbinit
|
| +@item show auto-load local-gdbinit
|
| +Show whether auto-loading of canned sequences of commands from init file in the
|
| +current directory is enabled or disabled.
|
| +
|
| +@anchor{info auto-load local-gdbinit}
|
| +@kindex info auto-load local-gdbinit
|
| +@item info auto-load local-gdbinit
|
| +Print whether canned sequences of commands from init file in the
|
| +current directory have been auto-loaded.
|
| +@end table
|
| +
|
| +@node libthread_db.so.1 file
|
| +@subsection Automatically loading thread debugging library
|
| +@cindex auto-loading libthread_db.so.1
|
| +
|
| +This feature is currently present only on @sc{gnu}/Linux native hosts.
|
| +
|
| +@value{GDBN} reads in some cases thread debugging library from places specific
|
| +to the inferior (@pxref{set libthread-db-search-path}).
|
| +
|
| +The special @samp{libthread-db-search-path} entry @samp{$sdir} is processed
|
| +without checking this @samp{set auto-load libthread-db} switch as system
|
| +libraries have to be trusted in general. In all other cases of
|
| +@samp{libthread-db-search-path} entries @value{GDBN} checks first if @samp{set
|
| +auto-load libthread-db} is enabled before trying to open such thread debugging
|
| +library.
|
| +
|
| +Note that loading of this debugging library also requires accordingly configured
|
| +@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
|
| +
|
| +@table @code
|
| +@anchor{set auto-load libthread-db}
|
| +@kindex set auto-load libthread-db
|
| +@item set auto-load libthread-db [on|off]
|
| +Enable or disable the auto-loading of inferior specific thread debugging library.
|
| +
|
| +@anchor{show auto-load libthread-db}
|
| +@kindex show auto-load libthread-db
|
| +@item show auto-load libthread-db
|
| +Show whether auto-loading of inferior specific thread debugging library is
|
| +enabled or disabled.
|
| +
|
| +@anchor{info auto-load libthread-db}
|
| +@kindex info auto-load libthread-db
|
| +@item info auto-load libthread-db
|
| +Print the list of all loaded inferior specific thread debugging libraries and
|
| +for each such library print list of inferior @var{pid}s using it.
|
| +@end table
|
| +
|
| +@node objfile-gdb.gdb file
|
| +@subsection The @file{@var{objfile}-gdb.gdb} file
|
| +@cindex auto-loading @file{@var{objfile}-gdb.gdb}
|
| +
|
| +@value{GDBN} tries to load an @file{@var{objfile}-gdb.gdb} file containing
|
| +canned sequences of commands (@pxref{Sequences}), as long as @samp{set
|
| +auto-load gdb-scripts} is set to @samp{on}.
|
| +
|
| +Note that loading of this script file also requires accordingly configured
|
| +@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
|
| +
|
| +For more background refer to the similar Python scripts auto-loading
|
| +description (@pxref{objfile-gdb.py file}).
|
| +
|
| +@table @code
|
| +@anchor{set auto-load gdb-scripts}
|
| +@kindex set auto-load gdb-scripts
|
| +@item set auto-load gdb-scripts [on|off]
|
| +Enable or disable the auto-loading of canned sequences of commands scripts.
|
| +
|
| +@anchor{show auto-load gdb-scripts}
|
| +@kindex show auto-load gdb-scripts
|
| +@item show auto-load gdb-scripts
|
| +Show whether auto-loading of canned sequences of commands scripts is enabled or
|
| +disabled.
|
| +
|
| +@anchor{info auto-load gdb-scripts}
|
| +@kindex info auto-load gdb-scripts
|
| +@cindex print list of auto-loaded canned sequences of commands scripts
|
| +@item info auto-load gdb-scripts [@var{regexp}]
|
| +Print the list of all canned sequences of commands scripts that @value{GDBN}
|
| +auto-loaded.
|
| +@end table
|
| +
|
| +If @var{regexp} is supplied only canned sequences of commands scripts with
|
| +matching names are printed.
|
| +
|
| +@node Auto-loading safe path
|
| +@subsection Security restriction for auto-loading
|
| +@cindex auto-loading safe-path
|
| +
|
| +As the files of inferior can come from untrusted source (such as submitted by
|
| +an application user) @value{GDBN} does not always load any files automatically.
|
| +@value{GDBN} provides the @samp{set auto-load safe-path} setting to list
|
| +directories trusted for loading files not explicitly requested by user.
|
| +Each directory can also be a shell wildcard pattern.
|
| +
|
| +If the path is not set properly you will see a warning and the file will not
|
| +get loaded:
|
| +
|
| +@smallexample
|
| +$ ./gdb -q ./gdb
|
| +Reading symbols from /home/user/gdb/gdb...done.
|
| +warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been
|
| + declined by your `auto-load safe-path' set
|
| + to "$debugdir:$datadir/auto-load".
|
| +warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been
|
| + declined by your `auto-load safe-path' set
|
| + to "$debugdir:$datadir/auto-load".
|
| +@end smallexample
|
| +
|
| +The list of trusted directories is controlled by the following commands:
|
| +
|
| +@table @code
|
| +@anchor{set auto-load safe-path}
|
| +@kindex set auto-load safe-path
|
| +@item set auto-load safe-path @r{[}@var{directories}@r{]}
|
| +Set the list of directories (and their subdirectories) trusted for automatic
|
| +loading and execution of scripts. You can also enter a specific trusted file.
|
| +Each directory can also be a shell wildcard pattern; wildcards do not match
|
| +directory separator - see @code{FNM_PATHNAME} for system function @code{fnmatch}
|
| +(@pxref{Wildcard Matching, fnmatch, , libc, GNU C Library Reference Manual}).
|
| +If you omit @var{directories}, @samp{auto-load safe-path} will be reset to
|
| +its default value as specified during @value{GDBN} compilation.
|
| +
|
| +The list of directories uses path separator (@samp{:} on GNU and Unix
|
| +systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
|
| +to the @env{PATH} environment variable.
|
| +
|
| +@anchor{show auto-load safe-path}
|
| +@kindex show auto-load safe-path
|
| +@item show auto-load safe-path
|
| +Show the list of directories trusted for automatic loading and execution of
|
| +scripts.
|
| +
|
| +@anchor{add-auto-load-safe-path}
|
| +@kindex add-auto-load-safe-path
|
| +@item add-auto-load-safe-path
|
| +Add an entry (or list of entries) the list of directories trusted for automatic
|
| +loading and execution of scripts. Multiple entries may be delimited by the
|
| +host platform path separator in use.
|
| +@end table
|
| +
|
| +This variable defaults to what @code{--with-auto-load-dir} has been configured
|
| +to (@pxref{with-auto-load-dir}). @file{$debugdir} and @file{$datadir}
|
| +substitution applies the same as for @ref{set auto-load scripts-directory}.
|
| +The default @code{set auto-load safe-path} value can be also overriden by
|
| +@value{GDBN} configuration option @option{--with-auto-load-safe-path}.
|
| +
|
| +Setting this variable to @file{/} disables this security protection,
|
| +corresponding @value{GDBN} configuration option is
|
| +@option{--without-auto-load-safe-path}.
|
| +This variable is supposed to be set to the system directories writable by the
|
| +system superuser only. Users can add their source directories in init files in
|
| +their home directories (@pxref{Home Directory Init File}). See also deprecated
|
| +init file in the current directory
|
| +(@pxref{Init File in the Current Directory during Startup}).
|
| +
|
| +To force @value{GDBN} to load the files it declined to load in the previous
|
| +example, you could use one of the following ways:
|
| +
|
| +@table @asis
|
| +@item @file{~/.gdbinit}: @samp{add-auto-load-safe-path ~/src/gdb}
|
| +Specify this trusted directory (or a file) as additional component of the list.
|
| +You have to specify also any existing directories displayed by
|
| +by @samp{show auto-load safe-path} (such as @samp{/usr:/bin} in this example).
|
| +
|
| +@item @kbd{gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" @dots{}}
|
| +Specify this directory as in the previous case but just for a single
|
| +@value{GDBN} session.
|
| +
|
| +@item @kbd{gdb -iex "set auto-load safe-path /" @dots{}}
|
| +Disable auto-loading safety for a single @value{GDBN} session.
|
| +This assumes all the files you debug during this @value{GDBN} session will come
|
| +from trusted sources.
|
| +
|
| +@item @kbd{./configure --without-auto-load-safe-path}
|
| +During compilation of @value{GDBN} you may disable any auto-loading safety.
|
| +This assumes all the files you will ever debug with this @value{GDBN} come from
|
| +trusted sources.
|
| +@end table
|
| +
|
| +On the other hand you can also explicitly forbid automatic files loading which
|
| +also suppresses any such warning messages:
|
| +
|
| +@table @asis
|
| +@item @kbd{gdb -iex "set auto-load no" @dots{}}
|
| +You can use @value{GDBN} command-line option for a single @value{GDBN} session.
|
| +
|
| +@item @file{~/.gdbinit}: @samp{set auto-load no}
|
| +Disable auto-loading globally for the user
|
| +(@pxref{Home Directory Init File}). While it is improbable, you could also
|
| +use system init file instead (@pxref{System-wide configuration}).
|
| +@end table
|
| +
|
| +This setting applies to the file names as entered by user. If no entry matches
|
| +@value{GDBN} tries as a last resort to also resolve all the file names into
|
| +their canonical form (typically resolving symbolic links) and compare the
|
| +entries again. @value{GDBN} already canonicalizes most of the filenames on its
|
| +own before starting the comparison so a canonical form of directories is
|
| +recommended to be entered.
|
| +
|
| +@node Auto-loading verbose mode
|
| +@subsection Displaying files tried for auto-load
|
| +@cindex auto-loading verbose mode
|
| +
|
| +For better visibility of all the file locations where you can place scripts to
|
| +be auto-loaded with inferior --- or to protect yourself against accidental
|
| +execution of untrusted scripts --- @value{GDBN} provides a feature for printing
|
| +all the files attempted to be loaded. Both existing and non-existing files may
|
| +be printed.
|
| +
|
| +For example the list of directories from which it is safe to auto-load files
|
| +(@pxref{Auto-loading safe path}) applies also to canonicalized filenames which
|
| +may not be too obvious while setting it up.
|
| +
|
| +@smallexample
|
| +(gdb) set debug auto-load on
|
| +(gdb) file ~/src/t/true
|
| +auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb"
|
| + for objfile "/tmp/true".
|
| +auto-load: Updating directories of "/usr:/opt".
|
| +auto-load: Using directory "/usr".
|
| +auto-load: Using directory "/opt".
|
| +warning: File "/tmp/true-gdb.gdb" auto-loading has been declined
|
| + by your `auto-load safe-path' set to "/usr:/opt".
|
| +@end smallexample
|
| +
|
| +@table @code
|
| +@anchor{set debug auto-load}
|
| +@kindex set debug auto-load
|
| +@item set debug auto-load [on|off]
|
| +Set whether to print the filenames attempted to be auto-loaded.
|
| +
|
| +@anchor{show debug auto-load}
|
| +@kindex show debug auto-load
|
| +@item show debug auto-load
|
| +Show whether printing of the filenames attempted to be auto-loaded is turned
|
| +on or off.
|
| +@end table
|
| +
|
| @node Messages/Warnings
|
| @section Optional Warnings and Messages
|
|
|
| @@ -20673,6 +21792,12 @@ The value is the number of nesting levels to print.
|
| A value of zero turns off the display.
|
| @item show debug dwarf2-die
|
| 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.
|
| +@item show debug dwarf2-read
|
| +Show the current state of DWARF2 reader debugging.
|
| @item set debug displaced
|
| @cindex displaced stepping debugging info
|
| Turns on or off display of @value{GDBN} debugging info for the
|
| @@ -20770,6 +21895,12 @@ 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 symtab-create
|
| +@cindex symbol table creation
|
| +Turns on or off display of debugging messages related to symbol table creation.
|
| +The default is off.
|
| +@item show debug symtab-create
|
| +Show the current state of symbol table creation debugging.
|
| @item set debug target
|
| @cindex target debugging info
|
| Turns on or off display of @value{GDBN} target debugging info. This info
|
| @@ -20974,8 +22105,9 @@ command should not be repeated when the user hits @key{RET}
|
|
|
| @kindex help user-defined
|
| @item help user-defined
|
| -List all user-defined commands, with the first line of the documentation
|
| -(if any) for each.
|
| +List all user-defined commands and all python commands defined in class
|
| +COMAND_USER. The first line of the documentation or docstring is
|
| +included (if any).
|
|
|
| @kindex show user
|
| @item show user
|
| @@ -20983,6 +22115,7 @@ List all user-defined commands, with the first line of the documentation
|
| Display the @value{GDBN} commands used to define @var{commandname} (but
|
| not its documentation). If no @var{commandname} is given, display the
|
| definitions for all user-defined commands.
|
| +This does not work for user-defined python commands.
|
|
|
| @cindex infinite recursion in user-defined commands
|
| @kindex show max-user-call-depth
|
| @@ -20992,6 +22125,7 @@ definitions for all user-defined commands.
|
| The value of @code{max-user-call-depth} controls how many recursion
|
| levels are allowed in user-defined commands before @value{GDBN} suspects an
|
| infinite recursion and aborts the command.
|
| +This does not apply to user-defined python commands.
|
| @end table
|
|
|
| In addition to the above commands, user-defined commands frequently
|
| @@ -21396,7 +22530,7 @@ automatically imported when @value{GDBN} starts.
|
| @menu
|
| * Python Commands:: Accessing Python from @value{GDBN}.
|
| * Python API:: Accessing @value{GDBN} from Python.
|
| -* Auto-loading:: Automatically loading Python code.
|
| +* Python Auto-loading:: Automatically loading Python code.
|
| * Python modules:: Python modules provided by @value{GDBN}.
|
| @end menu
|
|
|
| @@ -21493,10 +22627,10 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
|
| * Blocks In Python:: Accessing frame blocks from Python.
|
| * Symbols In Python:: Python representation of symbols.
|
| * Symbol Tables In Python:: Python representation of symbol tables.
|
| -* Lazy Strings In Python:: Python representation of lazy strings.
|
| * Breakpoints In Python:: Manipulating breakpoints using Python.
|
| * Finish Breakpoints in Python:: Setting Breakpoints on function return
|
| using Python.
|
| +* Lazy Strings In Python:: Python representation of lazy strings.
|
| @end menu
|
|
|
| @node Basic Python
|
| @@ -21581,6 +22715,15 @@ compute values, for example, it is the only way to get the value of a
|
| convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
|
| @end defun
|
|
|
| +@findex gdb.find_pc_line
|
| +@defun gdb.find_pc_line (pc)
|
| +Return the @code{gdb.Symtab_and_line} object corresponding to the
|
| +@var{pc} value. @xref{Symbol Tables In Python}. If an invalid
|
| +value of @var{pc} is passed as an argument, then the @code{symtab} and
|
| +@code{line} attributes of the returned @code{gdb.Symtab_and_line} object
|
| +will be @code{None} and 0 respectively.
|
| +@end defun
|
| +
|
| @findex gdb.post_event
|
| @defun gdb.post_event (event)
|
| Put @var{event}, a callable object taking no arguments, into
|
| @@ -21792,7 +22935,7 @@ to handle this case. Example:
|
| >class HelloWorld (gdb.Command):
|
| > """Greet the whole world."""
|
| > def __init__ (self):
|
| -> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
|
| +> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
|
| > def invoke (self, args, from_tty):
|
| > argv = gdb.string_to_argv (args)
|
| > if len (argv) != 0:
|
| @@ -21970,6 +23113,79 @@ bar = foo.dereference ()
|
|
|
| The result @code{bar} will be a @code{gdb.Value} object holding the
|
| value pointed to by @code{foo}.
|
| +
|
| +A similar function @code{Value.referenced_value} exists which also
|
| +returns @code{gdb.Value} objects corresonding to the values pointed to
|
| +by pointer values (and additionally, values referenced by reference
|
| +values). However, the behavior of @code{Value.dereference}
|
| +differs from @code{Value.referenced_value} by the fact that the
|
| +behavior of @code{Value.dereference} is identical to applying the C
|
| +unary operator @code{*} on a given value. For example, consider a
|
| +reference to a pointer @code{ptrref}, declared in your C@t{++} program
|
| +as
|
| +
|
| +@smallexample
|
| +typedef int *intptr;
|
| +...
|
| +int val = 10;
|
| +intptr ptr = &val;
|
| +intptr &ptrref = ptr;
|
| +@end smallexample
|
| +
|
| +Though @code{ptrref} is a reference value, one can apply the method
|
| +@code{Value.dereference} to the @code{gdb.Value} object corresponding
|
| +to it and obtain a @code{gdb.Value} which is identical to that
|
| +corresponding to @code{val}. However, if you apply the method
|
| +@code{Value.referenced_value}, the result would be a @code{gdb.Value}
|
| +object identical to that corresponding to @code{ptr}.
|
| +
|
| +@smallexample
|
| +py_ptrref = gdb.parse_and_eval ("ptrref")
|
| +py_val = py_ptrref.dereference ()
|
| +py_ptr = py_ptrref.referenced_value ()
|
| +@end smallexample
|
| +
|
| +The @code{gdb.Value} object @code{py_val} is identical to that
|
| +corresponding to @code{val}, and @code{py_ptr} is identical to that
|
| +corresponding to @code{ptr}. In general, @code{Value.dereference} can
|
| +be applied whenever the C unary operator @code{*} can be applied
|
| +to the corresponding C value. For those cases where applying both
|
| +@code{Value.dereference} and @code{Value.referenced_value} is allowed,
|
| +the results obtained need not be identical (as we have seen in the above
|
| +example). The results are however identical when applied on
|
| +@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
|
| +objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program.
|
| +@end defun
|
| +
|
| +@defun Value.referenced_value ()
|
| +For pointer or reference data types, this method returns a new
|
| +@code{gdb.Value} object corresponding to the value referenced by the
|
| +pointer/reference value. For pointer data types,
|
| +@code{Value.dereference} and @code{Value.referenced_value} produce
|
| +identical results. The difference between these methods is that
|
| +@code{Value.dereference} cannot get the values referenced by reference
|
| +values. For example, consider a reference to an @code{int}, declared
|
| +in your C@t{++} program as
|
| +
|
| +@smallexample
|
| +int val = 10;
|
| +int &ref = val;
|
| +@end smallexample
|
| +
|
| +@noindent
|
| +then applying @code{Value.dereference} to the @code{gdb.Value} object
|
| +corresponding to @code{ref} will result in an error, while applying
|
| +@code{Value.referenced_value} will result in a @code{gdb.Value} object
|
| +identical to that corresponding to @code{val}.
|
| +
|
| +@smallexample
|
| +py_ref = gdb.parse_and_eval ("ref")
|
| +er_ref = py_ref.dereference () # Results in error
|
| +py_val = py_ref.referenced_value () # Returns the referenced value
|
| +@end smallexample
|
| +
|
| +The @code{gdb.Value} object @code{py_val} is identical to that
|
| +corresponding to @code{val}.
|
| @end defun
|
|
|
| @defun Value.dynamic_cast (type)
|
| @@ -22565,7 +23781,7 @@ This practice will enable @value{GDBN} to load multiple versions of
|
| your pretty-printers at the same time, because they will have
|
| different names.
|
|
|
| -You should write auto-loaded code (@pxref{Auto-loading}) such that it
|
| +You should write auto-loaded code (@pxref{Python Auto-loading}) such that it
|
| can be evaluated multiple times without changing its meaning. An
|
| ideal auto-load file will consist solely of @code{import}s of your
|
| printer modules, followed by a call to a register pretty-printers with
|
| @@ -22737,20 +23953,20 @@ when it is called. If there are no valid threads, the method will
|
| return an empty tuple.
|
| @end defun
|
|
|
| -@findex gdb.read_memory
|
| +@findex Inferior.read_memory
|
| @defun Inferior.read_memory (address, length)
|
| 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{gdb.write_memory}
|
| -function.
|
| +or a string. It can be modified and given to the
|
| +@code{Inferior.write_memory} function.
|
| @end defun
|
|
|
| -@findex gdb.write_memory
|
| +@findex Inferior.write_memory
|
| @defun Inferior.write_memory (address, buffer @r{[}, length@r{]})
|
| Write the contents of @var{buffer} to the inferior, starting at
|
| @var{address}. The @var{buffer} parameter must be a Python object
|
| which supports the buffer protocol, i.e., a string, an array or the
|
| -object returned from @code{gdb.read_memory}. If given, @var{length}
|
| +object returned from @code{Inferior.read_memory}. If given, @var{length}
|
| determines the number of bytes from @var{buffer} to be written.
|
| @end defun
|
|
|
| @@ -23171,6 +24387,15 @@ The command has to do with tracepoints. For example, @code{trace},
|
| @kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
|
| commands in this category.
|
|
|
| +@findex COMMAND_USER
|
| +@findex gdb.COMMAND_USER
|
| +@item gdb.COMMAND_USER
|
| +The command is a general purpose command for the user, and typically
|
| +does not fit in one of the other categories.
|
| +Type @kbd{help user-defined} at the @value{GDBN} prompt to see
|
| +a list of commands in this category, as well as the list of gdb macros
|
| +(@pxref{Sequences}).
|
| +
|
| @findex COMMAND_OBSCURE
|
| @findex gdb.COMMAND_OBSCURE
|
| @item gdb.COMMAND_OBSCURE
|
| @@ -23232,7 +24457,7 @@ class HelloWorld (gdb.Command):
|
| """Greet the whole world."""
|
|
|
| def __init__ (self):
|
| - super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
|
| + super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
|
|
|
| def invoke (self, arg, from_tty):
|
| print "Hello, World!"
|
| @@ -23526,7 +24751,7 @@ The following objfile-related functions are available in the
|
|
|
| @findex gdb.current_objfile
|
| @defun gdb.current_objfile ()
|
| -When auto-loading a Python script (@pxref{Auto-loading}), @value{GDBN}
|
| +When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN}
|
| sets the ``current objfile'' to the corresponding objfile. This
|
| function returns the current objfile. If there is no current objfile,
|
| this function returns @code{None}.
|
| @@ -23753,6 +24978,13 @@ frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more
|
| detailed technical information on @value{GDBN}'s book-keeping of the
|
| stack.
|
|
|
| +A @code{gdb.Block} is iterable. The iterator returns the symbols
|
| +(@pxref{Symbols In Python}) local to the block. Python programs
|
| +should not assume that a specific block object will always contain a
|
| +given symbol, since changes in @value{GDBN} features and
|
| +infrastructure may cause symbols move across blocks in a symbol
|
| +table.
|
| +
|
| The following block-related functions are available in the @code{gdb}
|
| module:
|
|
|
| @@ -23771,9 +25003,8 @@ 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
|
| refers to doesn't exist anymore in the inferior. All other
|
| @code{gdb.Block} methods will throw an exception if it is invalid at
|
| -the time the method is called. This method is also made available to
|
| -the Python iterator object that @code{gdb.Block} provides in an iteration
|
| -context and via the Python @code{iter} built-in function.
|
| +the time the method is called. The block's validity is also checked
|
| +during iteration over symbols of the block.
|
| @end defun
|
| @end table
|
|
|
| @@ -23888,6 +25119,11 @@ represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
|
| Python}. This attribute is not writable.
|
| @end defvar
|
|
|
| +@defvar Symbol.line
|
| +The line number in the source code at which the symbol was defined.
|
| +This is an integer.
|
| +@end defvar
|
| +
|
| @defvar Symbol.name
|
| The name of the symbol as a string. This attribute is not writable.
|
| @end defvar
|
| @@ -23909,6 +25145,12 @@ of a symbol. Each address class is a constant defined in the
|
| @code{gdb} module and described later in this chapter.
|
| @end defvar
|
|
|
| +@defvar Symbol.needs_frame
|
| +This is @code{True} if evaluating this symbol's value requires a frame
|
| +(@pxref{Frames In Python}) and @code{False} otherwise. Typically,
|
| +local variables will require a frame, but other symbols will not.
|
| +@end defvar
|
| +
|
| @defvar Symbol.is_argument
|
| @code{True} if the symbol is an argument of a function.
|
| @end defvar
|
| @@ -23936,6 +25178,15 @@ the symbol it refers to does not exist in @value{GDBN} any longer.
|
| All other @code{gdb.Symbol} methods will throw an exception if it is
|
| invalid at the time the method is called.
|
| @end defun
|
| +
|
| +@defun Symbol.value (@r{[}frame@r{]})
|
| +Compute the value of the symbol, as a @code{gdb.Value}. For
|
| +functions, this computes the address of the function, cast to the
|
| +appropriate type. If the symbol requires a frame in order to compute
|
| +its value, then @var{frame} must be given. If @var{frame} is not
|
| +given, or if @var{frame} is invalid, then this method will throw an
|
| +exception.
|
| +@end defun
|
| @end table
|
|
|
| The available domain categories in @code{gdb.Symbol} are represented
|
| @@ -24072,8 +25323,13 @@ This attribute is not writable.
|
| @end defvar
|
|
|
| @defvar Symtab_and_line.pc
|
| -Indicates the current program counter address. This attribute is not
|
| -writable.
|
| +Indicates the start of the address range occupied by code for the
|
| +current source line. This attribute is not writable.
|
| +@end defvar
|
| +
|
| +@defvar Symtab_and_line.last
|
| +Indicates the end of the address range occupied by code for the current
|
| +source line. This attribute is not writable.
|
| @end defvar
|
|
|
| @defvar Symtab_and_line.line
|
| @@ -24122,6 +25378,16 @@ if it is invalid at the time the method is called.
|
| @defun Symtab.fullname ()
|
| Return the symbol table's source absolute file name.
|
| @end defun
|
| +
|
| +@defun Symtab.global_block ()
|
| +Return the global block of the underlying symbol table.
|
| +@xref{Blocks In Python}.
|
| +@end defun
|
| +
|
| +@defun Symtab.static_block ()
|
| +Return the static block of the underlying symbol table.
|
| +@xref{Blocks In Python}.
|
| +@end defun
|
| @end table
|
|
|
| @node Breakpoints In Python
|
| @@ -24437,20 +25703,16 @@ resolve this to the lazy string's character type, use the type's
|
| writable.
|
| @end defvar
|
|
|
| -@node Auto-loading
|
| -@subsection Auto-loading
|
| -@cindex auto-loading, Python
|
| +@node Python Auto-loading
|
| +@subsection Python Auto-loading
|
| +@cindex Python auto-loading
|
|
|
| When a new object file is read (for example, due to the @code{file}
|
| command, or because the inferior has loaded a shared library),
|
| @value{GDBN} will look for Python support scripts in several ways:
|
| -@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
|
| -
|
| -@menu
|
| -* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
|
| -* .debug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
|
| -* Which flavor to choose?::
|
| -@end menu
|
| +@file{@var{objfile}-gdb.py} (@pxref{objfile-gdb.py file})
|
| +and @code{.debug_gdb_scripts} section
|
| +(@pxref{dotdebug_gdb_scripts section}).
|
|
|
| The auto-loading feature is useful for supplying application-specific
|
| debugging commands and scripts.
|
| @@ -24459,36 +25721,39 @@ Auto-loading can be enabled or disabled,
|
| and the list of auto-loaded scripts can be printed.
|
|
|
| @table @code
|
| -@kindex set auto-load-scripts
|
| -@item set auto-load-scripts [yes|no]
|
| +@anchor{set auto-load python-scripts}
|
| +@kindex set auto-load python-scripts
|
| +@item set auto-load python-scripts [on|off]
|
| Enable or disable the auto-loading of Python scripts.
|
|
|
| -@kindex show auto-load-scripts
|
| -@item show auto-load-scripts
|
| +@anchor{show auto-load python-scripts}
|
| +@kindex show auto-load python-scripts
|
| +@item show auto-load python-scripts
|
| Show whether auto-loading of Python scripts is enabled or disabled.
|
|
|
| -@kindex info auto-load-scripts
|
| -@cindex print list of auto-loaded scripts
|
| -@item info auto-load-scripts [@var{regexp}]
|
| -Print the list of all scripts that @value{GDBN} auto-loaded.
|
| +@anchor{info auto-load python-scripts}
|
| +@kindex info auto-load python-scripts
|
| +@cindex print list of auto-loaded Python scripts
|
| +@item info auto-load python-scripts [@var{regexp}]
|
| +Print the list of all Python scripts that @value{GDBN} auto-loaded.
|
|
|
| -Also printed is the list of scripts that were mentioned in
|
| +Also printed is the list of Python scripts that were mentioned in
|
| the @code{.debug_gdb_scripts} section and were not found
|
| -(@pxref{.debug_gdb_scripts section}).
|
| +(@pxref{dotdebug_gdb_scripts section}).
|
| This is useful because their names are not printed when @value{GDBN}
|
| tries to load them and fails. There may be many of them, and printing
|
| an error message for each one is problematic.
|
|
|
| -If @var{regexp} is supplied only scripts with matching names are printed.
|
| +If @var{regexp} is supplied only Python scripts with matching names are printed.
|
|
|
| Example:
|
|
|
| @smallexample
|
| -(gdb) info auto-load-scripts
|
| -Loaded Script
|
| -Yes py-section-script.py
|
| - full name: /tmp/py-section-script.py
|
| -Missing my-foo-pretty-printers.py
|
| +(gdb) info auto-load python-scripts
|
| +Loaded Script
|
| +Yes py-section-script.py
|
| + full name: /tmp/py-section-script.py
|
| +No my-foo-pretty-printers.py
|
| @end smallexample
|
| @end table
|
|
|
| @@ -24497,27 +25762,69 @@ When reading an auto-loaded file, @value{GDBN} sets the
|
| function (@pxref{Objfiles In Python}). This can be useful for
|
| registering objfile-specific pretty-printers.
|
|
|
| +@menu
|
| +* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
|
| +* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
|
| +* Which flavor to choose?::
|
| +@end menu
|
| +
|
| @node objfile-gdb.py file
|
| @subsubsection The @file{@var{objfile}-gdb.py} file
|
| @cindex @file{@var{objfile}-gdb.py}
|
|
|
| When a new object file is read, @value{GDBN} looks for
|
| -a file named @file{@var{objfile}-gdb.py},
|
| +a file named @file{@var{objfile}-gdb.py} (we call it @var{script-name} below),
|
| where @var{objfile} is the object file's real name, formed by ensuring
|
| that the file name is absolute, following all symlinks, and resolving
|
| @code{.} and @code{..} components. If this file exists and is
|
| readable, @value{GDBN} will evaluate it as a Python script.
|
|
|
| -If this file does not exist, and if the parameter
|
| -@code{debug-file-directory} is set (@pxref{Separate Debug Files}),
|
| -then @value{GDBN} will look for @var{real-name} in all of the
|
| -directories mentioned in the value of @code{debug-file-directory}.
|
| +If this file does not exist, then @value{GDBN} will look for
|
| +@var{script-name} file in all of the directories as specified below.
|
|
|
| -Finally, if this file does not exist, then @value{GDBN} will look for
|
| -a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where
|
| -@var{data-directory} is @value{GDBN}'s data directory (available via
|
| -@code{show data-directory}, @pxref{Data Files}), and @var{real-name}
|
| -is the object file's real name, as described above.
|
| +Note that loading of this script file also requires accordingly configured
|
| +@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
|
| +
|
| +For object files using @file{.exe} suffix @value{GDBN} tries to load first the
|
| +scripts normally according to its @file{.exe} filename. But if no scripts are
|
| +found @value{GDBN} also tries script filenames matching the object file without
|
| +its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it
|
| +is attempted on any platform. This makes the script filenames compatible
|
| +between Unix and MS-Windows hosts.
|
| +
|
| +@table @code
|
| +@anchor{set auto-load scripts-directory}
|
| +@kindex set auto-load scripts-directory
|
| +@item set auto-load scripts-directory @r{[}@var{directories}@r{]}
|
| +Control @value{GDBN} auto-loaded scripts location. Multiple directory entries
|
| +may be delimited by the host platform path separator in use
|
| +(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS).
|
| +
|
| +Each entry here needs to be covered also by the security setting
|
| +@code{set auto-load safe-path} (@pxref{set auto-load safe-path}).
|
| +
|
| +@anchor{with-auto-load-dir}
|
| +This variable defaults to @file{$debugdir:$datadir/auto-load}. The default
|
| +@code{set auto-load safe-path} value can be also overriden by @value{GDBN}
|
| +configuration option @option{--with-auto-load-dir}.
|
| +
|
| +Any reference to @file{$debugdir} will get replaced by
|
| +@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any
|
| +reference to @file{$datadir} will get replaced by @var{data-directory} which is
|
| +determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and
|
| +@file{$datadir} must be placed as a directory component --- either alone or
|
| +delimited by @file{/} or @file{\} directory separators, depending on the host
|
| +platform.
|
| +
|
| +The list of directories uses path separator (@samp{:} on GNU and Unix
|
| +systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly
|
| +to the @env{PATH} environment variable.
|
| +
|
| +@anchor{show auto-load scripts-directory}
|
| +@kindex show auto-load scripts-directory
|
| +@item show auto-load scripts-directory
|
| +Show @value{GDBN} auto-loaded scripts location.
|
| +@end table
|
|
|
| @value{GDBN} does not track which files it has already auto-loaded this way.
|
| @value{GDBN} will load the associated script every time the corresponding
|
| @@ -24525,7 +25832,7 @@ is the object file's real name, as described above.
|
| So your @file{-gdb.py} file should be careful to avoid errors if it
|
| is evaluated more than once.
|
|
|
| -@node .debug_gdb_scripts section
|
| +@node dotdebug_gdb_scripts section
|
| @subsubsection The @code{.debug_gdb_scripts} section
|
| @cindex @code{.debug_gdb_scripts} section
|
|
|
| @@ -24563,6 +25870,9 @@ DEFINE_GDB_SCRIPT ("my-app-scripts.py")
|
|
|
| The script name may include directories if desired.
|
|
|
| +Note that loading of this script file also requires accordingly configured
|
| +@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
|
| +
|
| If the macro is put in a header, any application or library
|
| using this header will get a reference to the specified script.
|
|
|
| @@ -24652,6 +25962,13 @@ Utility class for handling multiple printers, all recognized via
|
| regular expressions.
|
| @xref{Writing a Pretty-Printer}, for an example.
|
|
|
| +@item FlagEnumerationPrinter (@var{name})
|
| +A pretty-printer which handles printing of @code{enum} values. Unlike
|
| +@value{GDBN}'s built-in @code{enum} printing, this printer attempts to
|
| +work properly when there is some overlap between the enumeration
|
| +constants. @var{name} is the name of the printer and also the name of
|
| +the @code{enum} type to look up.
|
| +
|
| @item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
|
| Register @var{printer} with the pretty-printer list of @var{obj}.
|
| If @var{replace} is @code{True} then any existing copy of the printer
|
| @@ -24955,9 +26272,8 @@ commands in separate text windows. The TUI mode is supported only
|
| on platforms where a suitable version of the @code{curses} library
|
| is available.
|
|
|
| -@pindex @value{GDBTUI}
|
| The TUI mode is enabled by default when you invoke @value{GDBN} as
|
| -either @samp{@value{GDBTUI}} or @samp{@value{GDBP} -tui}.
|
| +@samp{@value{GDBP} -tui}.
|
| You can also switch in and out of TUI mode while @value{GDBN} runs by
|
| using various TUI commands and key bindings, such as @kbd{C-x C-a}.
|
| @xref{TUI Keys, ,TUI Key Bindings}.
|
| @@ -26220,8 +27536,9 @@ The inferior exited normally.
|
| A signal was received by the inferior.
|
| @item solib-event
|
| The inferior has stopped due to a library being loaded or unloaded.
|
| -This can only happen when @code{stop-on-solib-events} (@pxref{Files})
|
| -is set.
|
| +This can happen when @code{stop-on-solib-events} (@pxref{Files}) is
|
| +set or when a @code{catch load} or @code{catch unload} catchpoint is
|
| +in use (@pxref{Set Catchpoints}).
|
| @item fork
|
| The inferior has forked. This is reported when @code{catch fork}
|
| (@pxref{Set Catchpoints}) has been used.
|
| @@ -26778,7 +28095,7 @@ N.A.
|
| @smallexample
|
| -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
|
| [ -c @var{condition} ] [ -i @var{ignore-count} ]
|
| - [ -p @var{thread} ] [ @var{location} ]
|
| + [ -p @var{thread-id} ] [ @var{location} ]
|
| @end smallexample
|
|
|
| @noindent
|
| @@ -26801,10 +28118,6 @@ The possible optional parameters of this command are:
|
| Insert a temporary breakpoint.
|
| @item -h
|
| Insert a hardware breakpoint.
|
| -@item -c @var{condition}
|
| -Make the breakpoint conditional on @var{condition}.
|
| -@item -i @var{ignore-count}
|
| -Initialize the @var{ignore-count}.
|
| @item -f
|
| If @var{location} cannot be parsed (for example if it
|
| refers to unknown files or functions), create a pending
|
| @@ -26816,6 +28129,12 @@ Create a disabled breakpoint.
|
| @item -a
|
| Create a tracepoint. @xref{Tracepoints}. When this parameter
|
| is used together with @samp{-h}, a fast tracepoint is created.
|
| +@item -c @var{condition}
|
| +Make the breakpoint conditional on @var{condition}.
|
| +@item -i @var{ignore-count}
|
| +Initialize the @var{ignore-count}.
|
| +@item -p @var{thread-id}
|
| +Restrict the breakpoint to the specified @var{thread-id}.
|
| @end table
|
|
|
| @subsubheading Result
|
| @@ -26844,7 +28163,7 @@ Note: this format is open to change.
|
| @subsubheading @value{GDBN} Command
|
|
|
| The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
|
| -@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
|
| +@samp{hbreak}, and @samp{thbreak}. @c and @samp{rbreak}.
|
|
|
| @subsubheading Example
|
|
|
| @@ -26873,11 +28192,11 @@ 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"@}]@}
|
| (gdb)
|
| --break-insert -r foo.*
|
| -~int foo(int, int);
|
| -^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
|
| -"fullname="/home/foo/recursive2.c",line="11",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 (gdb)
|
| @end smallexample
|
|
|
| @subheading The @code{-break-list} Command
|
| @@ -28677,7 +29996,10 @@ will not be interesting.
|
|
|
| @item type
|
| The varobj's type. This is a string representation of the type, as
|
| -would be printed by the @value{GDBN} CLI.
|
| +would be printed by the @value{GDBN} CLI. If @samp{print object}
|
| +(@pxref{Print Settings, set print object}) is set to @code{on}, the
|
| +@emph{actual} (derived) type of the object is shown rather than the
|
| +@emph{declared} one.
|
|
|
| @item thread-id
|
| If a variable object is bound to a specific thread, then this is the
|
| @@ -28848,7 +30170,10 @@ Number of children this child has. For a dynamic varobj, this will be
|
| 0.
|
|
|
| @item type
|
| -The type of the child.
|
| +The type of the child. If @samp{print object}
|
| +(@pxref{Print Settings, set print object}) is set to @code{on}, the
|
| +@emph{actual} (derived) type of the object is shown rather than the
|
| +@emph{declared} one.
|
|
|
| @item value
|
| If values were requested, this is the value.
|
| @@ -29103,6 +30428,12 @@ This is only present if the varobj is still valid. If the type
|
| changed, then this will be the string @samp{true}; otherwise it will
|
| be @samp{false}.
|
|
|
| +When a varobj's type changes, its children are also likely to have
|
| +become incorrect. Therefore, the varobj's children are automatically
|
| +deleted when this attribute is @samp{true}. Also, the varobj's update
|
| +range, when set using the @code{-var-set-update-range} command, is
|
| +unset.
|
| +
|
| @item new_type
|
| If the varobj's type changed, then this field will be present and will
|
| hold the new type.
|
| @@ -31363,6 +32694,78 @@ and only if there is a corresponding executable file.
|
| @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...]
|
| @end smallexample
|
|
|
| +@subheading The @code{-info-os} Command
|
| +@findex -info-os
|
| +
|
| +@subsubheading Synopsis
|
| +
|
| +@smallexample
|
| +-info-os [ @var{type} ]
|
| +@end smallexample
|
| +
|
| +If no argument is supplied, the command returns a table of available
|
| +operating-system-specific information types. If one of these types is
|
| +supplied as an argument @var{type}, then the command returns a table
|
| +of data of that type.
|
| +
|
| +The types of information available depend on the target operating
|
| +system.
|
| +
|
| +@subsubheading @value{GDBN} Command
|
| +
|
| +The corresponding @value{GDBN} command is @samp{info os}.
|
| +
|
| +@subsubheading Example
|
| +
|
| +When run on a @sc{gnu}/Linux system, the output will look something
|
| +like this:
|
| +
|
| +@smallexample
|
| +@value{GDBP}
|
| +-info-os
|
| +^done,OSDataTable=@{nr_rows="9",nr_cols="3",
|
| +hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@},
|
| + @{width="10",alignment="-1",col_name="col1",colhdr="Description"@},
|
| + @{width="10",alignment="-1",col_name="col2",colhdr="Title"@}],
|
| +body=[item=@{col0="processes",col1="Listing of all processes",
|
| + col2="Processes"@},
|
| + item=@{col0="procgroups",col1="Listing of all process groups",
|
| + col2="Process groups"@},
|
| + item=@{col0="threads",col1="Listing of all threads",
|
| + col2="Threads"@},
|
| + item=@{col0="files",col1="Listing of all file descriptors",
|
| + col2="File descriptors"@},
|
| + item=@{col0="sockets",col1="Listing of all internet-domain sockets",
|
| + col2="Sockets"@},
|
| + item=@{col0="shm",col1="Listing of all shared-memory regions",
|
| + col2="Shared-memory regions"@},
|
| + item=@{col0="semaphores",col1="Listing of all semaphores",
|
| + col2="Semaphores"@},
|
| + item=@{col0="msg",col1="Listing of all message queues",
|
| + col2="Message queues"@},
|
| + item=@{col0="modules",col1="Listing of all loaded kernel modules",
|
| + col2="Kernel modules"@}]@}
|
| +@value{GDBP}
|
| +-info-os processes
|
| +^done,OSDataTable=@{nr_rows="190",nr_cols="4",
|
| +hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="pid"@},
|
| + @{width="10",alignment="-1",col_name="col1",colhdr="user"@},
|
| + @{width="10",alignment="-1",col_name="col2",colhdr="command"@},
|
| + @{width="10",alignment="-1",col_name="col3",colhdr="cores"@}],
|
| +body=[item=@{col0="1",col1="root",col2="/sbin/init",col3="0"@},
|
| + item=@{col0="2",col1="root",col2="[kthreadd]",col3="1"@},
|
| + item=@{col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"@},
|
| + ...
|
| + item=@{col0="26446",col1="stan",col2="bash",col3="0"@},
|
| + item=@{col0="28152",col1="stan",col2="bash",col3="1"@}]@}
|
| +(gdb)
|
| +@end smallexample
|
| +
|
| +(Note that the MI output here includes a @code{"Title"} column that
|
| +does not appear in command-line @code{info os}; this column is useful
|
| +for MI clients that want to enumerate the types of data, such as in a
|
| +popup menu, but is needless clutter on the command line, and
|
| +@code{info os} omits it.)
|
|
|
| @subheading The @code{-add-inferior} Command
|
| @findex -add-inferior
|
| @@ -32086,6 +33489,215 @@ frame and to write out the values of the registers in the previous
|
| frame. Both have a callback (@code{target_read}) to read bytes off the
|
| target's address space.
|
|
|
| +@node In-Process Agent
|
| +@chapter In-Process Agent
|
| +@cindex debugging agent
|
| +The traditional debugging model is conceptually low-speed, but works fine,
|
| +because most bugs can be reproduced in debugging-mode execution. However,
|
| +as multi-core or many-core processors are becoming mainstream, and
|
| +multi-threaded programs become more and more popular, there should be more
|
| +and more bugs that only manifest themselves at normal-mode execution, for
|
| +example, thread races, because debugger's interference with the program's
|
| +timing may conceal the bugs. On the other hand, in some applications,
|
| +it is not feasible for the debugger to interrupt the program's execution
|
| +long enough for the developer to learn anything helpful about its behavior.
|
| +If the program's correctness depends on its real-time behavior, delays
|
| +introduced by a debugger might cause the program to fail, even when the
|
| +code itself is correct. It is useful to be able to observe the program's
|
| +behavior without interrupting it.
|
| +
|
| +Therefore, traditional debugging model is too intrusive to reproduce
|
| +some bugs. In order to reduce the interference with the program, we can
|
| +reduce the number of operations performed by debugger. The
|
| +@dfn{In-Process Agent}, a shared library, is running within the same
|
| +process with inferior, and is able to perform some debugging operations
|
| +itself. As a result, debugger is only involved when necessary, and
|
| +performance of debugging can be improved accordingly. Note that
|
| +interference with program can be reduced but can't be removed completely,
|
| +because the in-process agent will still stop or slow down the program.
|
| +
|
| +The in-process agent can interpret and execute Agent Expressions
|
| +(@pxref{Agent Expressions}) during performing debugging operations. The
|
| +agent expressions can be used for different purposes, such as collecting
|
| +data in tracepoints, and condition evaluation in breakpoints.
|
| +
|
| +@anchor{Control Agent}
|
| +You can control whether the in-process agent is used as an aid for
|
| +debugging with the following commands:
|
| +
|
| +@table @code
|
| +@kindex set agent on
|
| +@item set agent on
|
| +Causes the in-process agent to perform some operations on behalf of the
|
| +debugger. Just which operations requested by the user will be done
|
| +by the in-process agent depends on the its capabilities. For example,
|
| +if you request to evaluate breakpoint conditions in the in-process agent,
|
| +and the in-process agent has such capability as well, then breakpoint
|
| +conditions will be evaluated in the in-process agent.
|
| +
|
| +@kindex set agent off
|
| +@item set agent off
|
| +Disables execution of debugging operations by the in-process agent. All
|
| +of the operations will be performed by @value{GDBN}.
|
| +
|
| +@kindex show agent
|
| +@item show agent
|
| +Display the current setting of execution of debugging operations by
|
| +the in-process agent.
|
| +@end table
|
| +
|
| +@menu
|
| +* In-Process Agent Protocol::
|
| +@end menu
|
| +
|
| +@node In-Process Agent Protocol
|
| +@section In-Process Agent Protocol
|
| +@cindex in-process agent protocol
|
| +
|
| +The in-process agent is able to communicate with both @value{GDBN} and
|
| +GDBserver (@pxref{In-Process Agent}). This section documents the protocol
|
| +used for communications between @value{GDBN} or GDBserver and the IPA.
|
| +In general, @value{GDBN} or GDBserver sends commands
|
| +(@pxref{IPA Protocol Commands}) and data to in-process agent, and then
|
| +in-process agent replies back with the return result of the command, or
|
| +some other information. The data sent to in-process agent is composed
|
| +of primitive data types, such as 4-byte or 8-byte type, and composite
|
| +types, which are called objects (@pxref{IPA Protocol Objects}).
|
| +
|
| +@menu
|
| +* IPA Protocol Objects::
|
| +* IPA Protocol Commands::
|
| +@end menu
|
| +
|
| +@node IPA Protocol Objects
|
| +@subsection IPA Protocol Objects
|
| +@cindex ipa protocol objects
|
| +
|
| +The commands sent to and results received from agent may contain some
|
| +complex data types called @dfn{objects}.
|
| +
|
| +The in-process agent is running on the same machine with @value{GDBN}
|
| +or GDBserver, so it doesn't have to handle as much differences between
|
| +two ends as remote protocol (@pxref{Remote Protocol}) tries to handle.
|
| +However, there are still some differences of two ends in two processes:
|
| +
|
| +@enumerate
|
| +@item
|
| +word size. On some 64-bit machines, @value{GDBN} or GDBserver can be
|
| +compiled as a 64-bit executable, while in-process agent is a 32-bit one.
|
| +@item
|
| +ABI. Some machines may have multiple types of ABI, @value{GDBN} or
|
| +GDBserver is compiled with one, and in-process agent is compiled with
|
| +the other one.
|
| +@end enumerate
|
| +
|
| +Here are the IPA Protocol Objects:
|
| +
|
| +@enumerate
|
| +@item
|
| +agent expression object. It represents an agent expression
|
| +(@pxref{Agent Expressions}).
|
| +@anchor{agent expression object}
|
| +@item
|
| +tracepoint action object. It represents a tracepoint action
|
| +(@pxref{Tracepoint Actions,,Tracepoint Action Lists}) to collect registers,
|
| +memory, static trace data and to evaluate expression.
|
| +@anchor{tracepoint action object}
|
| +@item
|
| +tracepoint object. It represents a tracepoint (@pxref{Tracepoints}).
|
| +@anchor{tracepoint object}
|
| +
|
| +@end enumerate
|
| +
|
| +The following table describes important attributes of each IPA protocol
|
| +object:
|
| +
|
| +@multitable @columnfractions .30 .20 .50
|
| +@headitem Name @tab Size @tab Description
|
| +@item @emph{agent expression object} @tab @tab
|
| +@item length @tab 4 @tab length of bytes code
|
| +@item byte code @tab @var{length} @tab contents of byte code
|
| +@item @emph{tracepoint action for collecting memory} @tab @tab
|
| +@item 'M' @tab 1 @tab type of tracepoint action
|
| +@item addr @tab 8 @tab if @var{basereg} is @samp{-1}, @var{addr} is the
|
| +address of the lowest byte to collect, otherwise @var{addr} is the offset
|
| +of @var{basereg} for memory collecting.
|
| +@item len @tab 8 @tab length of memory for collecting
|
| +@item basereg @tab 4 @tab the register number containing the starting
|
| +memory address for collecting.
|
| +@item @emph{tracepoint action for collecting registers} @tab @tab
|
| +@item 'R' @tab 1 @tab type of tracepoint action
|
| +@item @emph{tracepoint action for collecting static trace data} @tab @tab
|
| +@item 'L' @tab 1 @tab type of tracepoint action
|
| +@item @emph{tracepoint action for expression evaluation} @tab @tab
|
| +@item 'X' @tab 1 @tab type of tracepoint action
|
| +@item agent expression @tab length of @tab @ref{agent expression object}
|
| +@item @emph{tracepoint object} @tab @tab
|
| +@item number @tab 4 @tab number of tracepoint
|
| +@item address @tab 8 @tab address of tracepoint inserted on
|
| +@item type @tab 4 @tab type of tracepoint
|
| +@item enabled @tab 1 @tab enable or disable of tracepoint
|
| +@item step_count @tab 8 @tab step
|
| +@item pass_count @tab 8 @tab pass
|
| +@item numactions @tab 4 @tab number of tracepoint actions
|
| +@item hit count @tab 8 @tab hit count
|
| +@item trace frame usage @tab 8 @tab trace frame usage
|
| +@item compiled_cond @tab 8 @tab compiled condition
|
| +@item orig_size @tab 8 @tab orig size
|
| +@item condition @tab 4 if condition is NULL otherwise length of
|
| +@ref{agent expression object}
|
| +@tab zero if condition is NULL, otherwise is
|
| +@ref{agent expression object}
|
| +@item actions @tab variable
|
| +@tab numactions number of @ref{tracepoint action object}
|
| +@end multitable
|
| +
|
| +@node IPA Protocol Commands
|
| +@subsection IPA Protocol Commands
|
| +@cindex ipa protocol commands
|
| +
|
| +The spaces in each command are delimiters to ease reading this commands
|
| +specification. They don't exist in real commands.
|
| +
|
| +@table @samp
|
| +
|
| +@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head}
|
| +Installs a new fast tracepoint described by @var{tracepoint_object}
|
| +(@pxref{tracepoint object}). @var{gdb_jump_pad_head}, 8-byte long, is the
|
| +head of @dfn{jumppad}, which is used to jump to data collection routine
|
| +in IPA finally.
|
| +
|
| +Replies:
|
| +@table @samp
|
| +@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump}
|
| +@var{target_address} is address of tracepoint in the inferior.
|
| +@var{gdb_jump_pad_head} is updated head of jumppad. Both of
|
| +@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long.
|
| +@var{fjump} contains a sequence of instructions jump to jumppad entry.
|
| +@var{fjump_size}, 4-byte long, is the size of @var{fjump}.
|
| +@item E @var{NN}
|
| +for an error
|
| +
|
| +@end table
|
| +
|
| +@item qTfSTM
|
| +@xref{qTfSTM}.
|
| +@item qTsSTM
|
| +@xref{qTsSTM}.
|
| +@item qTSTMat
|
| +@xref{qTSTMat}.
|
| +@item probe_marker_at:@var{address}
|
| +Asks in-process agent to probe the marker at @var{address}.
|
| +
|
| +Replies:
|
| +@table @samp
|
| +@item E @var{NN}
|
| +for an error
|
| +@end table
|
| +@item unprobe_marker_at:@var{address}
|
| +Asks in-process agent to unprobe the marker at @var{address}.
|
| +@end table
|
| +
|
| @node GDB Bugs
|
| @chapter Reporting Bugs in @value{GDBN}
|
| @cindex bugs in @value{GDBN}
|
| @@ -32876,8 +34488,8 @@ messages, see @ref{Debugging Output}.)
|
| @table @code
|
| @kindex maint agent
|
| @kindex maint agent-eval
|
| -@item maint agent @var{expression}
|
| -@itemx maint agent-eval @var{expression}
|
| +@item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression}
|
| +@itemx maint agent-eval @r{[}-at @var{location}@r{,}@r{]} @var{expression}
|
| Translate the given @var{expression} into remote agent bytecodes.
|
| This command is useful for debugging the Agent Expression mechanism
|
| (@pxref{Agent Expressions}). The @samp{agent} version produces an
|
| @@ -32888,6 +34500,15 @@ globb} will include bytecodes to record four bytes of memory at each
|
| of the addresses of @code{globa} and @code{globb}, while discarding
|
| the result of the addition, while an evaluation expression will do the
|
| addition and return the sum.
|
| +If @code{-at} is given, generate remote agent bytecode for @var{location}.
|
| +If not, generate remote agent bytecode for current frame PC address.
|
| +
|
| +@kindex maint agent-printf
|
| +@item maint agent-printf @var{format},@var{expr},...
|
| +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}.
|
|
|
| @kindex maint info breakpoints
|
| @item @anchor{maint info breakpoints}maint info breakpoints
|
| @@ -33141,7 +34762,7 @@ If @var{regexp} is specified, only print scripts loaded by object files
|
| matching @var{regexp}.
|
| For each script, this command prints its name as specified in the objfile,
|
| and the full path if known.
|
| -@xref{.debug_gdb_scripts section}.
|
| +@xref{dotdebug_gdb_scripts section}.
|
|
|
| @kindex maint print statistics
|
| @cindex bcache statistics
|
| @@ -33960,6 +35581,12 @@ the corresponding stop reply should indicate that the thread has stopped with
|
| signal @samp{0}, regardless of whether the target uses some other signal
|
| as an implementation detail.
|
|
|
| +The stub must support @samp{vCont} if it reports support for
|
| +multiprocess extensions (@pxref{multiprocess extensions}). Note that in
|
| +this case @samp{vCont} actions can be specified to apply to all threads
|
| +in a process by using the @samp{p@var{pid}.-1} form of the
|
| +@var{thread-id}.
|
| +
|
| Reply:
|
| @xref{Stop Reply Packets}, for the reply specifications.
|
|
|
| @@ -33992,12 +35619,6 @@ together, and sends a @samp{vFlashDone} request after each group; the
|
| stub is allowed to delay erase operation until the @samp{vFlashDone}
|
| packet is received.
|
|
|
| -The stub must support @samp{vCont} if it reports support for
|
| -multiprocess extensions (@pxref{multiprocess extensions}). Note that in
|
| -this case @samp{vCont} actions can be specified to apply to all threads
|
| -in a process by using the @samp{p@var{pid}.-1} form of the
|
| -@var{thread-id}.
|
| -
|
| Reply:
|
| @table @samp
|
| @item OK
|
| @@ -34123,7 +35744,7 @@ avoid potential problems with duplicate packets, the operations should
|
| be implemented in an idempotent way.}
|
|
|
| @item z0,@var{addr},@var{kind}
|
| -@itemx Z0,@var{addr},@var{kind}
|
| +@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]}
|
| @cindex @samp{z0} packet
|
| @cindex @samp{Z0} packet
|
| Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
|
| @@ -34135,6 +35756,38 @@ A memory breakpoint is implemented by replacing the instruction at
|
| the breakpoint in bytes that should be inserted. E.g., the @sc{arm}
|
| and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
|
| architectures have additional meanings for @var{kind};
|
| +@var{cond_list} is an optional list of conditional expressions in bytecode
|
| +form that should be evaluated on the target's side. These are the
|
| +conditions that should be taken into consideration when deciding if
|
| +the breakpoint trigger should be reported back to @var{GDBN}.
|
| +
|
| +The @var{cond_list} parameter is comprised of a series of expressions,
|
| +concatenated without separators. Each expression has the following form:
|
| +
|
| +@table @samp
|
| +
|
| +@item X @var{len},@var{expr}
|
| +@var{len} is the length of the bytecode expression and @var{expr} is the
|
| +actual conditional expression in bytecode form.
|
| +
|
| +@end table
|
| +
|
| +The optional @var{cmd_list} parameter introduces commands that may be
|
| +run on the target, rather than being reported back to @value{GDBN}.
|
| +The parameter starts with a numeric flag @var{persist}; if the flag is
|
| +nonzero, then the breakpoint may remain active and the commands
|
| +continue to be run even when @value{GDBN} disconnects from the target.
|
| +Following this flag is a series of expressions concatenated with no
|
| +separators. Each expression has the following form:
|
| +
|
| +@table @samp
|
| +
|
| +@item X @var{len},@var{expr}
|
| +@var{len} is the length of the bytecode expression and @var{expr} is the
|
| +actual conditional expression in bytecode form.
|
| +
|
| +@end table
|
| +
|
| see @ref{Architecture-Specific Protocol Details}.
|
|
|
| @emph{Implementation note: It is possible for a target to copy or move
|
| @@ -34153,7 +35806,7 @@ for an error
|
| @end table
|
|
|
| @item z1,@var{addr},@var{kind}
|
| -@itemx Z1,@var{addr},@var{kind}
|
| +@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}
|
| @cindex @samp{z1} packet
|
| @cindex @samp{Z1} packet
|
| Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
|
| @@ -34161,7 +35814,7 @@ address @var{addr}.
|
|
|
| A hardware breakpoint is implemented using a mechanism that is not
|
| dependant on being able to modify the target's memory. @var{kind}
|
| -has the same meaning as in @samp{Z0} packets.
|
| +and @var{cond_list} have the same meaning as in @samp{Z0} packets.
|
|
|
| @emph{Implementation note: A hardware breakpoint is not affected by code
|
| movement.}
|
| @@ -34407,6 +36060,11 @@ Here are the currently defined query and set packets:
|
|
|
| @table @samp
|
|
|
| +@item QAgent:1
|
| +@item QAgent:0
|
| +Turn on or off the agent as a helper to perform some debugging operations
|
| +delegated from @value{GDBN} (@pxref{Control Agent}).
|
| +
|
| @item QAllow:@var{op}:@var{val}@dots{}
|
| @cindex @samp{QAllow} packet
|
| Specify which operations @value{GDBN} expects to request of the
|
| @@ -34695,6 +36353,48 @@ command (@pxref{Remote Configuration, set remote pass-signals}).
|
| This packet is not probed by default; the remote stub must request it,
|
| by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
|
|
|
| +@item QProgramSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
|
| +@cindex signals the inferior may see, remote request
|
| +@cindex @samp{QProgramSignals} packet
|
| +@anchor{QProgramSignals}
|
| +Each listed @var{signal} may be delivered to the inferior process.
|
| +Others should be silently discarded.
|
| +
|
| +In some cases, the remote stub may need to decide whether to deliver a
|
| +signal to the program or not without @value{GDBN} involvement. One
|
| +example of that is while detaching --- the program's threads may have
|
| +stopped for signals that haven't yet had a chance of being reported to
|
| +@value{GDBN}, and so the remote stub can use the signal list specified
|
| +by this packet to know whether to deliver or ignore those pending
|
| +signals.
|
| +
|
| +This does not influence whether to deliver a signal as requested by a
|
| +resumption packet (@pxref{vCont packet}).
|
| +
|
| +Signals are numbered identically to continue packets and stop replies
|
| +(@pxref{Stop Reply Packets}). Each @var{signal} list item should be
|
| +strictly greater than the previous item. Multiple
|
| +@samp{QProgramSignals} packets do not combine; any earlier
|
| +@samp{QProgramSignals} list is completely replaced by the new list.
|
| +
|
| +Reply:
|
| +@table @samp
|
| +@item OK
|
| +The request succeeded.
|
| +
|
| +@item E @var{nn}
|
| +An error occurred. @var{nn} are hex digits.
|
| +
|
| +@item
|
| +An empty reply indicates that @samp{QProgramSignals} is not supported
|
| +by the stub.
|
| +@end table
|
| +
|
| +Use of this packet is controlled by the @code{set remote program-signals}
|
| +command (@pxref{Remote Configuration, set remote program-signals}).
|
| +This packet is not probed by default; the remote stub must request it,
|
| +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
|
| +
|
| @item qRcmd,@var{command}
|
| @cindex execute remote command, remote request
|
| @cindex @samp{qRcmd} packet
|
| @@ -34941,6 +36641,11 @@ These are the currently defined stub features and their properties:
|
| @tab @samp{-}
|
| @tab Yes
|
|
|
| +@item @samp{qXfer:uib:read}
|
| +@tab No
|
| +@tab @samp{-}
|
| +@tab Yes
|
| +
|
| @item @samp{qXfer:fdpic:read}
|
| @tab No
|
| @tab @samp{-}
|
| @@ -34966,6 +36671,11 @@ These are the currently defined stub features and their properties:
|
| @tab @samp{-}
|
| @tab No
|
|
|
| +@item @samp{ConditionalBreakpoints}
|
| +@tab No
|
| +@tab @samp{-}
|
| +@tab No
|
| +
|
| @item @samp{ConditionalTracepoints}
|
| @tab No
|
| @tab @samp{-}
|
| @@ -34986,6 +36696,11 @@ These are the currently defined stub features and their properties:
|
| @tab @samp{-}
|
| @tab No
|
|
|
| +@item @samp{QAgent}
|
| +@tab No
|
| +@tab @samp{-}
|
| +@tab No
|
| +
|
| @item @samp{QAllow}
|
| @tab No
|
| @tab @samp{-}
|
| @@ -35006,6 +36721,11 @@ These are the currently defined stub features and their properties:
|
| @tab @samp{-}
|
| @tab No
|
|
|
| +@item @samp{BreakpointCommands}
|
| +@tab No
|
| +@tab @samp{-}
|
| +@tab No
|
| +
|
| @end multitable
|
|
|
| These are the currently defined stub features, in more detail:
|
| @@ -35070,6 +36790,10 @@ The remote stub understands the @samp{qXfer:threads:read} packet
|
| The remote stub understands the @samp{qXfer:traceframe-info:read}
|
| packet (@pxref{qXfer traceframe info read}).
|
|
|
| +@item qXfer:uib:read
|
| +The remote stub understands the @samp{qXfer:uib:read}
|
| +packet (@pxref{qXfer unwind info block}).
|
| +
|
| @item qXfer:fdpic:read
|
| The remote stub understands the @samp{qXfer:fdpic:read}
|
| packet (@pxref{qXfer fdpic loadmap read}).
|
| @@ -35103,6 +36827,11 @@ indicated it supports them in its @samp{qSupported} request.
|
| The remote stub understands the @samp{qXfer:osdata:read} packet
|
| ((@pxref{qXfer osdata read}).
|
|
|
| +@item ConditionalBreakpoints
|
| +The target accepts and implements evaluation of conditional expressions
|
| +defined for breakpoints. The target will only report breakpoint triggers
|
| +when such conditions are true (@pxref{Conditions, ,Break Conditions}).
|
| +
|
| @item ConditionalTracepoints
|
| The remote stub accepts and implements conditional expressions defined
|
| for tracepoints (@pxref{Tracepoint Conditions}).
|
| @@ -35119,6 +36848,9 @@ The remote stub accepts and implements the reverse step packet
|
| The remote stub understands the @samp{QTDPsrc} packet that supplies
|
| the source form of tracepoint definitions.
|
|
|
| +@item QAgent
|
| +The remote stub understands the @samp{QAgent} packet.
|
| +
|
| @item QAllow
|
| The remote stub understands the @samp{QAllow} packet.
|
|
|
| @@ -35143,6 +36875,11 @@ to be enabled and disabled while a trace experiment is running.
|
| The remote stub supports the @samp{tracenz} bytecode for collecting strings.
|
| See @ref{Bytecode Descriptions} for details about the bytecode.
|
|
|
| +@item BreakpointCommands
|
| +@cindex breakpoint commands, in remote protocol
|
| +The remote stub supports running a breakpoint's command list itself,
|
| +rather than reporting the hit to @value{GDBN}.
|
| +
|
| @end table
|
|
|
| @item qSymbol::
|
| @@ -35357,6 +37094,14 @@ Return a description of the current traceframe's contents.
|
| This packet is not probed by default; the remote stub must request it,
|
| by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
|
|
|
| +@item qXfer:uib:read:@var{pc}:@var{offset},@var{length}
|
| +@anchor{qXfer unwind info block}
|
| +
|
| +Return the unwind information block for @var{pc}. This packet is used
|
| +on OpenVMS/ia64 to ask the kernel unwind information.
|
| +
|
| +This packet is not probed by default.
|
| +
|
| @item qXfer:fdpic:read:@var{annex}:@var{offset},@var{length}
|
| @anchor{qXfer fdpic loadmap read}
|
| Read contents of @code{loadmap}s on the target system. The
|
| @@ -35498,9 +37243,21 @@ This section describes how the remote protocol is applied to specific
|
| target architectures. Also see @ref{Standard Target Features}, for
|
| details of XML target descriptions for each architecture.
|
|
|
| -@subsection ARM
|
| +@menu
|
| +* ARM-Specific Protocol Details::
|
| +* MIPS-Specific Protocol Details::
|
| +@end menu
|
| +
|
| +@node ARM-Specific Protocol Details
|
| +@subsection @acronym{ARM}-specific Protocol Details
|
| +
|
| +@menu
|
| +* ARM Breakpoint Kinds::
|
| +@end menu
|
|
|
| -@subsubsection Breakpoint Kinds
|
| +@node ARM Breakpoint Kinds
|
| +@subsubsection @acronym{ARM} Breakpoint Kinds
|
| +@cindex breakpoint kinds, @acronym{ARM}
|
|
|
| These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
|
|
|
| @@ -35513,37 +37270,65 @@ These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
|
| 32-bit Thumb mode (Thumb-2) breakpoint.
|
|
|
| @item 4
|
| -32-bit ARM mode breakpoint.
|
| +32-bit @acronym{ARM} mode breakpoint.
|
|
|
| @end table
|
|
|
| -@subsection MIPS
|
| +@node MIPS-Specific Protocol Details
|
| +@subsection @acronym{MIPS}-specific Protocol Details
|
| +
|
| +@menu
|
| +* MIPS Register packet Format::
|
| +* MIPS Breakpoint Kinds::
|
| +@end menu
|
|
|
| -@subsubsection Register Packet Format
|
| +@node MIPS Register packet Format
|
| +@subsubsection @acronym{MIPS} Register Packet Format
|
| +@cindex register packet format, @acronym{MIPS}
|
|
|
| The following @code{g}/@code{G} packets have previously been defined.
|
| In the below, some thirty-two bit registers are transferred as
|
| sixty-four bits. Those registers should be zero/sign extended (which?)
|
| to fill the space allocated. Register bytes are transferred in target
|
| byte order. The two nibbles within a register byte are transferred
|
| -most-significant - least-significant.
|
| +most-significant -- least-significant.
|
|
|
| @table @r
|
|
|
| @item MIPS32
|
| -
|
| All registers are transferred as thirty-two bit quantities in the order:
|
| 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
|
| registers; fsr; fir; fp.
|
|
|
| @item MIPS64
|
| -
|
| All registers are transferred as sixty-four bit quantities (including
|
| thirty-two bit registers such as @code{sr}). The ordering is the same
|
| as @code{MIPS32}.
|
|
|
| @end table
|
|
|
| +@node MIPS Breakpoint Kinds
|
| +@subsubsection @acronym{MIPS} Breakpoint Kinds
|
| +@cindex breakpoint kinds, @acronym{MIPS}
|
| +
|
| +These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
|
| +
|
| +@table @r
|
| +
|
| +@item 2
|
| +16-bit @acronym{MIPS16} mode breakpoint.
|
| +
|
| +@item 3
|
| +16-bit @acronym{microMIPS} mode breakpoint.
|
| +
|
| +@item 4
|
| +32-bit standard @acronym{MIPS} mode breakpoint.
|
| +
|
| +@item 5
|
| +32-bit @acronym{microMIPS} mode breakpoint.
|
| +
|
| +@end table
|
| +
|
| @node Tracepoint Packets
|
| @section Tracepoint Packets
|
| @cindex tracepoint packets
|
| @@ -35555,6 +37340,7 @@ tracepoints (@pxref{Tracepoints}).
|
| @table @samp
|
|
|
| @item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]}
|
| +@cindex @samp{QTDP} packet
|
| Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
|
| is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
|
| the tracepoint is disabled. @var{step} is the tracepoint's step
|
| @@ -35689,6 +37475,7 @@ target should simply create the trace state variables as they are
|
| mentioned in expressions.
|
|
|
| @item QTFrame:@var{n}
|
| +@cindex @samp{QTFrame} packet
|
| Select the @var{n}'th tracepoint frame from the buffer, and use the
|
| register and memory contents recorded there to answer subsequent
|
| request packets from @value{GDBN}.
|
| @@ -35731,6 +37518,7 @@ Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
|
| frame @emph{outside} the given range of addresses (exclusive).
|
|
|
| @item qTMinFTPILen
|
| +@cindex @samp{qTMinFTPILen} packet
|
| This packet requests the minimum length of instruction at which a fast
|
| tracepoint (@pxref{Set Tracepoints}) may be placed. For instance, on
|
| the 32-bit x86 architecture, it is possible to use a 4-byte jump, but
|
| @@ -35755,30 +37543,36 @@ An empty reply indicates that the request is not supported by the stub.
|
| @end table
|
|
|
| @item QTStart
|
| +@cindex @samp{QTStart} packet
|
| Begin the tracepoint experiment. Begin collecting data from
|
| tracepoint hits in the trace frame buffer. This packet supports the
|
| @samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate
|
| instruction reply packet}).
|
|
|
| @item QTStop
|
| +@cindex @samp{QTStop} packet
|
| End the tracepoint experiment. Stop collecting trace frames.
|
|
|
| @item QTEnable:@var{n}:@var{addr}
|
| @anchor{QTEnable}
|
| +@cindex @samp{QTEnable} packet
|
| Enable tracepoint @var{n} at address @var{addr} in a started tracepoint
|
| experiment. If the tracepoint was previously disabled, then collection
|
| of data from it will resume.
|
|
|
| @item QTDisable:@var{n}:@var{addr}
|
| @anchor{QTDisable}
|
| +@cindex @samp{QTDisable} packet
|
| Disable tracepoint @var{n} at address @var{addr} in a started tracepoint
|
| experiment. No more data will be collected from the tracepoint unless
|
| @samp{QTEnable:@var{n}:@var{addr}} is subsequently issued.
|
|
|
| @item QTinit
|
| +@cindex @samp{QTinit} packet
|
| Clear the table of tracepoints, and empty the trace frame buffer.
|
|
|
| @item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{}
|
| +@cindex @samp{QTro} packet
|
| Establish the given ranges of memory as ``transparent''. The stub
|
| will answer requests for these ranges from memory's current contents,
|
| if they were not collected as part of the tracepoint hit.
|
| @@ -35789,12 +37583,14 @@ still have the same contents they did when the tracepoint was hit, so
|
| there's no reason for the stub to refuse to provide their contents.
|
|
|
| @item QTDisconnected:@var{value}
|
| +@cindex @samp{QTDisconnected} packet
|
| Set the choice to what to do with the tracing run when @value{GDBN}
|
| disconnects from the target. A @var{value} of 1 directs the target to
|
| continue the tracing run, while 0 tells the target to stop tracing if
|
| @value{GDBN} is no longer in the picture.
|
|
|
| @item qTStatus
|
| +@cindex @samp{qTStatus} packet
|
| Ask the stub if there is a trace experiment running right now.
|
|
|
| The reply has the form:
|
| @@ -35914,7 +37710,9 @@ was not collected.
|
| @end table
|
|
|
| @item qTfP
|
| +@cindex @samp{qTfP} packet
|
| @itemx qTsP
|
| +@cindex @samp{qTsP} packet
|
| These packets request data about tracepoints that are being used by
|
| the target. @value{GDBN} sends @code{qTfP} to get the first piece
|
| of data, and multiple @code{qTsP} to get additional pieces. Replies
|
| @@ -35922,7 +37720,9 @@ to these packets generally take the form of the @code{QTDP} packets
|
| that define tracepoints. (FIXME add detailed syntax)
|
|
|
| @item qTfV
|
| +@cindex @samp{qTfV} packet
|
| @itemx qTsV
|
| +@cindex @samp{qTsV} packet
|
| These packets request data about trace state variables that are on the
|
| target. @value{GDBN} sends @code{qTfV} to get the first vari of data,
|
| and multiple @code{qTsV} to get additional variables. Replies to
|
| @@ -35931,6 +37731,10 @@ trace state variables.
|
|
|
| @item qTfSTM
|
| @itemx qTsSTM
|
| +@anchor{qTfSTM}
|
| +@anchor{qTsSTM}
|
| +@cindex @samp{qTfSTM} packet
|
| +@cindex @samp{qTsSTM} packet
|
| These packets request data about static tracepoint markers that exist
|
| in the target program. @value{GDBN} sends @code{qTfSTM} to get the
|
| first piece of data, and multiple @code{qTsSTM} to get additional
|
| @@ -35961,18 +37765,22 @@ query), until the target responds with @samp{l} (lower-case ell, for
|
| @dfn{last}).
|
|
|
| @item qTSTMat:@var{address}
|
| +@anchor{qTSTMat}
|
| +@cindex @samp{qTSTMat} packet
|
| This packets requests data about static tracepoint markers in the
|
| target program at @var{address}. Replies to this packet follow the
|
| syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static
|
| tracepoint markers.
|
|
|
| @item QTSave:@var{filename}
|
| +@cindex @samp{QTSave} packet
|
| This packet directs the target to save trace data to the file name
|
| @var{filename} in the target's filesystem. @var{filename} is encoded
|
| as a hex string; the interpretation of the file name (relative vs
|
| absolute, wild cards, etc) is up to the target.
|
|
|
| @item qTBuffer:@var{offset},@var{len}
|
| +@cindex @samp{qTBuffer} packet
|
| Return up to @var{len} bytes of the current contents of trace buffer,
|
| starting at @var{offset}. The trace buffer is treated as if it were
|
| a contiguous collection of traceframes, as per the trace file format.
|
| @@ -35986,6 +37794,7 @@ This packet directs the target to use a circular trace buffer if
|
| @var{value} is 1, or a linear buffer if the value is 0.
|
|
|
| @item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{}
|
| +@cindex @samp{QTNotes} packet
|
| This packet adds optional textual notes to the trace run. Allowable
|
| types include @code{user}, @code{notes}, and @code{tstop}, the
|
| @var{text} fields are arbitrary strings, hex-encoded.
|
| @@ -36126,6 +37935,16 @@ error occurred.
|
| Delete the file at @var{pathname} on the target. Return 0,
|
| or -1 if an error occurs. @var{pathname} is a string.
|
|
|
| +@item vFile:readlink: @var{filename}
|
| +Read value of symbolic link @var{filename} on the target. Return
|
| +the number of bytes read, or -1 if an error occurs.
|
| +
|
| +The data read should be returned as a binary attachment on success.
|
| +If zero bytes were read, the response should include an empty binary
|
| +attachment (i.e.@: a trailing semicolon). The return value is the
|
| +number of target bytes read; the binary attachment may be longer if
|
| +some characters were escaped.
|
| +
|
| @end table
|
|
|
| @node Interrupts
|
| @@ -37840,7 +39659,7 @@ The formal DTD for the traceframe info format is given below:
|
| One of the challenges of using @value{GDBN} to debug embedded systems
|
| is that there are so many minor variants of each processor
|
| architecture in use. It is common practice for vendors to start with
|
| -a standard processor core --- ARM, PowerPC, or MIPS, for example ---
|
| +a standard processor core --- ARM, PowerPC, or @acronym{MIPS}, for example ---
|
| and then make changes to adapt it to a particular market niche. Some
|
| architectures have hundreds of variants, available from dozens of
|
| vendors. This leads to a number of problems:
|
| @@ -38383,10 +40202,10 @@ The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
|
| describe a single register, @samp{orig_eax}.
|
|
|
| @node MIPS Features
|
| -@subsection MIPS Features
|
| -@cindex target descriptions, MIPS features
|
| +@subsection @acronym{MIPS} Features
|
| +@cindex target descriptions, @acronym{MIPS} features
|
|
|
| -The @samp{org.gnu.gdb.mips.cpu} feature is required for MIPS targets.
|
| +The @samp{org.gnu.gdb.mips.cpu} feature is required for @acronym{MIPS} targets.
|
| It should contain registers @samp{r0} through @samp{r31}, @samp{lo},
|
| @samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending
|
| on the target.
|
| @@ -38400,6 +40219,11 @@ it may be optional in a future version of @value{GDBN}. It should
|
| contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and
|
| @samp{fir}. They may be 32-bit or 64-bit depending on the target.
|
|
|
| +The @samp{org.gnu.gdb.mips.dsp} feature is optional. It should
|
| +contain registers @samp{hi1} through @samp{hi3}, @samp{lo1} through
|
| +@samp{lo3}, and @samp{dspctl}. The @samp{dspctl} register should
|
| +be 32-bit and the rest may be 32-bit or 64-bit depending on the target.
|
| +
|
| The @samp{org.gnu.gdb.mips.linux} feature is optional. It should
|
| contain a single register, @samp{restart}, which is used by the
|
| Linux kernel to control restartable syscalls.
|
| @@ -38601,8 +40425,12 @@ unless otherwise noted:
|
|
|
| @enumerate
|
| @item
|
| -The version number, currently 5. Versions 1, 2 and 3 are obsolete.
|
| -Version 4 differs by its hashing function.
|
| +The version number, currently 7. 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
|
| +by specifying @code{set use-deprecated-index-sections on}.
|
|
|
| @item
|
| The offset, from the start of the file, of the CU list.
|
| @@ -38677,7 +40505,7 @@ index version:
|
| @item Version 4
|
| The formula is @code{r = r * 67 + c - 113}.
|
|
|
| -@item Version 5
|
| +@item Versions 5 to 7
|
| The formula is @code{r = r * 67 + tolower (c) - 113}.
|
| @end table
|
|
|
| @@ -38701,26 +40529,121 @@ strings.
|
|
|
| A CU vector in the constant pool is a sequence of @code{offset_type}
|
| values. The first value is the number of CU indices in the vector.
|
| -Each subsequent value is the index of a CU in the CU list. This
|
| -element in the hash table is used to indicate which CUs define the
|
| -symbol.
|
| +Each subsequent value is the index and symbol attributes of a CU in
|
| +the CU list. This element in the hash table is used to indicate which
|
| +CUs define the symbol and how the symbol is used.
|
| +See below for the format of each CU index+attributes entry.
|
|
|
| A string in the constant pool is zero-terminated.
|
| @end enumerate
|
|
|
| +Attributes were added to CU index values in @code{.gdb_index} version 7.
|
| +If a symbol has multiple uses within a CU then there is one
|
| +CU index+attributes value for each use.
|
| +
|
| +The format of each CU index+attributes entry is as follows
|
| +(bit 0 = LSB):
|
| +
|
| +@table @asis
|
| +
|
| +@item Bits 0-23
|
| +This is the index of the CU in the CU list.
|
| +@item Bits 24-27
|
| +These bits are reserved for future purposes and must be zero.
|
| +@item Bits 28-30
|
| +The kind of the symbol in the CU.
|
| +
|
| +@table @asis
|
| +@item 0
|
| +This value is reserved and should not be used.
|
| +By reserving zero the full @code{offset_type} value is backwards compatible
|
| +with previous versions of the index.
|
| +@item 1
|
| +The symbol is a type.
|
| +@item 2
|
| +The symbol is a variable or an enum value.
|
| +@item 3
|
| +The symbol is a function.
|
| +@item 4
|
| +Any other kind of symbol.
|
| +@item 5,6,7
|
| +These values are reserved.
|
| +@end table
|
| +
|
| +@item Bit 31
|
| +This bit is zero if the value is global and one if it is static.
|
| +
|
| +The determination of whether a symbol is global or static is complicated.
|
| +The authorative reference is the file @file{dwarf2read.c} in
|
| +@value{GDBN} sources.
|
| +
|
| +@end table
|
| +
|
| +This pseudo-code describes the computation of a symbol's kind and
|
| +global/static attributes in the index.
|
| +
|
| +@smallexample
|
| +is_external = get_attribute (die, DW_AT_external);
|
| +language = get_attribute (cu_die, DW_AT_language);
|
| +switch (die->tag)
|
| + @{
|
| + case DW_TAG_typedef:
|
| + case DW_TAG_base_type:
|
| + case DW_TAG_subrange_type:
|
| + kind = TYPE;
|
| + is_static = 1;
|
| + break;
|
| + case DW_TAG_enumerator:
|
| + kind = VARIABLE;
|
| + is_static = (language != CPLUS && language != JAVA);
|
| + break;
|
| + case DW_TAG_subprogram:
|
| + kind = FUNCTION;
|
| + is_static = ! (is_external || language == ADA);
|
| + break;
|
| + case DW_TAG_constant:
|
| + kind = VARIABLE;
|
| + is_static = ! is_external;
|
| + break;
|
| + case DW_TAG_variable:
|
| + kind = VARIABLE;
|
| + is_static = ! is_external;
|
| + break;
|
| + case DW_TAG_namespace:
|
| + kind = TYPE;
|
| + is_static = 0;
|
| + break;
|
| + case DW_TAG_class_type:
|
| + case DW_TAG_interface_type:
|
| + case DW_TAG_structure_type:
|
| + case DW_TAG_union_type:
|
| + case DW_TAG_enumeration_type:
|
| + kind = TYPE;
|
| + is_static = (language != CPLUS && language != JAVA);
|
| + break;
|
| + default:
|
| + assert (0);
|
| + @}
|
| +@end smallexample
|
| +
|
| @include gpl.texi
|
|
|
| @node GNU Free Documentation License
|
| @appendix GNU Free Documentation License
|
| @include fdl.texi
|
|
|
| -@node Index
|
| -@unnumbered Index
|
| +@node Concept Index
|
| +@unnumbered Concept Index
|
|
|
| @printindex cp
|
|
|
| +@node Command and Variable Index
|
| +@unnumbered Command, Variable, and Function Index
|
| +
|
| +@printindex fn
|
| +
|
| @tex
|
| -% I think something like @colophon should be in texinfo. In the
|
| +% I think something like @@colophon should be in texinfo. In the
|
| % meantime:
|
| \long\def\colophon{\hbox to0pt{}\vfill
|
| \centerline{The body of this manual is set in}
|
| @@ -38732,7 +40655,7 @@ A string in the constant pool is zero-terminated.
|
| \centerline{{\sl\fontname\tensl\/}}
|
| \centerline{are used for emphasis.}\vfill}
|
| \page\colophon
|
| -% Blame: doc@cygnus.com, 1991.
|
| +% Blame: doc@@cygnus.com, 1991.
|
| @end tex
|
|
|
| @bye
|
|
|
Chromium Code Reviews
Issue 11969036:
Merge GDB 7.5.1 (Closed)
Base URL: http://git.chromium.org/native_client/nacl-gdb.git@master