Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(56)

Unified Diff: gdb/doc/gdb.texinfo

Side-by-side diff isn't available for this file because of its large size.
Issue 11969036: Merge GDB 7.5.1 (Closed) Base URL: http://git.chromium.org/native_client/nacl-gdb.git@master
Patch Set: Created 7 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
Download patch
« no previous file with comments | « gdb/doc/gdb.info-6 ('k') | gdb/doc/gdbint.info » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
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
« no previous file with comments | « gdb/doc/gdb.info-6 ('k') | gdb/doc/gdbint.info » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698