@smallexample
(@value{GDBP}) p gdb_stdout.@kbd{M-?}
-magic to_delete to_fputs to_put to_rewind
-to_data to_flush to_isatty to_read to_write
+magic to_fputs to_rewind
+to_data to_isatty to_write
+to_delete to_put to_write_async_safe
+to_flush to_read
@end smallexample
@noindent
int *magic;
ui_file_flush_ftype *to_flush;
ui_file_write_ftype *to_write;
+ ui_file_write_async_safe_ftype *to_write_async_safe;
ui_file_fputs_ftype *to_fputs;
ui_file_read_ftype *to_read;
ui_file_delete_ftype *to_delete;
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
-an empty list.
+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
@item disable tracepoint @r{[}@var{num}@r{]}
Disable tracepoint @var{num}, or all tracepoints if no argument
@var{num} is given. A disabled tracepoint will have no effect during
-the next trace experiment, but it is not forgotten. You can re-enable
+a trace experiment, but it is not forgotten. You can re-enable
a disabled tracepoint using the @code{enable tracepoint} command.
+If the command is issued during a trace experiment and the debug target
+has support for disabling tracepoints during a trace experiment, then the
+change will be effective immediately. Otherwise, it will be applied to the
+next trace experiment.
@kindex enable tracepoint
@item enable tracepoint @r{[}@var{num}@r{]}
-Enable tracepoint @var{num}, or all tracepoints. The enabled
-tracepoints will become effective the next time a trace experiment is
-run.
+Enable tracepoint @var{num}, or all tracepoints. If this command is
+issued during a trace experiment and the debug target supports enabling
+tracepoints during a trace experiment, then the enabled tracepoints will
+become effective immediately. Otherwise, they will become effective the
+next time a trace experiment is run.
@end table
@node Tracepoint Passcounts
@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
When this command is issued, @var{path} is a colon-separated list of
directories to search for @code{libthread_db} (@pxref{Threads,,set
libthread-db-search-path}). If you omit @var{path},
-@samp{libthread-db-search-path} will be reset to an empty list.
+@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
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}
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.
Turns on or off debugging messages from the Linux LWP debug support.
@item show debug lin-lwp
Show the current state of Linux LWP debugging messages.
-@item set debug lin-lwp-async
-@cindex @sc{gnu}/Linux LWP async debug messages
-@cindex Linux lightweight processes
-Turns on or off debugging messages from the Linux LWP async debug support.
-@item show debug lin-lwp-async
-Show the current state of Linux LWP async debugging messages.
@item set debug observer
@cindex observer debugging info
Turns on or off display of @value{GDBN} observer debugging. This
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
+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 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
@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
@c The readline documentation is distributed with the readline code
@c and consists of the two following files:
-@c rluser.texinfo
-@c inc-hist.texinfo
+@c rluser.texi
+@c hsuser.texi
@c Use -I with makeinfo to point to the appropriate directory,
@c environment var TEXINPUTS with TeX.
@ifclear SYSTEM_READLINE
@include rluser.texi
-@include inc-hist.texinfo
+@include hsuser.texi
@end ifclear
@node In Memoriam
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 No
+@item @samp{EnableDisableTracepoints}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
@cindex static tracepoints, in remote protocol
The remote stub supports static tracepoints.
+@item EnableDisableTracepoints
+The remote stub supports the @samp{QTEnable} (@pxref{QTEnable}) and
+@samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints
+to be enabled and disabled while a trace experiment is running.
+
@end table
@item qSymbol::
@item qTsV
@itemx QTStart
@itemx QTStop
+@itemx QTEnable
+@itemx QTDisable
@itemx QTinit
@itemx QTro
@itemx qTStatus
@item QTStop
End the tracepoint experiment. Stop collecting trace frames.
+@item QTEnable:@var{n}:@var{addr}
+@anchor{QTEnable}
+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}
+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
Clear the table of tracepoints, and empty the trace frame buffer.
@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