If this variable is set, @var{path} is a colon-separated list of
directories @value{GDBN} will use to search for @code{libthread_db}.
If you omit @var{path}, @samp{libthread-db-search-path} will be reset to
-its default value.
+its default value (@code{$sdir:$pdir} on @sc{gnu}/Linux and Solaris systems).
+Internally, the default value comes from the @code{LIBTHREAD_DB_SEARCH_PATH}
+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}. If that fails, @value{GDBN} will continue
-with default system shared library directories, and finally the directory
-from which @code{libpthread} was loaded in the inferior process.
+to find @code{libthread_db}.
+
+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.
+
+A special entry @samp{$pdir} for @samp{libthread-db-search-path}
+refers to the directory from which @code{libpthread}
+was loaded in the inferior process.
For any @code{libthread_db} library @value{GDBN} finds in above directories,
@value{GDBN} attempts to initialize it with the current inferior process.
If a line number is specified, the contents of that line will be
printed in hex.
+
+@item set dcache size @var{size}
+@cindex dcache size
+@kindex set dcache size
+Set maximum number of entries in dcache (dcache depth above).
+
+@item set dcache line-size @var{line-size}
+@cindex dcache line-size
+@kindex set dcache line-size
+Set number of bytes each dcache entry caches (dcache width above).
+Must be a power of 2.
+
+@item show dcache size
+@kindex show dcache size
+Show maximum number of dcache entries. See also @ref{Caching Remote Data, info dcache}.
+
+@item show dcache line-size
+@kindex show dcache line-size
+Show default size of dcache lines. See also @ref{Caching Remote Data, info dcache}.
+
@end table
@node Searching Memory
@kindex info macro
@cindex macro definition, showing
-@cindex definition, showing a macro's
+@cindex definition of a macro, showing
+@cindex macros, from debug info
@item info macro @var{macro}
-Show the definition of the macro named @var{macro}, and describe the
+Show the current definition of the named @var{macro}, and describe the
source location or compiler command-line where that definition was established.
+@kindex info macros
+@item info macros @var{linespec}
+Show all macro definitions that are in effect at the location specified
+by @var{linespec}, and describe the source location or compiler
+command-line where those definitions were established.
+
+@kindex info definitions
+@item info definitions @var{macro}
+Show all definitions of the named @var{macro} that are defined in the current
+compilation unit, and describe the source location or compiler command-line
+where those definitions were established.
+
@kindex macro define
@cindex user-defined macros
@cindex defining macros interactively
@kindex whatis
@item whatis [@var{arg}]
-Print the data type of @var{arg}, which can be either an expression or
-a data type. With no argument, print the data type of @code{$}, the
-last value in the value history. If @var{arg} is an expression, it is
-not actually evaluated, and any side-effecting operations (such as
-assignments or function calls) inside it do not take place. If
-@var{arg} is a type name, it may be the name of a type or typedef, or
-for C code it may have the form @samp{class @var{class-name}},
-@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
-@samp{enum @var{enum-tag}}.
-@xref{Expressions, ,Expressions}.
+Print the data type of @var{arg}, which can be either an expression
+or a name of a data type. With no argument, print the data type of
+@code{$}, the last value in the value history.
+
+If @var{arg} is an expression (@pxref{Expressions, ,Expressions}), it
+is not actually evaluated, and any side-effecting operations (such as
+assignments or function calls) inside it do not take place.
+
+If @var{arg} is a variable or an expression, @code{whatis} prints its
+literal type as it is used in the source code. If the type was
+defined using a @code{typedef}, @code{whatis} will @emph{not} print
+the data type underlying the @code{typedef}. If the type of the
+variable or the expression is a compound data type, such as
+@code{struct} or @code{class}, @code{whatis} never prints their
+fields or methods. It just prints the @code{struct}/@code{class}
+name (a.k.a.@: its @dfn{tag}). If you want to see the members of
+such a compound data type, use @code{ptype}.
+
+If @var{arg} is a type name that was defined using @code{typedef},
+@code{whatis} @dfn{unrolls} only one level of that @code{typedef}.
+Unrolling means that @code{whatis} will show the underlying type used
+in the @code{typedef} declaration of @var{arg}. However, if that
+underlying type is also a @code{typedef}, @code{whatis} will not
+unroll it.
+
+For C code, the type names may also have the form @samp{class
+@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
+@var{union-tag}} or @samp{enum @var{enum-tag}}.
@kindex ptype
@item ptype [@var{arg}]
detailed description of the type, instead of just the name of the type.
@xref{Expressions, ,Expressions}.
+Contrary to @code{whatis}, @code{ptype} always unrolls any
+@code{typedef}s in its argument declaration, whether the argument is
+a variable, expression, or a data type. This means that @code{ptype}
+of a variable or an expression will not print literally its type as
+present in the source code---use @code{whatis} for that. @code{typedef}s at
+the pointer or reference targets are also unrolled. Only @code{typedef}s of
+fields, methods and inner @code{class typedef}s of @code{struct}s,
+@code{class}es and @code{union}s are not unrolled even with @code{ptype}.
+
For example, for this variable declaration:
@smallexample
-struct complex @{double real; double imag;@} v;
+typedef double real_t;
+struct complex @{ real_t real; double imag; @};
+typedef struct complex complex_t;
+complex_t var;
+real_t *real_pointer_var;
@end smallexample
@noindent
@smallexample
@group
-(@value{GDBP}) whatis v
+(@value{GDBP}) whatis var
+type = complex_t
+(@value{GDBP}) ptype var
+type = struct complex @{
+ real_t real;
+ double imag;
+@}
+(@value{GDBP}) whatis complex_t
+type = struct complex
+(@value{GDBP}) whatis struct complex
type = struct complex
-(@value{GDBP}) ptype v
+(@value{GDBP}) ptype struct complex
type = struct complex @{
- double real;
+ real_t real;
double imag;
@}
+(@value{GDBP}) whatis real_pointer_var
+type = real_t *
+(@value{GDBP}) ptype real_pointer_var
+type = double *
@end group
@end smallexample
libthread-db-search-path}). If you omit @var{path},
@samp{libthread-db-search-path} will be reset to its default value.
+The special entry @samp{$pdir} for @samp{libthread-db-search-path} is
+not supported in @code{gdbserver}.
+
@item monitor exit
Tell gdbserver to exit immediately. This command should be followed by
@code{disconnect} to close the debugging session. @code{gdbserver} will
Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
watchpoints. A limit of -1, the default, is treated as unlimited.
+@cindex limit hardware watchpoints length
+@cindex remote target, limit watchpoints length
+@anchor{set remote hardware-watchpoint-length-limit}
+@item set remote hardware-watchpoint-length-limit @var{limit}
+Restrict @value{GDBN} to using @var{limit} bytes for the maximum length of
+a remote hardware watchpoint. A limit of -1, the default, is treated
+as unlimited.
+
+@item show remote hardware-watchpoint-length-limit
+Show the current limit (in bytes) of the maximum length of
+a remote hardware watchpoint.
+
@item set remote exec-file @var{filename}
@itemx show remote exec-file
@anchor{set remote exec-file}
Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
@end table
+Versions of @value{GDBN} that ship with Python scripting enabled have
+prompt extensions. The commands for interacting with these extensions
+are:
+
+@table @code
+@kindex set extended-prompt
+@item set extended-prompt @var{prompt}
+Set an extended prompt that allows for substitutions.
+@xref{gdb.prompt}, for a list of escape sequences that can be used for
+substitution. Any escape sequences specified as part of the prompt
+string are replaced with the corresponding strings each time the prompt
+is displayed.
+
+For example:
+
+@smallexample
+set extended-prompt Current working directory: \w (gdb)
+@end smallexample
+
+Note that when an extended-prompt is set, it takes control of the
+@var{prompt_hook} hook. @xref{prompt_hook}, for further information.
+
+@kindex show extended-prompt
+@item show extended-prompt
+Prints the extended prompt. Any escape sequences specified as part of
+the prompt string with @code{set extended-prompt}, are replaced with the
+corresponding strings each time the prompt is displayed.
+@end table
+
@node Editing
@section Command Editing
@cindex readline
module.
@item show debug aix-thread
Show the current state of AIX thread debugging info display.
+@item set debug check-physname
+@cindex physname
+Check the results of the ``physname'' computation. When reading DWARF
+debugging information for C@t{++}, @value{GDBN} attempts to compute
+each entity's name. @value{GDBN} can do this computation in two
+different ways, depending on exactly what information is present.
+When enabled, this setting causes @value{GDBN} to compute the names
+both ways and display any discrepancies.
+@item show debug check-physname
+Show the current state of ``physname'' checking.
@item set debug dwarf2-die
@cindex DWARF2 DIEs
Dump DWARF2 DIEs after they are read in.
is automatically added to the Python Search Path in order to allow
the Python interpreter to locate all scripts installed at this location.
+Additionally, @value{GDBN} commands and convenience functions which
+are written in Python and are located in the
+@file{@var{data-directory}/python/gdb/command} or
+@file{@var{data-directory}/python/gdb/function} directories are
+automatically imported when @value{GDBN} starts.
+
@menu
* Python Commands:: Accessing Python from @value{GDBN}.
* Python API:: Accessing @value{GDBN} from Python.
@kindex maint set python print-stack
@item maint set python print-stack
-By default, @value{GDBN} will print a stack trace when an error occurs
-in a Python script. This can be controlled using @code{maint set
-python print-stack}: if @code{on}, the default, then Python stack
-printing is enabled; if @code{off}, then Python stack printing is
+This command is now deprecated. Instead use @code{set python
+print-stack}
+
+@kindex set python print-stack
+@item set python print-stack
+By default, @value{GDBN} will not print a stack trace when an error
+occurs in a Python script. This can be controlled using @code{set
+python print-stack}: if @code{on}, then Python stack printing is
+enabled; if @code{off}, the default, then Python stack printing is
disabled.
@end table
@code{break} or @code{edit} commands do (@pxref{Specify Location}).
@end defun
+@defop Operation {@value{GDBN}} prompt_hook current_prompt
+@anchor{prompt_hook}
+
+If @var{prompt_hook} is callable, @value{GDBN} will call the method
+assigned to this operation before a prompt is displayed by
+@value{GDBN}.
+
+The parameter @code{current_prompt} contains the current @value{GDBN}
+prompt. This method must return a Python string, or @code{None}. If
+a string is returned, the @value{GDBN} prompt will be set to that
+string. If @code{None} is returned, @value{GDBN} will continue to use
+the current prompt.
+
+Some prompts cannot be substituted in @value{GDBN}. Secondary prompts
+such as those used by readline for command input, and annotation
+related prompts are prohibited from being changed.
+@end defop
+
@node Exception Handling
@subsubsection Exception Handling
@cindex python exceptions
@item bitpos
This attribute is not available for @code{static} fields (as in
C@t{++} or Java). For non-@code{static} fields, the value is the bit
-position of the field.
+position of the field. For @code{enum} fields, the value is the
+enumeration member's integer representation.
@item name
The name of the field, or @code{None} for anonymous fields.
@item events.exited
Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
-@code{events.ExitedEvent} has one attribute:
+@code{events.ExitedEvent} has one optional attribute. This attribute
+will exist only in the case that the inferior exited with some
+status.
@table @code
@defivar ExitedEvent exit_code
An integer representing the exit code which the inferior has returned.
A @code{gdb.Symbol} object has the following attributes:
@table @code
+@defivar Symbol type
+The type of the symbol or @code{None} if no type is recorded.
+This attribute is represented as a @code{gdb.Type} object.
+@xref{Types In Python}. This attribute is not writable.
+@end defivar
+
@defivar Symbol symtab
The symbol table in which the symbol appears. This attribute is
represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
The auto-loading feature is useful for supplying application-specific
debugging commands and scripts.
-Auto-loading can be enabled or disabled.
+Auto-loading can be enabled or disabled,
+and the list of auto-loaded scripts can be printed.
@table @code
@kindex set auto-load-scripts
@kindex show auto-load-scripts
@item show auto-load-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.
+
+Also printed is the list of scripts that were mentioned in
+the @code{.debug_gdb_scripts} section and were not found
+(@pxref{.debug_gdb_scripts section}).
+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.
+
+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
+@end smallexample
@end table
When reading an auto-loaded file, @value{GDBN} sets the
@subsection Python modules
@cindex python modules
-@value{GDBN} comes with a module to assist writing Python code.
+@value{GDBN} comes with several modules to assist writing Python code.
@menu
* gdb.printing:: Building and registering pretty-printers.
* gdb.types:: Utilities for working with types.
+* gdb.prompt:: Utilities for prompt value substitution.
@end menu
@node gdb.printing
Return a Python @code{dictionary} type produced from @var{enum_type}.
@end table
+@node gdb.prompt
+@subsubsection gdb.prompt
+@cindex gdb.prompt
+
+This module provides a method for prompt value-substitution.
+
+@table @code
+@item substitute_prompt (@var{string})
+Return @var{string} with escape sequences substituted by values. Some
+escape sequences take arguments. You can specify arguments inside
+``@{@}'' immediately following the escape sequence.
+
+The escape sequences you can pass to this function are:
+
+@table @code
+@item \\
+Substitute a backslash.
+@item \e
+Substitute an ESC character.
+@item \f
+Substitute the selected frame; an argument names a frame parameter.
+@item \n
+Substitute a newline.
+@item \p
+Substitute a parameter's value; the argument names the parameter.
+@item \r
+Substitute a carriage return.
+@item \t
+Substitute the selected thread; an argument names a thread parameter.
+@item \v
+Substitute the version of GDB.
+@item \w
+Substitute the current working directory.
+@item \[
+Begin a sequence of non-printing characters. These sequences are
+typically used with the ESC character, and are not counted in the string
+length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
+blue-colored ``(gdb)'' prompt where the length is five.
+@item \]
+End a sequence of non-printing characters.
+@end table
+
+For example:
+
+@smallexample
+substitute_prompt (``frame: \f,
+ print arguments: \p@{print frame-arguments@}'')
+@end smallexample
+
+@exdent will return the string:
+
+@smallexample
+"frame: main, print arguments: scalars"
+@end smallexample
+@end table
+
@node Interpreters
@chapter Command Interpreters
@cindex command interpreters
@value{GDBN} identifier of the thread group. The @var{pid} field
contains process identifier, specific to the operating system.
-@itemx =thread-group-exited,id="@var{id}"
+@item =thread-group-exited,id="@var{id}"[,exit-code="@var{code}"]
A thread group is no longer associated with a running program,
either because the program has exited, or because it was detached
from. The @var{id} field contains the @value{GDBN} identifier of the
-thread group.
+thread group. @var{code} is the exit code of the inferior; it exists
+only when the inferior exited with some code.
@item =thread-created,id="@var{id}",group-id="@var{gid}"
@itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
@item data-read-memory-bytes
Indicates presense of the @code{-data-read-memory-bytes} and the
@code{-data-write-memory-bytes} commands.
+@item breakpoint-notifications
+Indicates that changes to breakpoints and breakpoints created via the
+CLI will be announced via async records.
@end table
protocol. A newer @value{GDBN} can tell if a packet is supported based
on that response.
-A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
-@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
-optional.
+At a minimum, a stub is required to support the @samp{g} and @samp{G}
+commands for register access, and the @samp{m} and @samp{M} commands
+for memory access. Stubs that only control single-threaded targets
+can implement run control with the @samp{c} (continue), and @samp{s}
+(step) commands. Stubs that support multi-threading targets should
+support the @samp{vCont} command. All other commands are optional.
@node Packets
@section Packets
Continue. @var{addr} is address to resume. If @var{addr} is omitted,
resume at current address.
+This packet is deprecated for multi-threading support. @xref{vCont
+packet}.
+
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
Continue with signal @var{sig} (hex signal number). If
@samp{;@var{addr}} is omitted, resume at same address.
+This packet is deprecated for multi-threading support. @xref{vCont
+packet}.
+
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
for an error
@end table
-@item H @var{c} @var{thread-id}
+@item H @var{op} @var{thread-id}
@cindex @samp{H} packet
Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
-@samp{G}, et.al.). @var{c} depends on the operation to be performed: it
-should be @samp{c} for step and continue operations, @samp{g} for other
-operations. The thread designator @var{thread-id} has the format and
-interpretation described in @ref{thread-id syntax}.
+@samp{G}, et.al.). @var{op} depends on the operation to be performed:
+it should be @samp{c} for step and continue operations (note that this
+is deprecated, supporting the @samp{vCont} command is a better
+option), @samp{g} for other operations. The thread designator
+@var{thread-id} has the format and interpretation described in
+@ref{thread-id syntax}.
Reply:
@table @samp
Single step. @var{addr} is the address at which to resume. If
@var{addr} is omitted, resume at same address.
+This packet is deprecated for multi-threading support. @xref{vCont
+packet}.
+
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
Step with signal. This is analogous to the @samp{C} packet, but
requests a single-step, rather than a normal resumption of execution.
+This packet is deprecated for multi-threading support. @xref{vCont
+packet}.
+
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{}
@cindex @samp{vCont} packet
+@anchor{vCont packet}
Resume the inferior, specifying different actions for each thread.
If an action is specified with no @var{thread-id}, then it is applied to any
threads that don't have a specific action specified; if no default action is
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:fdpic:read}
+@tab No
+@tab @samp{-}
+@tab Yes
@item @samp{QNonStop}
@tab No
The remote stub understands the @samp{qXfer:traceframe-info:read}
packet (@pxref{qXfer traceframe info read}).
+@item qXfer:fdpic:read
+The remote stub understands the @samp{qXfer:fdpic:read}
+packet (@pxref{qXfer fdpic loadmap read}).
+
@item QNonStop
The remote stub understands the @samp{QNonStop} packet
(@pxref{QNonStop}).
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@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
+annex, either @samp{exec} or @samp{interp}, specifies which @code{loadmap},
+executable @code{loadmap} or interpreter @code{loadmap} to read.
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:osdata:read::@var{offset},@var{length}
@anchor{qXfer osdata read}
Access the target's @dfn{operating system information}.
@appendix Target Descriptions
@cindex target descriptions
-@strong{Warning:} target descriptions are still under active development,
-and the contents and format may change between @value{GDBN} releases.
-The format is expected to stabilize in the future.
-
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
@item regnum
The register's number. If omitted, a register's number is one greater
than that of the previous register (either in the current feature or in
-a preceeding feature); the first register in the target description
+a preceding feature); the first register in the target description
defaults to zero. This register number is used to read or write
the register; e.g.@: it is used in the remote @code{p} and @code{P}
packets, and registers appear in the @code{g} and @code{G} packets
* MIPS Features::
* M68K Features::
* PowerPC Features::
+* TIC6x Features::
@end menu
these to present registers @samp{ev0} through @samp{ev31} to the
user.
+@node TIC6x Features
+@subsection TMS320C6x Features
+@cindex target descriptions, TIC6x features
+@cindex target descriptions, TMS320C6x features
+The @samp{org.gnu.gdb.tic6x.core} feature is required for TMS320C6x
+targets. It should contain registers @samp{A0} through @samp{A15},
+registers @samp{B0} through @samp{B15}, @samp{CSR} and @samp{PC}.
+
+The @samp{org.gnu.gdb.tic6x.gp} feature is optional. It should
+contain registers @samp{A16} through @samp{A31} and @samp{B16}
+through @samp{B31}.
+
+The @samp{org.gnu.gdb.tic6x.c6xp} feature is optional. It should
+contain registers @samp{TSR}, @samp{ILC} and @samp{RILC}.
+
@node Operating System Information
@appendix Operating System Information
@cindex operating system information
projects / deliverable / binutils-gdb.git / blobdiff