@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.
@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
@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
* 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
@menu
* Free Software:: Freely redistributable software
+* Free Documentation:: Free Software Needs Free Documentation
* Contributors:: Contributors to GDB
@end menu
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
@itemx -ix @var{file}
@cindex @code{--init-command}
@cindex @code{-ix}
-Execute commands from file @var{file} before loading gdbinit files or the
-inferior.
+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 gdbinit files or the
-inferior.
+Execute a single @value{GDBN} command before loading the inferior (but
+after loading gdbinit files).
@xref{Startup}.
@item -directory @var{directory}
This option causes @value{GDBN} to print its version number and
no-warranty blurb, and exit.
-@item -use-deprecated-index-sections
-@cindex @code{--use-deprecated-index-sections}
-This option causes @value{GDBN} to read and use deprecated
-@samp{.gdb_index} sections from symbol files. This can speed up
-startup, but may result in some functionality being lost.
-@xref{Index Section Format}.
-
@end table
@node Startup
Sets up the command interpreter as specified by the command line
(@pxref{Mode Options, interpreter}).
-@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
@cindex init file
Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was
@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.
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
* 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
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
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''
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}
@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}.
@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
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
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
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
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
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
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
@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,
@menu
* C:: C and C@t{++}
* D:: D
+* Go:: Go
* Objective-C:: Objective-C
* OpenCL C:: OpenCL C
* Fortran:: Fortran
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
@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
@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.)
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:
@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
--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.
@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
* 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
@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
+@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
@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
@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
@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
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:
@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.
@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}
@menu
* i386::
-* A29K::
* Alpha::
* MIPS::
* HPPA:: HP PA architecture
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
@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
@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
@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
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.
(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.
+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 /usr/local.
+ 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}
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.
+local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been
+ loaded.
python-scripts:
Loaded Script
Yes /home/user/gdb/gdb-gdb.py
@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}.
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
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
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}).
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:
$ ./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 "/usr/local".
+ 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 "/usr/local".
+ 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 @var{directories}
+@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.
-The list of directories uses directory separator (@samp{:} on GNU and Unix
+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.
@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 directory separator in use.
+host platform path separator in use.
@end table
-Setting this variable to an empty string disables this security protection.
+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
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"}
+@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"}
+@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.
also suppresses any such warning messages:
@table @asis
-@item @kbd{gdb -iex "set auto-load no"}
+@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}
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
@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
* 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
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
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
stack.
A @code{gdb.Block} is iterable. The iterator returns the symbols
-(@pxref{Symbols In Python}) local to the block.
+(@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:
@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
@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
@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.
+
+Note that loading of this script file also requires accordingly configured
+@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
+
+@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}.
-Finally, if this file does not exist, then @value{GDBN} will look for
-a file named @file{@var{data-directory}/auto-load/@var{real-name}}, where
-@var{data-directory} is @value{GDBN}'s data directory (available via
-@code{show data-directory}, @pxref{Data Files}), and @var{real-name}
-is the object file's real name, as described above.
+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
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.
@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
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
@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
@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
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
@{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
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}
@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
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
@end table
+@kindex maint info bfds
+@item maint info bfds
+This prints information about each @code{bfd} object that is known to
+@value{GDBN}. @xref{Top, , BFD, bfd, The Binary File Descriptor Library}.
+
@kindex set displaced-stepping
@kindex show displaced-stepping
@cindex displaced stepping support
be implemented in an idempotent way.}
@item z0,@var{addr},@var{kind}
-@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}
+@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
@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
@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:
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::
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.
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
-@subsubsection Register Packet Format
+@menu
+* MIPS Register packet Format::
+* MIPS Breakpoint Kinds::
+@end menu
+
+@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
@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
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}.
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
@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.
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:
@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
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
@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
@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.
@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.
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:
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.
@enumerate
@item
-The version number, currently 6. Versions 1, 2 and 3 are obsolete.
+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. @value{GDBN} will only read version 4 and 5 indices
-if the @code{--use-deprecated-index-sections} option is used.
+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.
@item Version 4
The formula is @code{r = r * 67 + c - 113}.
-@item Versions 5 and 6
+@item Versions 5 to 7
The formula is @code{r = r * 67 + tolower (c) - 113}.
@end table
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}
\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
projects / deliverable / binutils-gdb.git / blobdiff