@table @code
@item auto
Allow @value{GDBN} to choose a decoding style by inspecting your program.
+This is the default.
@item gnu
Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
-This is the default.
@item hp
Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
@var{pid} is the inferior process ID.
Note that this command is implemented only for some systems (as of
-this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
+this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390).
@end table
@node Character Sets
@code{whatis}, it does not print a detailed description; second, it
lists all source files where a type is defined.
+@kindex info type-printers
+@item info type-printers
+Versions of @value{GDBN} that ship with Python scripting enabled may
+have ``type printers'' available. When using @command{ptype} or
+@command{whatis}, these printers are consulted when the name of a type
+is needed. @xref{Type Printing API}, for more information on writing
+type printers.
+
+@code{info type-printers} displays all the available type printers.
+
+@kindex enable type-printer
+@kindex disable type-printer
+@item enable type-printer @var{name}@dots{}
+@item disable type-printer @var{name}@dots{}
+These commands can be used to enable or disable type printers.
+
@kindex info scope
@cindex local variables
@item info scope @var{location}
Alternatively, if @var{signal} is zero, continue execution without
giving a signal. This is useful when your program stopped on account of
-a signal and would ordinary see the signal when resumed with the
+a signal and would ordinarily see the signal when resumed with the
@code{continue} command; @samp{signal 0} causes it to resume without a
signal.
@menu
* Files:: Commands to specify files
* Separate Debug Files:: Debugging information in separate files
+* MiniDebugInfo:: Debugging information in a special section
* Index Files:: Index files speed up GDB
* Symbol Errors:: Errors reading symbol files
* Data Files:: GDB data files
@noindent
This computation does not apply to the ``build ID'' method.
+@node MiniDebugInfo
+@section Debugging information in a special section
+@cindex separate debug sections
+@cindex @samp{.gnu_debugdata} section
+
+Some systems ship pre-built executables and libraries that have a
+special @samp{.gnu_debugdata} section. This feature is called
+@dfn{MiniDebugInfo}. This section holds an LZMA-compressed object and
+is used to supply extra symbols for backtraces.
+
+The intent of this section is to provide extra minimal debugging
+information for use in simple backtraces. It is not intended to be a
+replacement for full separate debugging information (@pxref{Separate
+Debug Files}). The example below shows the intended use; however,
+@value{GDBN} does not currently put restrictions on what sort of
+debugging information might be included in the section.
+
+@value{GDBN} has support for this extension. If the section exists,
+then it is used provided that no other source of debugging information
+can be found, and that @value{GDBN} was configured with LZMA support.
+
+This section can be easily created using @command{objcopy} and other
+standard utilities:
+
+@smallexample
+# Extract the dynamic symbols from the main binary, there is no need
+# to also have these in the normal symbol table
+nm -D @var{binary} --format=posix --defined-only \
+ | awk '@{ print $1 @}' | sort > dynsyms
+
+# Extract all the text (i.e. function) symbols from the debuginfo .
+nm @var{binary} --format=posix --defined-only \
+ | awk '@{ if ($2 == "T" || $2 == "t") print $1 @}' \
+ | sort > funcsyms
+
+# Keep all the function symbols not already in the dynamic symbol
+# table.
+comm -13 dynsyms funcsyms > keep_symbols
+
+# Copy the full debuginfo, keeping only a minimal set of symbols and
+# removing some unnecessary sections.
+objcopy -S --remove-section .gdb_index --remove-section .comment \
+ --keep-symbols=keep_symbols @var{binary} mini_debuginfo
+
+# Inject the compressed data into the .gnu_debugdata section of the
+# original binary.
+xz mini_debuginfo
+objcopy --add-section .gnu_debugdata=mini_debuginfo.xz @var{binary}
+@end smallexample
@node Index Files
@section Index Files Speed Up @value{GDBN}
Many versions of SVR4 and compatible systems provide a facility called
@samp{/proc} that can be used to examine the image of a running
-process using file-system subroutines. If @value{GDBN} is configured
-for an operating system with this facility, the command @code{info
-proc} is available to report information about the process running
-your program, or about any process running on your system. @code{info
-proc} works only on SVR4 systems that include the @code{procfs} code.
-This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital
-Unix), Solaris, Irix, and Unixware, but not HP-UX, for example.
+process using file-system subroutines.
+
+If @value{GDBN} is configured for an operating system with this
+facility, the command @code{info proc} is available to report
+information about the process running your program, or about any
+process running on your system. This includes, as of this writing,
+@sc{gnu}/Linux, OSF/1 (Digital Unix), Solaris, and Irix, but
+not HP-UX, for example.
+
+This command may also work on core files that were created on a system
+that has the @samp{/proc} facility.
@table @code
@kindex info proc
needs to be present, or else @value{GDBN} will interpret the number as
a process ID rather than a thread ID).
+@item info proc cmdline
+@cindex info proc cmdline
+Show the original command line of the process. This command is
+specific to @sc{gnu}/Linux.
+
+@item info proc cwd
+@cindex info proc cwd
+Show the current working directory of the process. This command is
+specific to @sc{gnu}/Linux.
+
+@item info proc exe
+@cindex info proc exe
+Show the name of executable of the process. This command is specific
+to @sc{gnu}/Linux.
+
@item info proc mappings
@cindex memory address space mappings
Report the memory address space ranges accessible in the program, with
* Pretty Printing API:: Pretty-printing values.
* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
* Writing a Pretty-Printer:: Writing a Pretty-Printer.
+* Type Printing API:: Pretty-printing types.
* Inferiors In Python:: Python representation of inferiors (processes)
* Events In Python:: Listening for events from @value{GDBN}.
* Threads In Python:: Accessing inferior threads from Python.
bar
@end smallexample
+@node Type Printing API
+@subsubsection Type Printing API
+@cindex type printing API for Python
+
+@value{GDBN} provides a way for Python code to customize type display.
+This is mainly useful for substituting canonical typedef names for
+types.
+
+@cindex type printer
+A @dfn{type printer} is just a Python object conforming to a certain
+protocol. A simple base class implementing the protocol is provided;
+see @ref{gdb.types}. A type printer must supply at least:
+
+@defivar type_printer enabled
+A boolean which is True if the printer is enabled, and False
+otherwise. This is manipulated by the @code{enable type-printer}
+and @code{disable type-printer} commands.
+@end defivar
+
+@defivar type_printer name
+The name of the type printer. This must be a string. This is used by
+the @code{enable type-printer} and @code{disable type-printer}
+commands.
+@end defivar
+
+@defmethod type_printer instantiate (self)
+This is called by @value{GDBN} at the start of type-printing. It is
+only called if the type printer is enabled. This method must return a
+new object that supplies a @code{recognize} method, as described below.
+@end defmethod
+
+
+When displaying a type, say via the @code{ptype} command, @value{GDBN}
+will compute a list of type recognizers. This is done by iterating
+first over the per-objfile type printers (@pxref{Objfiles In Python}),
+followed by the per-progspace type printers (@pxref{Progspaces In
+Python}), and finally the global type printers.
+
+@value{GDBN} will call the @code{instantiate} method of each enabled
+type printer. If this method returns @code{None}, then the result is
+ignored; otherwise, it is appended to the list of recognizers.
+
+Then, when @value{GDBN} is going to display a type name, it iterates
+over the list of recognizers. For each one, it calls the recognition
+function, stopping if the function returns a non-@code{None} value.
+The recognition function is defined as:
+
+@defmethod type_recognizer recognize (self, type)
+If @var{type} is not recognized, return @code{None}. Otherwise,
+return a string which is to be printed as the name of @var{type}.
+@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
+Python}).
+@end defmethod
+
+@value{GDBN} uses this two-pass approach so that type printers can
+efficiently cache information without holding on to it too long. For
+example, it can be convenient to look up type information in a type
+printer and hold it for a recognizer's lifetime; if a single pass were
+done then type printers would have to make use of the event system in
+order to avoid holding information that could become stale as the
+inferior changed.
+
@node Inferiors In Python
@subsubsection Inferiors In Python
@cindex inferiors in Python
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{Inferior.write_memory} function.
+@code{Inferior.write_memory} function. In @code{Python} 3, the return
+value is a @code{memoryview} object.
@end defun
@findex Inferior.write_memory
information.
@end defvar
+@defvar Progspace.type_printers
+The @code{type_printers} attribute is a list of type printer objects.
+@xref{Type Printing API}, for more information.
+@end defvar
+
@node Objfiles In Python
@subsubsection Objfiles In Python
information.
@end defvar
+@defvar Objfile.type_printers
+The @code{type_printers} attribute is a list of type printer objects.
+@xref{Type Printing API}, for more information.
+@end defvar
+
A @code{gdb.Objfile} object has the following methods:
@defun Objfile.is_valid ()
@cindex gdb.types
This module provides a collection of utilities for working with
-@code{gdb.Types} objects.
+@code{gdb.Type} objects.
@table @code
@item get_basic_type (@var{type})
@{['a', 'b0', 'b1']@}
@end smallexample
+@item get_type_recognizers ()
+Return a list of the enabled type recognizers for the current context.
+This is called by @value{GDBN} during the type-printing process
+(@pxref{Type Printing API}).
+
+@item apply_type_recognizers (recognizers, type_obj)
+Apply the type recognizers, @var{recognizers}, to the type object
+@var{type_obj}. If any recognizer returns a string, return that
+string. Otherwise, return @code{None}. This is called by
+@value{GDBN} during the type-printing process (@pxref{Type Printing
+API}).
+
+@item register_type_printer (locus, printer)
+This is a convenience function to register a type printer.
+@var{printer} is the type printer to register. It must implement the
+type printer protocol. @var{locus} is either a @code{gdb.Objfile}, in
+which case the printer is registered with that objfile; a
+@code{gdb.Progspace}, in which case the printer is registered with
+that progspace; or @code{None}, in which case the printer is
+registered globally.
+
+@item TypePrinter
+This is a base class that implements the type printer protocol. Type
+printers are encouraged, but not required, to derive from this class.
+It defines a constructor:
+
+@defmethod TypePrinter __init__ (self, name)
+Initialize the type printer with the given name. The new printer
+starts in the enabled state.
+@end defmethod
+
@end table
@node gdb.prompt
* GDB/MI Simple Examples::
* GDB/MI Command Description Format::
* GDB/MI Breakpoint Commands::
+* GDB/MI Catchpoint Commands::
* GDB/MI Program Context::
* GDB/MI Thread Commands::
* GDB/MI Ada Tasking Commands::
(gdb)
@end smallexample
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Catchpoint Commands
+@section @sc{gdb/mi} Catchpoint Commands
+
+This section documents @sc{gdb/mi} commands for manipulating
+catchpoints.
+
+@subheading The @code{-catch-load} Command
+@findex -catch-load
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-load [ -t ] [ -d ] @var{regexp}
+@end smallexample
+
+Add a catchpoint for library load events. If the @samp{-t} option is used,
+the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting
+Breakpoints}). If the @samp{-d} option is used, the catchpoint is created
+in a disabled state. The @samp{regexp} argument is a regular
+expression used to match the name of the loaded library.
+
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch load}.
+
+@subsubheading Example
+
+@smallexample
+-catch-load -t foo.so
+^done,bkpt=@{number="1",type="catchpoint",disp="del",enabled="y",
+what="load of library matching foo.so",times="0"@}
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-catch-unload} Command
+@findex -catch-unload
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-unload [ -t ] [ -d ] @var{regexp}
+@end smallexample
+
+Add a catchpoint for library unload events. If the @samp{-t} option is
+used, the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting
+Breakpoints}). If the @samp{-d} option is used, the catchpoint is
+created in a disabled state. The @samp{regexp} argument is a regular
+expression used to match the name of the unloaded library.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch unload}.
+
+@subsubheading Example
+
+@smallexample
+-catch-unload -d bar.so
+^done,bkpt=@{number="2",type="catchpoint",disp="keep",enabled="n",
+what="load of library matching bar.so",times="0"@}
+(gdb)
+@end smallexample
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Context
@section @sc{gdb/mi} Program Context
@smallexample
-data-write-memory-bytes @var{address} @var{contents}
+ -data-write-memory-bytes @var{address} @var{contents} @r{[}@var{count}@r{]}
@end smallexample
@noindent
@item @var{contents}
The hex-encoded bytes to write.
+@item @var{count}
+Optional argument indicating the number of bytes to be written. If @var{count}
+is greater than @var{contents}' length, @value{GDBN} will repeatedly
+write @var{contents} until it fills @var{count} bytes.
+
@end table
@subsubheading @value{GDBN} Command
(gdb)
@end smallexample
+@smallexample
+(gdb)
+-data-write-memory-bytes &a "aabbccdd" 16e
+^done
+(gdb)
+@end smallexample
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Tracepoint Commands
wherever @value{GDBN} is installed.
@end itemize
+If the configured location of the system-wide init file (as given by the
+@option{--with-system-gdbinit} option at configure time) is in the
+data-directory (as specified by @option{--with-gdb-datadir} at configure
+time) or in one of its subdirectories, then @value{GDBN} will look for the
+system-wide init file in the directory specified by the
+@option{--data-directory} command-line option.
+Note that the system-wide init file is only read once, during @value{GDBN}
+initialization. If the data-directory is changed after @value{GDBN} has
+started with the @code{set data-directory} command, the file will not be
+reread.
+
@node Maintenance Commands
@appendix Maintenance Commands
@cindex maintenance commands
projects / deliverable / binutils-gdb.git / blobdiff