| Index: gdb/doc/gdb.info-4
|
| diff --git a/gdb/doc/gdb.info-4 b/gdb/doc/gdb.info-4
|
| index ed5c1bc7af2e18ecc5bc77e5273bdb57d9426190..e53a5c0ab4768fe00dd587898ac97d12d3735cea 100644
|
| --- a/gdb/doc/gdb.info-4
|
| +++ b/gdb/doc/gdb.info-4
|
| @@ -7,7 +7,7 @@ END-INFO-DIR-ENTRY
|
|
|
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
| -2010 Free Software Foundation, Inc.
|
| +2010 2011, 2012 Free Software Foundation, Inc.
|
|
|
| Permission is granted to copy, distribute and/or modify this document
|
| under the terms of the GNU Free Documentation License, Version 1.3 or
|
| @@ -23,11 +23,11 @@ developing GNU and promoting software freedom."
|
| This file documents the GNU debugger GDB.
|
|
|
| This is the Tenth Edition, of `Debugging with GDB: the GNU
|
| -Source-Level Debugger' for GDB (GDB) Version 7.4.1.
|
| +Source-Level Debugger' for GDB (GDB) Version 7.5.1.
|
|
|
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
| -2010 Free Software Foundation, Inc.
|
| +2010 2011, 2012 Free Software Foundation, Inc.
|
|
|
| Permission is granted to copy, distribute and/or modify this document
|
| under the terms of the GNU Free Documentation License, Version 1.3 or
|
| @@ -41,6 +41,1275 @@ this GNU Manual. Buying copies from GNU Press supports the FSF in
|
| developing GNU and promoting software freedom."
|
|
|
|
|
| +File: gdb.info, Node: objfile-gdb.py file, Next: dotdebug_gdb_scripts section, Up: Python Auto-loading
|
| +
|
| +23.2.3.1 The `OBJFILE-gdb.py' file
|
| +..................................
|
| +
|
| +When a new object file is read, GDB looks for a file named
|
| +`OBJFILE-gdb.py' (we call it SCRIPT-NAME below), where OBJFILE is the
|
| +object file's real name, formed by ensuring that the file name is
|
| +absolute, following all symlinks, and resolving `.' and `..'
|
| +components. If this file exists and is readable, GDB will evaluate it
|
| +as a Python script.
|
| +
|
| + If this file does not exist, then GDB will look for SCRIPT-NAME file
|
| +in all of the directories as specified below.
|
| +
|
| + Note that loading of this script file also requires accordingly
|
| +configured `auto-load safe-path' (*note Auto-loading safe path::).
|
| +
|
| + For object files using `.exe' suffix GDB tries to load first the
|
| +scripts normally according to its `.exe' filename. But if no scripts
|
| +are found GDB also tries script filenames matching the object file
|
| +without its `.exe' suffix. This `.exe' stripping is case insensitive
|
| +and it is attempted on any platform. This makes the script filenames
|
| +compatible between Unix and MS-Windows hosts.
|
| +
|
| +`set auto-load scripts-directory [DIRECTORIES]'
|
| + Control GDB auto-loaded scripts location. Multiple directory
|
| + entries may be delimited by the host platform path separator in use
|
| + (`:' on Unix, `;' on MS-Windows and MS-DOS).
|
| +
|
| + Each entry here needs to be covered also by the security setting
|
| + `set auto-load safe-path' (*note set auto-load safe-path::).
|
| +
|
| + This variable defaults to `$debugdir:$datadir/auto-load'. The
|
| + default `set auto-load safe-path' value can be also overriden by
|
| + GDB configuration option `--with-auto-load-dir'.
|
| +
|
| + Any reference to `$debugdir' will get replaced by
|
| + DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any
|
| + reference to `$datadir' will get replaced by DATA-DIRECTORY which
|
| + is determined at GDB startup (*note Data Files::). `$debugdir' and
|
| + `$datadir' must be placed as a directory component -- either alone
|
| + or delimited by `/' or `\' directory separators, depending on the
|
| + host platform.
|
| +
|
| + The list of directories uses path separator (`:' on GNU and Unix
|
| + systems, `;' on MS-Windows and MS-DOS) to separate directories,
|
| + similarly to the `PATH' environment variable.
|
| +
|
| +`show auto-load scripts-directory'
|
| + Show GDB auto-loaded scripts location.
|
| +
|
| + GDB does not track which files it has already auto-loaded this way.
|
| +GDB will load the associated script every time the corresponding
|
| +OBJFILE is opened. So your `-gdb.py' file should be careful to avoid
|
| +errors if it is evaluated more than once.
|
| +
|
| +
|
| +File: gdb.info, Node: dotdebug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdb.py file, Up: Python Auto-loading
|
| +
|
| +23.2.3.2 The `.debug_gdb_scripts' section
|
| +.........................................
|
| +
|
| +For systems using file formats like ELF and COFF, when GDB loads a new
|
| +object file it will look for a special section named
|
| +`.debug_gdb_scripts'. If this section exists, its contents is a list
|
| +of names of scripts to load.
|
| +
|
| + GDB will look for each specified script file first in the current
|
| +directory and then along the source search path (*note Specifying
|
| +Source Directories: Source Path.), except that `$cdir' is not searched,
|
| +since the compilation directory is not relevant to scripts.
|
| +
|
| + Entries can be placed in section `.debug_gdb_scripts' with, for
|
| +example, this GCC macro:
|
| +
|
| + /* Note: The "MS" section flags are to remove duplicates. */
|
| + #define DEFINE_GDB_SCRIPT(script_name) \
|
| + asm("\
|
| + .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\
|
| + .byte 1\n\
|
| + .asciz \"" script_name "\"\n\
|
| + .popsection \n\
|
| + ");
|
| +
|
| +Then one can reference the macro in a header or source file like this:
|
| +
|
| + DEFINE_GDB_SCRIPT ("my-app-scripts.py")
|
| +
|
| + The script name may include directories if desired.
|
| +
|
| + Note that loading of this script file also requires accordingly
|
| +configured `auto-load safe-path' (*note 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.
|
| +
|
| +
|
| +File: gdb.info, Node: Which flavor to choose?, Prev: dotdebug_gdb_scripts section, Up: Python Auto-loading
|
| +
|
| +23.2.3.3 Which flavor to choose?
|
| +................................
|
| +
|
| +Given the multiple ways of auto-loading Python scripts, it might not
|
| +always be clear which one to choose. This section provides some
|
| +guidance.
|
| +
|
| + Benefits of the `-gdb.py' way:
|
| +
|
| + * Can be used with file formats that don't support multiple sections.
|
| +
|
| + * Ease of finding scripts for public libraries.
|
| +
|
| + Scripts specified in the `.debug_gdb_scripts' section are searched
|
| + for in the source search path. For publicly installed libraries,
|
| + e.g., `libstdc++', there typically isn't a source directory in
|
| + which to find the script.
|
| +
|
| + * Doesn't require source code additions.
|
| +
|
| + Benefits of the `.debug_gdb_scripts' way:
|
| +
|
| + * Works with static linking.
|
| +
|
| + Scripts for libraries done the `-gdb.py' way require an objfile to
|
| + trigger their loading. When an application is statically linked
|
| + the only objfile available is the executable, and it is cumbersome
|
| + to attach all the scripts from all the input libraries to the
|
| + executable's `-gdb.py' script.
|
| +
|
| + * Works with classes that are entirely inlined.
|
| +
|
| + Some classes can be entirely inlined, and thus there may not be an
|
| + associated shared library to attach a `-gdb.py' script to.
|
| +
|
| + * Scripts needn't be copied out of the source tree.
|
| +
|
| + In some circumstances, apps can be built out of large collections
|
| + of internal libraries, and the build infrastructure necessary to
|
| + install the `-gdb.py' scripts in a place where GDB can find them is
|
| + cumbersome. It may be easier to specify the scripts in the
|
| + `.debug_gdb_scripts' section as relative paths, and add a path to
|
| + the top of the source tree to the source search path.
|
| +
|
| +
|
| +File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python
|
| +
|
| +23.2.4 Python modules
|
| +---------------------
|
| +
|
| +GDB 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.
|
| +
|
| +
|
| +File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules
|
| +
|
| +23.2.4.1 gdb.printing
|
| +.....................
|
| +
|
| +This module provides a collection of utilities for working with
|
| +pretty-printers.
|
| +
|
| +`PrettyPrinter (NAME, SUBPRINTERS=None)'
|
| + This class specifies the API that makes `info pretty-printer',
|
| + `enable pretty-printer' and `disable pretty-printer' work.
|
| + Pretty-printers should generally inherit from this class.
|
| +
|
| +`SubPrettyPrinter (NAME)'
|
| + For printers that handle multiple types, this class specifies the
|
| + corresponding API for the subprinters.
|
| +
|
| +`RegexpCollectionPrettyPrinter (NAME)'
|
| + Utility class for handling multiple printers, all recognized via
|
| + regular expressions. *Note Writing a Pretty-Printer::, for an
|
| + example.
|
| +
|
| +`FlagEnumerationPrinter (NAME)'
|
| + A pretty-printer which handles printing of `enum' values. Unlike
|
| + GDB's built-in `enum' printing, this printer attempts to work
|
| + properly when there is some overlap between the enumeration
|
| + constants. NAME is the name of the printer and also the name of
|
| + the `enum' type to look up.
|
| +
|
| +`register_pretty_printer (OBJ, PRINTER, REPLACE=False)'
|
| + Register PRINTER with the pretty-printer list of OBJ. If REPLACE
|
| + is `True' then any existing copy of the printer is replaced.
|
| + Otherwise a `RuntimeError' exception is raised if a printer with
|
| + the same name already exists.
|
| +
|
| +
|
| +File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: Python modules
|
| +
|
| +23.2.4.2 gdb.types
|
| +..................
|
| +
|
| +This module provides a collection of utilities for working with
|
| +`gdb.Types' objects.
|
| +
|
| +`get_basic_type (TYPE)'
|
| + Return TYPE with const and volatile qualifiers stripped, and with
|
| + typedefs and C++ references converted to the underlying type.
|
| +
|
| + C++ example:
|
| +
|
| + typedef const int const_int;
|
| + const_int foo (3);
|
| + const_int& foo_ref (foo);
|
| + int main () { return 0; }
|
| +
|
| + Then in gdb:
|
| +
|
| + (gdb) start
|
| + (gdb) python import gdb.types
|
| + (gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
|
| + (gdb) python print gdb.types.get_basic_type(foo_ref.type)
|
| + int
|
| +
|
| +`has_field (TYPE, FIELD)'
|
| + Return `True' if TYPE, assumed to be a type with fields (e.g., a
|
| + structure or union), has field FIELD.
|
| +
|
| +`make_enum_dict (ENUM_TYPE)'
|
| + Return a Python `dictionary' type produced from ENUM_TYPE.
|
| +
|
| +`deep_items (TYPE)'
|
| + Returns a Python iterator similar to the standard
|
| + `gdb.Type.iteritems' method, except that the iterator returned by
|
| + `deep_items' will recursively traverse anonymous struct or union
|
| + fields. For example:
|
| +
|
| + struct A
|
| + {
|
| + int a;
|
| + union {
|
| + int b0;
|
| + int b1;
|
| + };
|
| + };
|
| +
|
| + Then in GDB:
|
| + (gdb) python import gdb.types
|
| + (gdb) python struct_a = gdb.lookup_type("struct A")
|
| + (gdb) python print struct_a.keys ()
|
| + {['a', '']}
|
| + (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)]
|
| + {['a', 'b0', 'b1']}
|
| +
|
| +
|
| +
|
| +File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules
|
| +
|
| +23.2.4.3 gdb.prompt
|
| +...................
|
| +
|
| +This module provides a method for prompt value-substitution.
|
| +
|
| +`substitute_prompt (STRING)'
|
| + Return 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:
|
| +
|
| + `\\'
|
| + Substitute a backslash.
|
| +
|
| + `\e'
|
| + Substitute an ESC character.
|
| +
|
| + `\f'
|
| + Substitute the selected frame; an argument names a frame
|
| + parameter.
|
| +
|
| + `\n'
|
| + Substitute a newline.
|
| +
|
| + `\p'
|
| + Substitute a parameter's value; the argument names the
|
| + parameter.
|
| +
|
| + `\r'
|
| + Substitute a carriage return.
|
| +
|
| + `\t'
|
| + Substitute the selected thread; an argument names a thread
|
| + parameter.
|
| +
|
| + `\v'
|
| + Substitute the version of GDB.
|
| +
|
| + `\w'
|
| + Substitute the current working directory.
|
| +
|
| + `\['
|
| + 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.
|
| +
|
| + `\]'
|
| + End a sequence of non-printing characters.
|
| +
|
| + For example:
|
| +
|
| + substitute_prompt (``frame: \f,
|
| + print arguments: \p{print frame-arguments}'')
|
| +
|
| +will return the string:
|
| +
|
| +
|
| + "frame: main, print arguments: scalars"
|
| +
|
| +
|
| +File: gdb.info, Node: Aliases, Prev: Python, Up: Extending GDB
|
| +
|
| +23.3 Creating new spellings of existing commands
|
| +================================================
|
| +
|
| +It is often useful to define alternate spellings of existing commands.
|
| +For example, if a new GDB command defined in Python has a long name to
|
| +type, it is handy to have an abbreviated version of it that involves
|
| +less typing.
|
| +
|
| + GDB itself uses aliases. For example `s' is an alias of the `step'
|
| +command even though it is otherwise an ambiguous abbreviation of other
|
| +commands like `set' and `show'.
|
| +
|
| + Aliases are also used to provide shortened or more common versions
|
| +of multi-word commands. For example, GDB provides the `tty' alias of
|
| +the `set inferior-tty' command.
|
| +
|
| + You can define a new alias with the `alias' command.
|
| +
|
| +`alias [-a] [--] ALIAS = COMMAND'
|
| +
|
| + ALIAS specifies the name of the new alias. Each word of ALIAS must
|
| +consist of letters, numbers, dashes and underscores.
|
| +
|
| + COMMAND specifies the name of an existing command that is being
|
| +aliased.
|
| +
|
| + The `-a' option specifies that the new alias is an abbreviation of
|
| +the command. Abbreviations are not shown in command lists displayed by
|
| +the `help' command.
|
| +
|
| + The `--' option specifies the end of options, and is useful when
|
| +ALIAS begins with a dash.
|
| +
|
| + Here is a simple example showing how to make an abbreviation of a
|
| +command so that there is less to type. Suppose you were tired of
|
| +typing `disas', the current shortest unambiguous abbreviation of the
|
| +`disassemble' command and you wanted an even shorter version named `di'.
|
| +The following will accomplish this.
|
| +
|
| + (gdb) alias -a di = disas
|
| +
|
| + Note that aliases are different from user-defined commands. With a
|
| +user-defined command, you also need to write documentation for it with
|
| +the `document' command. An alias automatically picks up the
|
| +documentation of the existing command.
|
| +
|
| + Here is an example where we make `elms' an abbreviation of
|
| +`elements' in the `set print elements' command. This is to show that
|
| +you can make an abbreviation of any part of a command.
|
| +
|
| + (gdb) alias -a set print elms = set print elements
|
| + (gdb) alias -a show print elms = show print elements
|
| + (gdb) set p elms 20
|
| + (gdb) show p elms
|
| + Limit on string chars or array elements to print is 200.
|
| +
|
| + Note that if you are defining an alias of a `set' command, and you
|
| +want to have an alias for the corresponding `show' command, then you
|
| +need to define the latter separately.
|
| +
|
| + Unambiguously abbreviated commands are allowed in COMMAND and ALIAS,
|
| +just as they are normally.
|
| +
|
| + (gdb) alias -a set pr elms = set p ele
|
| +
|
| + Finally, here is an example showing the creation of a one word alias
|
| +for a more complex command. This creates alias `spe' of the command
|
| +`set print elements'.
|
| +
|
| + (gdb) alias spe = set print elements
|
| + (gdb) spe 20
|
| +
|
| +
|
| +File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top
|
| +
|
| +24 Command Interpreters
|
| +***********************
|
| +
|
| +GDB supports multiple command interpreters, and some command
|
| +infrastructure to allow users or user interface writers to switch
|
| +between interpreters or run commands in other interpreters.
|
| +
|
| + GDB currently supports two command interpreters, the console
|
| +interpreter (sometimes called the command-line interpreter or CLI) and
|
| +the machine interface interpreter (or GDB/MI). This manual describes
|
| +both of these interfaces in great detail.
|
| +
|
| + By default, GDB will start with the console interpreter. However,
|
| +the user may choose to start GDB with another interpreter by specifying
|
| +the `-i' or `--interpreter' startup options. Defined interpreters
|
| +include:
|
| +
|
| +`console'
|
| + The traditional console or command-line interpreter. This is the
|
| + most often used interpreter with GDB. With no interpreter
|
| + specified at runtime, GDB will use this interpreter.
|
| +
|
| +`mi'
|
| + The newest GDB/MI interface (currently `mi2'). Used primarily by
|
| + programs wishing to use GDB as a backend for a debugger GUI or an
|
| + IDE. For more information, see *Note The GDB/MI Interface: GDB/MI.
|
| +
|
| +`mi2'
|
| + The current GDB/MI interface.
|
| +
|
| +`mi1'
|
| + The GDB/MI interface included in GDB 5.1, 5.2, and 5.3.
|
| +
|
| +
|
| + The interpreter being used by GDB may not be dynamically switched at
|
| +runtime. Although possible, this could lead to a very precarious
|
| +situation. Consider an IDE using GDB/MI. If a user enters the command
|
| +"interpreter-set console" in a console view, GDB would switch to using
|
| +the console interpreter, rendering the IDE inoperable!
|
| +
|
| + Although you may only choose a single interpreter at startup, you
|
| +may execute commands in any interpreter from the current interpreter
|
| +using the appropriate command. If you are running the console
|
| +interpreter, simply use the `interpreter-exec' command:
|
| +
|
| + interpreter-exec mi "-data-list-register-names"
|
| +
|
| + GDB/MI has a similar command, although it is only available in
|
| +versions of GDB which support GDB/MI version 2 (or greater).
|
| +
|
| +
|
| +File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top
|
| +
|
| +25 GDB Text User Interface
|
| +**************************
|
| +
|
| +* Menu:
|
| +
|
| +* TUI Overview:: TUI overview
|
| +* TUI Keys:: TUI key bindings
|
| +* TUI Single Key Mode:: TUI single key mode
|
| +* TUI Commands:: TUI-specific commands
|
| +* TUI Configuration:: TUI configuration variables
|
| +
|
| + The GDB Text User Interface (TUI) is a terminal interface which uses
|
| +the `curses' library to show the source file, the assembly output, the
|
| +program registers and GDB commands in separate text windows. The TUI
|
| +mode is supported only on platforms where a suitable version of the
|
| +`curses' library is available.
|
| +
|
| + The TUI mode is enabled by default when you invoke GDB as `gdb -tui'.
|
| +You can also switch in and out of TUI mode while GDB runs by using
|
| +various TUI commands and key bindings, such as `C-x C-a'. *Note TUI
|
| +Key Bindings: TUI Keys.
|
| +
|
| +
|
| +File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI
|
| +
|
| +25.1 TUI Overview
|
| +=================
|
| +
|
| +In TUI mode, GDB can display several text windows:
|
| +
|
| +_command_
|
| + This window is the GDB command window with the GDB prompt and the
|
| + GDB output. The GDB input is still managed using readline.
|
| +
|
| +_source_
|
| + The source window shows the source file of the program. The
|
| + current line and active breakpoints are displayed in this window.
|
| +
|
| +_assembly_
|
| + The assembly window shows the disassembly output of the program.
|
| +
|
| +_register_
|
| + This window shows the processor registers. Registers are
|
| + highlighted when their values change.
|
| +
|
| + The source and assembly windows show the current program position by
|
| +highlighting the current line and marking it with a `>' marker.
|
| +Breakpoints are indicated with two markers. The first marker indicates
|
| +the breakpoint type:
|
| +
|
| +`B'
|
| + Breakpoint which was hit at least once.
|
| +
|
| +`b'
|
| + Breakpoint which was never hit.
|
| +
|
| +`H'
|
| + Hardware breakpoint which was hit at least once.
|
| +
|
| +`h'
|
| + Hardware breakpoint which was never hit.
|
| +
|
| + The second marker indicates whether the breakpoint is enabled or not:
|
| +
|
| +`+'
|
| + Breakpoint is enabled.
|
| +
|
| +`-'
|
| + Breakpoint is disabled.
|
| +
|
| + The source, assembly and register windows are updated when the
|
| +current thread changes, when the frame changes, or when the program
|
| +counter changes.
|
| +
|
| + These windows are not all visible at the same time. The command
|
| +window is always visible. The others can be arranged in several
|
| +layouts:
|
| +
|
| + * source only,
|
| +
|
| + * assembly only,
|
| +
|
| + * source and assembly,
|
| +
|
| + * source and registers, or
|
| +
|
| + * assembly and registers.
|
| +
|
| + A status line above the command window shows the following
|
| +information:
|
| +
|
| +_target_
|
| + Indicates the current GDB target. (*note Specifying a Debugging
|
| + Target: Targets.).
|
| +
|
| +_process_
|
| + Gives the current process or thread number. When no process is
|
| + being debugged, this field is set to `No process'.
|
| +
|
| +_function_
|
| + Gives the current function name for the selected frame. The name
|
| + is demangled if demangling is turned on (*note Print Settings::).
|
| + When there is no symbol corresponding to the current program
|
| + counter, the string `??' is displayed.
|
| +
|
| +_line_
|
| + Indicates the current line number for the selected frame. When
|
| + the current line number is not known, the string `??' is displayed.
|
| +
|
| +_pc_
|
| + Indicates the current program counter address.
|
| +
|
| +
|
| +File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI
|
| +
|
| +25.2 TUI Key Bindings
|
| +=====================
|
| +
|
| +The TUI installs several key bindings in the readline keymaps (*note
|
| +Command Line Editing::). The following key bindings are installed for
|
| +both TUI mode and the GDB standard mode.
|
| +
|
| +`C-x C-a'
|
| +`C-x a'
|
| +`C-x A'
|
| + Enter or leave the TUI mode. When leaving the TUI mode, the
|
| + curses window management stops and GDB operates using its standard
|
| + mode, writing on the terminal directly. When reentering the TUI
|
| + mode, control is given back to the curses windows. The screen is
|
| + then refreshed.
|
| +
|
| +`C-x 1'
|
| + Use a TUI layout with only one window. The layout will either be
|
| + `source' or `assembly'. When the TUI mode is not active, it will
|
| + switch to the TUI mode.
|
| +
|
| + Think of this key binding as the Emacs `C-x 1' binding.
|
| +
|
| +`C-x 2'
|
| + Use a TUI layout with at least two windows. When the current
|
| + layout already has two windows, the next layout with two windows
|
| + is used. When a new layout is chosen, one window will always be
|
| + common to the previous layout and the new one.
|
| +
|
| + Think of it as the Emacs `C-x 2' binding.
|
| +
|
| +`C-x o'
|
| + Change the active window. The TUI associates several key bindings
|
| + (like scrolling and arrow keys) with the active window. This
|
| + command gives the focus to the next TUI window.
|
| +
|
| + Think of it as the Emacs `C-x o' binding.
|
| +
|
| +`C-x s'
|
| + Switch in and out of the TUI SingleKey mode that binds single keys
|
| + to GDB commands (*note TUI Single Key Mode::).
|
| +
|
| + The following key bindings only work in the TUI mode:
|
| +
|
| +<PgUp>
|
| + Scroll the active window one page up.
|
| +
|
| +<PgDn>
|
| + Scroll the active window one page down.
|
| +
|
| +<Up>
|
| + Scroll the active window one line up.
|
| +
|
| +<Down>
|
| + Scroll the active window one line down.
|
| +
|
| +<Left>
|
| + Scroll the active window one column left.
|
| +
|
| +<Right>
|
| + Scroll the active window one column right.
|
| +
|
| +`C-L'
|
| + Refresh the screen.
|
| +
|
| + Because the arrow keys scroll the active window in the TUI mode, they
|
| +are not available for their normal use by readline unless the command
|
| +window has the focus. When another window is active, you must use
|
| +other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to
|
| +control the command window.
|
| +
|
| +
|
| +File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI
|
| +
|
| +25.3 TUI Single Key Mode
|
| +========================
|
| +
|
| +The TUI also provides a "SingleKey" mode, which binds several
|
| +frequently used GDB commands to single keys. Type `C-x s' to switch
|
| +into this mode, where the following key bindings are used:
|
| +
|
| +`c'
|
| + continue
|
| +
|
| +`d'
|
| + down
|
| +
|
| +`f'
|
| + finish
|
| +
|
| +`n'
|
| + next
|
| +
|
| +`q'
|
| + exit the SingleKey mode.
|
| +
|
| +`r'
|
| + run
|
| +
|
| +`s'
|
| + step
|
| +
|
| +`u'
|
| + up
|
| +
|
| +`v'
|
| + info locals
|
| +
|
| +`w'
|
| + where
|
| +
|
| + Other keys temporarily switch to the GDB command prompt. The key
|
| +that was pressed is inserted in the editing buffer so that it is
|
| +possible to type most GDB commands without interaction with the TUI
|
| +SingleKey mode. Once the command is entered the TUI SingleKey mode is
|
| +restored. The only way to permanently leave this mode is by typing `q'
|
| +or `C-x s'.
|
| +
|
| +
|
| +File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI
|
| +
|
| +25.4 TUI-specific Commands
|
| +==========================
|
| +
|
| +The TUI has specific commands to control the text windows. These
|
| +commands are always available, even when GDB is not in the TUI mode.
|
| +When GDB is in the standard mode, most of these commands will
|
| +automatically switch to the TUI mode.
|
| +
|
| + Note that if GDB's `stdout' is not connected to a terminal, or GDB
|
| +has been started with the machine interface interpreter (*note The
|
| +GDB/MI Interface: GDB/MI.), most of these commands will fail with an
|
| +error, because it would not be possible or desirable to enable curses
|
| +window management.
|
| +
|
| +`info win'
|
| + List and give the size of all displayed windows.
|
| +
|
| +`layout next'
|
| + Display the next layout.
|
| +
|
| +`layout prev'
|
| + Display the previous layout.
|
| +
|
| +`layout src'
|
| + Display the source window only.
|
| +
|
| +`layout asm'
|
| + Display the assembly window only.
|
| +
|
| +`layout split'
|
| + Display the source and assembly window.
|
| +
|
| +`layout regs'
|
| + Display the register window together with the source or assembly
|
| + window.
|
| +
|
| +`focus next'
|
| + Make the next window active for scrolling.
|
| +
|
| +`focus prev'
|
| + Make the previous window active for scrolling.
|
| +
|
| +`focus src'
|
| + Make the source window active for scrolling.
|
| +
|
| +`focus asm'
|
| + Make the assembly window active for scrolling.
|
| +
|
| +`focus regs'
|
| + Make the register window active for scrolling.
|
| +
|
| +`focus cmd'
|
| + Make the command window active for scrolling.
|
| +
|
| +`refresh'
|
| + Refresh the screen. This is similar to typing `C-L'.
|
| +
|
| +`tui reg float'
|
| + Show the floating point registers in the register window.
|
| +
|
| +`tui reg general'
|
| + Show the general registers in the register window.
|
| +
|
| +`tui reg next'
|
| + Show the next register group. The list of register groups as well
|
| + as their order is target specific. The predefined register groups
|
| + are the following: `general', `float', `system', `vector', `all',
|
| + `save', `restore'.
|
| +
|
| +`tui reg system'
|
| + Show the system registers in the register window.
|
| +
|
| +`update'
|
| + Update the source window and the current execution point.
|
| +
|
| +`winheight NAME +COUNT'
|
| +`winheight NAME -COUNT'
|
| + Change the height of the window NAME by COUNT lines. Positive
|
| + counts increase the height, while negative counts decrease it.
|
| +
|
| +`tabset NCHARS'
|
| + Set the width of tab stops to be NCHARS characters.
|
| +
|
| +
|
| +File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI
|
| +
|
| +25.5 TUI Configuration Variables
|
| +================================
|
| +
|
| +Several configuration variables control the appearance of TUI windows.
|
| +
|
| +`set tui border-kind KIND'
|
| + Select the border appearance for the source, assembly and register
|
| + windows. The possible values are the following:
|
| + `space'
|
| + Use a space character to draw the border.
|
| +
|
| + `ascii'
|
| + Use ASCII characters `+', `-' and `|' to draw the border.
|
| +
|
| + `acs'
|
| + Use the Alternate Character Set to draw the border. The
|
| + border is drawn using character line graphics if the terminal
|
| + supports them.
|
| +
|
| +`set tui border-mode MODE'
|
| +`set tui active-border-mode MODE'
|
| + Select the display attributes for the borders of the inactive
|
| + windows or the active window. The MODE can be one of the
|
| + following:
|
| + `normal'
|
| + Use normal attributes to display the border.
|
| +
|
| + `standout'
|
| + Use standout mode.
|
| +
|
| + `reverse'
|
| + Use reverse video mode.
|
| +
|
| + `half'
|
| + Use half bright mode.
|
| +
|
| + `half-standout'
|
| + Use half bright and standout mode.
|
| +
|
| + `bold'
|
| + Use extra bright or bold mode.
|
| +
|
| + `bold-standout'
|
| + Use extra bright or bold and standout mode.
|
| +
|
| +
|
| +File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top
|
| +
|
| +26 Using GDB under GNU Emacs
|
| +****************************
|
| +
|
| +A special interface allows you to use GNU Emacs to view (and edit) the
|
| +source files for the program you are debugging with GDB.
|
| +
|
| + To use this interface, use the command `M-x gdb' in Emacs. Give the
|
| +executable file you want to debug as an argument. This command starts
|
| +GDB as a subprocess of Emacs, with input and output through a newly
|
| +created Emacs buffer.
|
| +
|
| + Running GDB under Emacs can be just like running GDB normally except
|
| +for two things:
|
| +
|
| + * All "terminal" input and output goes through an Emacs buffer,
|
| + called the GUD buffer.
|
| +
|
| + This applies both to GDB commands and their output, and to the
|
| + input and output done by the program you are debugging.
|
| +
|
| + This is useful because it means that you can copy the text of
|
| + previous commands and input them again; you can even use parts of
|
| + the output in this way.
|
| +
|
| + All the facilities of Emacs' Shell mode are available for
|
| + interacting with your program. In particular, you can send
|
| + signals the usual way--for example, `C-c C-c' for an interrupt,
|
| + `C-c C-z' for a stop.
|
| +
|
| + * GDB displays source code through Emacs.
|
| +
|
| + Each time GDB displays a stack frame, Emacs automatically finds the
|
| + source file for that frame and puts an arrow (`=>') at the left
|
| + margin of the current line. Emacs uses a separate buffer for
|
| + source display, and splits the screen to show both your GDB session
|
| + and the source.
|
| +
|
| + Explicit GDB `list' or search commands still produce output as
|
| + usual, but you probably have no reason to use them from Emacs.
|
| +
|
| + We call this "text command mode". Emacs 22.1, and later, also uses
|
| +a graphical mode, enabled by default, which provides further buffers
|
| +that can control the execution and describe the state of your program.
|
| +*Note GDB Graphical Interface: (Emacs)GDB Graphical Interface.
|
| +
|
| + If you specify an absolute file name when prompted for the `M-x gdb'
|
| +argument, then Emacs sets your current working directory to where your
|
| +program resides. If you only specify the file name, then Emacs sets
|
| +your current working directory to the directory associated with the
|
| +previous buffer. In this case, GDB may find your program by searching
|
| +your environment's `PATH' variable, but on some operating systems it
|
| +might not find the source. So, although the GDB input and output
|
| +session proceeds normally, the auxiliary buffer does not display the
|
| +current source and line of execution.
|
| +
|
| + The initial working directory of GDB is printed on the top line of
|
| +the GUD buffer and this serves as a default for the commands that
|
| +specify files for GDB to operate on. *Note Commands to Specify Files:
|
| +Files.
|
| +
|
| + By default, `M-x gdb' calls the program called `gdb'. If you need
|
| +to call GDB by a different name (for example, if you keep several
|
| +configurations around, with different names) you can customize the
|
| +Emacs variable `gud-gdb-command-name' to run the one you want.
|
| +
|
| + In the GUD buffer, you can use these special Emacs commands in
|
| +addition to the standard Shell mode commands:
|
| +
|
| +`C-h m'
|
| + Describe the features of Emacs' GUD Mode.
|
| +
|
| +`C-c C-s'
|
| + Execute to another source line, like the GDB `step' command; also
|
| + update the display window to show the current file and location.
|
| +
|
| +`C-c C-n'
|
| + Execute to next source line in this function, skipping all function
|
| + calls, like the GDB `next' command. Then update the display window
|
| + to show the current file and location.
|
| +
|
| +`C-c C-i'
|
| + Execute one instruction, like the GDB `stepi' command; update
|
| + display window accordingly.
|
| +
|
| +`C-c C-f'
|
| + Execute until exit from the selected stack frame, like the GDB
|
| + `finish' command.
|
| +
|
| +`C-c C-r'
|
| + Continue execution of your program, like the GDB `continue'
|
| + command.
|
| +
|
| +`C-c <'
|
| + Go up the number of frames indicated by the numeric argument
|
| + (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
|
| + command.
|
| +
|
| +`C-c >'
|
| + Go down the number of frames indicated by the numeric argument,
|
| + like the GDB `down' command.
|
| +
|
| + In any source file, the Emacs command `C-x <SPC>' (`gud-break')
|
| +tells GDB to set a breakpoint on the source line point is on.
|
| +
|
| + In text command mode, if you type `M-x speedbar', Emacs displays a
|
| +separate frame which shows a backtrace when the GUD buffer is current.
|
| +Move point to any frame in the stack and type <RET> to make it become
|
| +the current frame and display the associated source in the source
|
| +buffer. Alternatively, click `Mouse-2' to make the selected frame
|
| +become the current one. In graphical mode, the speedbar displays watch
|
| +expressions.
|
| +
|
| + If you accidentally delete the source-display buffer, an easy way to
|
| +get it back is to type the command `f' in the GDB buffer, to request a
|
| +frame display; when you run under Emacs, this recreates the source
|
| +buffer if necessary to show you the context of the current frame.
|
| +
|
| + The source files displayed in Emacs are in ordinary Emacs buffers
|
| +which are visiting the source files in the usual way. You can edit the
|
| +files with these buffers if you wish; but keep in mind that GDB
|
| +communicates with Emacs in terms of line numbers. If you add or delete
|
| +lines from the text, the line numbers that GDB knows cease to
|
| +correspond properly with the code.
|
| +
|
| + A more detailed description of Emacs' interaction with GDB is given
|
| +in the Emacs manual (*note Debuggers: (Emacs)Debuggers.).
|
| +
|
| +
|
| +File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top
|
| +
|
| +27 The GDB/MI Interface
|
| +***********************
|
| +
|
| +Function and Purpose
|
| +====================
|
| +
|
| +GDB/MI is a line based machine oriented text interface to GDB and is
|
| +activated by specifying using the `--interpreter' command line option
|
| +(*note Mode Options::). It is specifically intended to support the
|
| +development of systems which use the debugger as just one small
|
| +component of a larger system.
|
| +
|
| + This chapter is a specification of the GDB/MI interface. It is
|
| +written in the form of a reference manual.
|
| +
|
| + Note that GDB/MI is still under construction, so some of the
|
| +features described below are incomplete and subject to change (*note
|
| +GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.).
|
| +
|
| +Notation and Terminology
|
| +========================
|
| +
|
| +This chapter uses the following notation:
|
| +
|
| + * `|' separates two alternatives.
|
| +
|
| + * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
|
| + may not be given.
|
| +
|
| + * `( GROUP )*' means that GROUP inside the parentheses may repeat
|
| + zero or more times.
|
| +
|
| + * `( GROUP )+' means that GROUP inside the parentheses may repeat
|
| + one or more times.
|
| +
|
| + * `"STRING"' means a literal STRING.
|
| +
|
| +* Menu:
|
| +
|
| +* GDB/MI General Design::
|
| +* GDB/MI Command Syntax::
|
| +* GDB/MI Compatibility with CLI::
|
| +* GDB/MI Development and Front Ends::
|
| +* GDB/MI Output Records::
|
| +* GDB/MI Simple Examples::
|
| +* GDB/MI Command Description Format::
|
| +* GDB/MI Breakpoint Commands::
|
| +* GDB/MI Program Context::
|
| +* GDB/MI Thread Commands::
|
| +* GDB/MI Ada Tasking Commands::
|
| +* GDB/MI Program Execution::
|
| +* GDB/MI Stack Manipulation::
|
| +* GDB/MI Variable Objects::
|
| +* GDB/MI Data Manipulation::
|
| +* GDB/MI Tracepoint Commands::
|
| +* GDB/MI Symbol Query::
|
| +* GDB/MI File Commands::
|
| +* GDB/MI Target Manipulation::
|
| +* GDB/MI File Transfer Commands::
|
| +* GDB/MI Miscellaneous Commands::
|
| +
|
| +
|
| +File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI
|
| +
|
| +27.1 GDB/MI General Design
|
| +==========================
|
| +
|
| +Interaction of a GDB/MI frontend with GDB involves three
|
| +parts--commands sent to GDB, responses to those commands and
|
| +notifications. Each command results in exactly one response,
|
| +indicating either successful completion of the command, or an error.
|
| +For the commands that do not resume the target, the response contains
|
| +the requested information. For the commands that resume the target, the
|
| +response only indicates whether the target was successfully resumed.
|
| +Notifications is the mechanism for reporting changes in the state of the
|
| +target, or in GDB state, that cannot conveniently be associated with a
|
| +command and reported as part of that command response.
|
| +
|
| + The important examples of notifications are:
|
| + * Exec notifications. These are used to report changes in target
|
| + state--when a target is resumed, or stopped. It would not be
|
| + feasible to include this information in response of resuming
|
| + commands, because one resume commands can result in multiple
|
| + events in different threads. Also, quite some time may pass
|
| + before any event happens in the target, while a frontend needs to
|
| + know whether the resuming command itself was successfully executed.
|
| +
|
| + * Console output, and status notifications. Console output
|
| + notifications are used to report output of CLI commands, as well as
|
| + diagnostics for other commands. Status notifications are used to
|
| + report the progress of a long-running operation. Naturally,
|
| + including this information in command response would mean no
|
| + output is produced until the command is finished, which is
|
| + undesirable.
|
| +
|
| + * General notifications. Commands may have various side effects on
|
| + the GDB or target state beyond their official purpose. For
|
| + example, a command may change the selected thread. Although such
|
| + changes can be included in command response, using notification
|
| + allows for more orthogonal frontend design.
|
| +
|
| +
|
| + There's no guarantee that whenever an MI command reports an error,
|
| +GDB or the target are in any specific state, and especially, the state
|
| +is not reverted to the state before the MI command was processed.
|
| +Therefore, whenever an MI command results in an error, we recommend
|
| +that the frontend refreshes all the information shown in the user
|
| +interface.
|
| +
|
| +* Menu:
|
| +
|
| +* Context management::
|
| +* Asynchronous and non-stop modes::
|
| +* Thread groups::
|
| +
|
| +
|
| +File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design
|
| +
|
| +27.1.1 Context management
|
| +-------------------------
|
| +
|
| +In most cases when GDB accesses the target, this access is done in
|
| +context of a specific thread and frame (*note Frames::). Often, even
|
| +when accessing global data, the target requires that a thread be
|
| +specified. The CLI interface maintains the selected thread and frame,
|
| +and supplies them to target on each command. This is convenient,
|
| +because a command line user would not want to specify that information
|
| +explicitly on each command, and because user interacts with GDB via a
|
| +single terminal, so no confusion is possible as to what thread and
|
| +frame are the current ones.
|
| +
|
| + In the case of MI, the concept of selected thread and frame is less
|
| +useful. First, a frontend can easily remember this information itself.
|
| +Second, a graphical frontend can have more than one window, each one
|
| +used for debugging a different thread, and the frontend might want to
|
| +access additional threads for internal purposes. This increases the
|
| +risk that by relying on implicitly selected thread, the frontend may be
|
| +operating on a wrong one. Therefore, each MI command should explicitly
|
| +specify which thread and frame to operate on. To make it possible,
|
| +each MI command accepts the `--thread' and `--frame' options, the value
|
| +to each is GDB identifier for thread and frame to operate on.
|
| +
|
| + Usually, each top-level window in a frontend allows the user to
|
| +select a thread and a frame, and remembers the user selection for
|
| +further operations. However, in some cases GDB may suggest that the
|
| +current thread be changed. For example, when stopping on a breakpoint
|
| +it is reasonable to switch to the thread where breakpoint is hit. For
|
| +another example, if the user issues the CLI `thread' command via the
|
| +frontend, it is desirable to change the frontend's selected thread to
|
| +the one specified by user. GDB communicates the suggestion to change
|
| +current thread using the `=thread-selected' notification. No such
|
| +notification is available for the selected frame at the moment.
|
| +
|
| + Note that historically, MI shares the selected thread with CLI, so
|
| +frontends used the `-thread-select' to execute commands in the right
|
| +context. However, getting this to work right is cumbersome. The
|
| +simplest way is for frontend to emit `-thread-select' command before
|
| +every command. This doubles the number of commands that need to be
|
| +sent. The alternative approach is to suppress `-thread-select' if the
|
| +selected thread in GDB is supposed to be identical to the thread the
|
| +frontend wants to operate on. However, getting this optimization right
|
| +can be tricky. In particular, if the frontend sends several commands
|
| +to GDB, and one of the commands changes the selected thread, then the
|
| +behaviour of subsequent commands will change. So, a frontend should
|
| +either wait for response from such problematic commands, or explicitly
|
| +add `-thread-select' for all subsequent commands. No frontend is known
|
| +to do this exactly right, so it is suggested to just always pass the
|
| +`--thread' and `--frame' options.
|
| +
|
| +
|
| +File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design
|
| +
|
| +27.1.2 Asynchronous command execution and non-stop mode
|
| +-------------------------------------------------------
|
| +
|
| +On some targets, GDB is capable of processing MI commands even while
|
| +the target is running. This is called "asynchronous command execution"
|
| +(*note Background Execution::). The frontend may specify a preferrence
|
| +for asynchronous execution using the `-gdb-set target-async 1' command,
|
| +which should be emitted before either running the executable or
|
| +attaching to the target. After the frontend has started the executable
|
| +or attached to the target, it can find if asynchronous execution is
|
| +enabled using the `-list-target-features' command.
|
| +
|
| + Even if GDB can accept a command while target is running, many
|
| +commands that access the target do not work when the target is running.
|
| +Therefore, asynchronous command execution is most useful when combined
|
| +with non-stop mode (*note Non-Stop Mode::). Then, it is possible to
|
| +examine the state of one thread, while other threads are running.
|
| +
|
| + When a given thread is running, MI commands that try to access the
|
| +target in the context of that thread may not work, or may work only on
|
| +some targets. In particular, commands that try to operate on thread's
|
| +stack will not work, on any target. Commands that read memory, or
|
| +modify breakpoints, may work or not work, depending on the target. Note
|
| +that even commands that operate on global state, such as `print',
|
| +`set', and breakpoint commands, still access the target in the context
|
| +of a specific thread, so frontend should try to find a stopped thread
|
| +and perform the operation on that thread (using the `--thread' option).
|
| +
|
| + Which commands will work in the context of a running thread is
|
| +highly target dependent. However, the two commands `-exec-interrupt',
|
| +to stop a thread, and `-thread-info', to find the state of a thread,
|
| +will always work.
|
| +
|
| +
|
| +File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design
|
| +
|
| +27.1.3 Thread groups
|
| +--------------------
|
| +
|
| +GDB may be used to debug several processes at the same time. On some
|
| +platfroms, GDB may support debugging of several hardware systems, each
|
| +one having several cores with several different processes running on
|
| +each core. This section describes the MI mechanism to support such
|
| +debugging scenarios.
|
| +
|
| + The key observation is that regardless of the structure of the
|
| +target, MI can have a global list of threads, because most commands that
|
| +accept the `--thread' option do not need to know what process that
|
| +thread belongs to. Therefore, it is not necessary to introduce neither
|
| +additional `--process' option, nor an notion of the current process in
|
| +the MI interface. The only strictly new feature that is required is
|
| +the ability to find how the threads are grouped into processes.
|
| +
|
| + To allow the user to discover such grouping, and to support arbitrary
|
| +hierarchy of machines/cores/processes, MI introduces the concept of a
|
| +"thread group". Thread group is a collection of threads and other
|
| +thread groups. A thread group always has a string identifier, a type,
|
| +and may have additional attributes specific to the type. A new
|
| +command, `-list-thread-groups', returns the list of top-level thread
|
| +groups, which correspond to processes that GDB is debugging at the
|
| +moment. By passing an identifier of a thread group to the
|
| +`-list-thread-groups' command, it is possible to obtain the members of
|
| +specific thread group.
|
| +
|
| + To allow the user to easily discover processes, and other objects, he
|
| +wishes to debug, a concept of "available thread group" is introduced.
|
| +Available thread group is an thread group that GDB is not debugging,
|
| +but that can be attached to, using the `-target-attach' command. The
|
| +list of available top-level thread groups can be obtained using
|
| +`-list-thread-groups --available'. In general, the content of a thread
|
| +group may be only retrieved only after attaching to that thread group.
|
| +
|
| + Thread groups are related to inferiors (*note Inferiors and
|
| +Programs::). Each inferior corresponds to a thread group of a special
|
| +type `process', and some additional operations are permitted on such
|
| +thread groups.
|
| +
|
| +
|
| +File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI
|
| +
|
| +27.2 GDB/MI Command Syntax
|
| +==========================
|
| +
|
| +* Menu:
|
| +
|
| +* GDB/MI Input Syntax::
|
| +* GDB/MI Output Syntax::
|
| +
|
| +
|
| +File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax
|
| +
|
| +27.2.1 GDB/MI Input Syntax
|
| +--------------------------
|
| +
|
| +`COMMAND ==>'
|
| + `CLI-COMMAND | MI-COMMAND'
|
| +
|
| +`CLI-COMMAND ==>'
|
| + `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
|
| + CLI command.
|
| +
|
| +`MI-COMMAND ==>'
|
| + `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
|
| + PARAMETER )* NL'
|
| +
|
| +`TOKEN ==>'
|
| + "any sequence of digits"
|
| +
|
| +`OPTION ==>'
|
| + `"-" PARAMETER [ " " PARAMETER ]'
|
| +
|
| +`PARAMETER ==>'
|
| + `NON-BLANK-SEQUENCE | C-STRING'
|
| +
|
| +`OPERATION ==>'
|
| + _any of the operations described in this chapter_
|
| +
|
| +`NON-BLANK-SEQUENCE ==>'
|
| + _anything, provided it doesn't contain special characters such as
|
| + "-", NL, """ and of course " "_
|
| +
|
| +`C-STRING ==>'
|
| + `""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
|
| +
|
| +`NL ==>'
|
| + `CR | CR-LF'
|
| +
|
| +Notes:
|
| +
|
| + * The CLI commands are still handled by the MI interpreter; their
|
| + output is described below.
|
| +
|
| + * The `TOKEN', when present, is passed back when the command
|
| + finishes.
|
| +
|
| + * Some MI commands accept optional arguments as part of the parameter
|
| + list. Each option is identified by a leading `-' (dash) and may be
|
| + followed by an optional argument parameter. Options occur first
|
| + in the parameter list and can be delimited from normal parameters
|
| + using `--' (this is useful when some parameters begin with a dash).
|
| +
|
| + Pragmatics:
|
| +
|
| + * We want easy access to the existing CLI syntax (for debugging).
|
| +
|
| + * We want it to be easy to spot a MI operation.
|
| +
|
| +
|
| File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax
|
|
|
| 27.2.2 GDB/MI Output Syntax
|
| @@ -363,8 +1632,9 @@ activity (e.g., target stopped).
|
|
|
| `solib-event'
|
| The inferior has stopped due to a library being loaded or
|
| - unloaded. This can only happen when `stop-on-solib-events'
|
| - (*note Files::) is set.
|
| + unloaded. This can happen when `stop-on-solib-events' (*note
|
| + Files::) is set or when a `catch load' or `catch unload'
|
| + catchpoint is in use (*note Set Catchpoints::).
|
|
|
| `fork'
|
| The inferior has forked. This is reported when `catch fork'
|
| @@ -921,7 +2191,7 @@ Synopsis
|
|
|
| -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
|
| [ -c CONDITION ] [ -i IGNORE-COUNT ]
|
| - [ -p THREAD ] [ LOCATION ]
|
| + [ -p THREAD-ID ] [ LOCATION ]
|
|
|
| If specified, LOCATION, can be one of:
|
|
|
| @@ -941,12 +2211,6 @@ If specified, LOCATION, can be one of:
|
| `-h'
|
| Insert a hardware breakpoint.
|
|
|
| -`-c CONDITION'
|
| - Make the breakpoint conditional on CONDITION.
|
| -
|
| -`-i IGNORE-COUNT'
|
| - Initialize the IGNORE-COUNT.
|
| -
|
| `-f'
|
| If LOCATION cannot be parsed (for example if it refers to unknown
|
| files or functions), create a pending breakpoint. Without this
|
| @@ -960,6 +2224,15 @@ If specified, LOCATION, can be one of:
|
| Create a tracepoint. *Note Tracepoints::. When this parameter is
|
| used together with `-h', a fast tracepoint is created.
|
|
|
| +`-c CONDITION'
|
| + Make the breakpoint conditional on CONDITION.
|
| +
|
| +`-i IGNORE-COUNT'
|
| + Initialize the IGNORE-COUNT.
|
| +
|
| +`-p THREAD-ID'
|
| + Restrict the breakpoint to the specified THREAD-ID.
|
| +
|
| Result
|
| ......
|
|
|
| @@ -982,8 +2255,8 @@ greater for -break-info or -break-list which use the same output).
|
| GDB Command
|
| ...........
|
|
|
| -The corresponding GDB commands are `break', `tbreak', `hbreak',
|
| -`thbreak', and `rbreak'.
|
| +The corresponding GDB commands are `break', `tbreak', `hbreak', and
|
| +`thbreak'.
|
|
|
| Example
|
| .......
|
| @@ -1012,11 +2285,6 @@ 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)
|
|
|
| The `-break-list' Command
|
| -------------------------
|
| @@ -2643,7 +3911,10 @@ are:
|
|
|
| `type'
|
| The varobj's type. This is a string representation of the type, as
|
| - would be printed by the GDB CLI.
|
| + would be printed by the GDB CLI. If `print object' (*note set
|
| + print object: Print Settings.) is set to `on', the _actual_
|
| + (derived) type of the object is shown rather than the _declared_
|
| + one.
|
|
|
| `thread-id'
|
| If a variable object is bound to a specific thread, then this is
|
| @@ -2791,7 +4062,9 @@ NUMCHILD
|
| will be 0.
|
|
|
| TYPE
|
| - The type of the child.
|
| + The type of the child. If `print object' (*note set print object:
|
| + Print Settings.) is set to `on', the _actual_ (derived) type of
|
| + the object is shown rather than the _declared_ one.
|
|
|
| VALUE
|
| If values were requested, this is the value.
|
| @@ -3013,6 +4286,12 @@ only the selected range of children will be reported.
|
| changed, then this will be the string `true'; otherwise it will be
|
| `false'.
|
|
|
| + When a varobj's type changes, its children are also likely to have
|
| + become incorrect. Therefore, the varobj's children are
|
| + automatically deleted when this attribute is `true'. Also, the
|
| + varobj's update range, when set using the `-var-set-update-range'
|
| + command, is unset.
|
| +
|
| `new_type'
|
| If the varobj's type changed, then this field will be present and
|
| will hold the new type.
|
| @@ -4751,6 +6030,78 @@ Example
|
| threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
|
| {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...]
|
|
|
| +The `-info-os' Command
|
| +----------------------
|
| +
|
| +Synopsis
|
| +........
|
| +
|
| + -info-os [ TYPE ]
|
| +
|
| + 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 TYPE, then the command returns a table of data
|
| +of that type.
|
| +
|
| + The types of information available depend on the target operating
|
| +system.
|
| +
|
| +GDB Command
|
| +...........
|
| +
|
| +The corresponding GDB command is `info os'.
|
| +
|
| +Example
|
| +.......
|
| +
|
| +When run on a GNU/Linux system, the output will look something like
|
| +this:
|
| +
|
| + gdb
|
| + -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"}]}
|
| + gdb
|
| + -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)
|
| +
|
| + (Note that the MI output here includes a `"Title"' column that does
|
| +not appear in command-line `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 `info os' omits
|
| +it.)
|
| +
|
| The `-add-inferior' Command
|
| ---------------------------
|
|
|
| @@ -5166,7 +6517,7 @@ in the form `0x' followed by one or more lowercase hex digits (note
|
| that this does not depend on the language).
|
|
|
|
|
| -File: gdb.info, Node: JIT Interface, Next: GDB Bugs, Prev: Annotations, Up: Top
|
| +File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotations, Up: Top
|
|
|
| 29 JIT Compilation Interface
|
| ****************************
|
| @@ -5402,9 +6753,228 @@ the previous frame. Both have a callback (`target_read') to read bytes
|
| off the target's address space.
|
|
|
|
|
| -File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: JIT Interface, Up: Top
|
| +File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top
|
| +
|
| +30 In-Process Agent
|
| +*******************
|
| +
|
| +The traditional debugging model is conceptually low-speed, but works
|
| +fine, because most bugs can be reproduced in debugging-mode execution.
|
| +However, as multi-core or many-core processors are becoming mainstream,
|
| +and multi-threaded programs become more and more popular, there should
|
| +be more and more bugs that only manifest themselves at normal-mode
|
| +execution, for example, thread races, because debugger's interference
|
| +with the program's timing may conceal the bugs. On the other hand, in
|
| +some applications, it is not feasible for the debugger to interrupt the
|
| +program's execution long enough for the developer to learn anything
|
| +helpful about its behavior. If the program's correctness depends on
|
| +its real-time behavior, delays introduced by a debugger might cause the
|
| +program to fail, even when the code itself is correct. It is useful to
|
| +be able to observe the program's behavior without interrupting it.
|
| +
|
| + Therefore, traditional debugging model is too intrusive to reproduce
|
| +some bugs. In order to reduce the interference with the program, we can
|
| +reduce the number of operations performed by debugger. The "In-Process
|
| +Agent", a shared library, is running within the same process with
|
| +inferior, and is able to perform some debugging operations itself. As
|
| +a result, debugger is only involved when necessary, and performance of
|
| +debugging can be improved accordingly. Note that interference with
|
| +program can be reduced but can't be removed completely, because the
|
| +in-process agent will still stop or slow down the program.
|
| +
|
| + The in-process agent can interpret and execute Agent Expressions
|
| +(*note Agent Expressions::) during performing debugging operations. The
|
| +agent expressions can be used for different purposes, such as collecting
|
| +data in tracepoints, and condition evaluation in breakpoints.
|
| +
|
| + You can control whether the in-process agent is used as an aid for
|
| +debugging with the following commands:
|
| +
|
| +`set agent on'
|
| + Causes the in-process agent to perform some operations on behalf
|
| + of the debugger. Just which operations requested by the user will
|
| + be done by the in-process agent depends on the its capabilities.
|
| + For example, if you request to evaluate breakpoint conditions in
|
| + the in-process agent, and the in-process agent has such capability
|
| + as well, then breakpoint conditions will be evaluated in the
|
| + in-process agent.
|
| +
|
| +`set agent off'
|
| + Disables execution of debugging operations by the in-process
|
| + agent. All of the operations will be performed by GDB.
|
| +
|
| +`show agent'
|
| + Display the current setting of execution of debugging operations by
|
| + the in-process agent.
|
| +
|
| +* Menu:
|
| +
|
| +* In-Process Agent Protocol::
|
| +
|
| +
|
| +File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent
|
| +
|
| +30.1 In-Process Agent Protocol
|
| +==============================
|
| +
|
| +The in-process agent is able to communicate with both GDB and GDBserver
|
| +(*note In-Process Agent::). This section documents the protocol used
|
| +for communications between GDB or GDBserver and the IPA. In general,
|
| +GDB or GDBserver sends commands (*note 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
|
| +(*note IPA Protocol Objects::).
|
| +
|
| +* Menu:
|
| +
|
| +* IPA Protocol Objects::
|
| +* IPA Protocol Commands::
|
| +
|
| +
|
| +File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol
|
| +
|
| +30.1.1 IPA Protocol Objects
|
| +---------------------------
|
| +
|
| +The commands sent to and results received from agent may contain some
|
| +complex data types called "objects".
|
| +
|
| + The in-process agent is running on the same machine with GDB or
|
| +GDBserver, so it doesn't have to handle as much differences between two
|
| +ends as remote protocol (*note Remote Protocol::) tries to handle.
|
| +However, there are still some differences of two ends in two processes:
|
| +
|
| + 1. word size. On some 64-bit machines, GDB or GDBserver can be
|
| + compiled as a 64-bit executable, while in-process agent is a
|
| + 32-bit one.
|
| +
|
| + 2. ABI. Some machines may have multiple types of ABI, GDB or
|
| + GDBserver is compiled with one, and in-process agent is compiled
|
| + with the other one.
|
| +
|
| + Here are the IPA Protocol Objects:
|
| +
|
| + 1. agent expression object. It represents an agent expression (*note
|
| + Agent Expressions::).
|
| +
|
| + 2. tracepoint action object. It represents a tracepoint action
|
| + (*note Tracepoint Action Lists: Tracepoint Actions.) to collect
|
| + registers, memory, static trace data and to evaluate expression.
|
| +
|
| + 3. tracepoint object. It represents a tracepoint (*note
|
| + Tracepoints::).
|
| +
|
| +
|
| + The following table describes important attributes of each IPA
|
| +protocol object:
|
| +
|
| +Name Size Description
|
| +---------------------------------------------------------------------------
|
| +_agent expression
|
| +object_
|
| +length 4 length of bytes code
|
| +byte code LENGTH contents of byte code
|
| +_tracepoint action
|
| +for collecting
|
| +memory_
|
| +'M' 1 type of tracepoint action
|
| +addr 8 if BASEREG is `-1', ADDR is the
|
| + address of the lowest byte to
|
| + collect, otherwise ADDR is the
|
| + offset of BASEREG for memory
|
| + collecting.
|
| +len 8 length of memory for collecting
|
| +basereg 4 the register number containing the
|
| + starting memory address for
|
| + collecting.
|
| +_tracepoint action
|
| +for collecting
|
| +registers_
|
| +'R' 1 type of tracepoint action
|
| +_tracepoint action
|
| +for collecting static
|
| +trace data_
|
| +'L' 1 type of tracepoint action
|
| +_tracepoint action
|
| +for expression
|
| +evaluation_
|
| +'X' 1 type of tracepoint action
|
| +agent expression length of *Note agent expression object::
|
| +_tracepoint object_
|
| +number 4 number of tracepoint
|
| +address 8 address of tracepoint inserted on
|
| +type 4 type of tracepoint
|
| +enabled 1 enable or disable of tracepoint
|
| +step_count 8 step
|
| +pass_count 8 pass
|
| +numactions 4 number of tracepoint actions
|
| +hit count 8 hit count
|
| +trace frame usage 8 trace frame usage
|
| +compiled_cond 8 compiled condition
|
| +orig_size 8 orig size
|
| +condition 4 if zero if condition is NULL,
|
| + condition is otherwise is *Note agent expression
|
| + NULL object::
|
| + otherwise
|
| + length of
|
| + *Note agent
|
| + expression
|
| + object::
|
| +actions variable numactions number of *Note
|
| + tracepoint action object::
|
| +
|
| +
|
| +File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol
|
| +
|
| +30.1.2 IPA Protocol Commands
|
| +----------------------------
|
| +
|
| +The spaces in each command are delimiters to ease reading this commands
|
| +specification. They don't exist in real commands.
|
| +
|
| +`FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD'
|
| + Installs a new fast tracepoint described by TRACEPOINT_OBJECT
|
| + (*note tracepoint object::). GDB_JUMP_PAD_HEAD, 8-byte long, is
|
| + the head of "jumppad", which is used to jump to data collection
|
| + routine in IPA finally.
|
| +
|
| + Replies:
|
| + `OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP'
|
| + TARGET_ADDRESS is address of tracepoint in the inferior.
|
| + GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of
|
| + TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. FJUMP
|
| + contains a sequence of instructions jump to jumppad entry.
|
| + FJUMP_SIZE, 4-byte long, is the size of FJUMP.
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +
|
| +`qTfSTM'
|
| + *Note qTfSTM::.
|
| +
|
| +`qTsSTM'
|
| + *Note qTsSTM::.
|
| +
|
| +`qTSTMat'
|
| + *Note qTSTMat::.
|
| +
|
| +`probe_marker_at:ADDRESS'
|
| + Asks in-process agent to probe the marker at ADDRESS.
|
| +
|
| + Replies:
|
| + `E NN'
|
| + for an error
|
| +
|
| +`unprobe_marker_at:ADDRESS'
|
| + Asks in-process agent to unprobe the marker at ADDRESS.
|
| +
|
| +
|
| +File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top
|
|
|
| -30 Reporting Bugs in GDB
|
| +31 Reporting Bugs in GDB
|
| ************************
|
|
|
| Your bug reports play an essential role in making GDB reliable.
|
| @@ -5425,7 +6995,7 @@ information that enables us to fix the bug.
|
|
|
| File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
|
|
|
| -30.1 Have You Found a Bug?
|
| +31.1 Have You Found a Bug?
|
| ==========================
|
|
|
| If you are not sure whether you have found a bug, here are some
|
| @@ -5449,7 +7019,7 @@ guidelines:
|
|
|
| File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
|
|
|
| -30.2 How to Report Bugs
|
| +31.2 How to Report Bugs
|
| =======================
|
|
|
| A number of companies and individuals offer support for GNU products.
|
| @@ -5615,7 +7185,7 @@ to respond to them_ except to chide the sender to report bugs properly.
|
|
|
| File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
|
|
|
| -31 Command Line Editing
|
| +32 Command Line Editing
|
| ***********************
|
|
|
| This chapter describes the basic features of the GNU command line
|
| @@ -5634,7 +7204,7 @@ editing interface.
|
|
|
| File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
|
|
|
| -31.1 Introduction to Line Editing
|
| +32.1 Introduction to Line Editing
|
| =================================
|
|
|
| The following paragraphs describe the notation used to represent
|
| @@ -5670,7 +7240,7 @@ some keyboards.
|
|
|
| File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
|
|
|
| -31.2 Readline Interaction
|
| +32.2 Readline Interaction
|
| =========================
|
|
|
| Often during an interactive session you type in a long line of text,
|
| @@ -5695,7 +7265,7 @@ location of the cursor within the line.
|
|
|
| File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
|
|
|
| -31.2.1 Readline Bare Essentials
|
| +32.2.1 Readline Bare Essentials
|
| -------------------------------
|
|
|
| In order to enter characters into the line, simply type them. The typed
|
| @@ -5743,7 +7313,7 @@ character to the left of the cursor.)
|
|
|
| File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
|
|
|
| -31.2.2 Readline Movement Commands
|
| +32.2.2 Readline Movement Commands
|
| ---------------------------------
|
|
|
| The above table describes the most basic keystrokes that you need in
|
| @@ -5774,7 +7344,7 @@ operate on characters while meta keystrokes operate on words.
|
|
|
| File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
|
|
|
| -31.2.3 Readline Killing Commands
|
| +32.2.3 Readline Killing Commands
|
| --------------------------------
|
|
|
| "Killing" text means to delete the text from the line, but to save it
|
| @@ -5827,7 +7397,7 @@ copy the most-recently-killed text from the kill buffer.
|
|
|
| File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
|
|
|
| -31.2.4 Readline Arguments
|
| +32.2.4 Readline Arguments
|
| -------------------------
|
|
|
| You can pass numeric arguments to Readline commands. Sometimes the
|
| @@ -5848,7 +7418,7 @@ will delete the next ten characters on the input line.
|
|
|
| File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
|
|
|
| -31.2.5 Searching for Commands in the History
|
| +32.2.5 Searching for Commands in the History
|
| --------------------------------------------
|
|
|
| Readline provides commands for searching through the command history
|
| @@ -5889,7 +7459,7 @@ typed by the user or be part of the contents of the current line.
|
|
|
| File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
|
|
|
| -31.3 Readline Init File
|
| +32.3 Readline Init File
|
| =======================
|
|
|
| Although the Readline library comes with a set of Emacs-like
|
| @@ -5918,7 +7488,7 @@ incorporating any changes that you might have made to it.
|
|
|
| File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
|
|
|
| -31.3.1 Readline Init File Syntax
|
| +32.3.1 Readline Init File Syntax
|
| --------------------------------
|
|
|
| There are only a few basic constructs allowed in the Readline init
|
| @@ -6281,7 +7851,7 @@ Key Bindings
|
|
|
| File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
|
|
|
| -31.3.2 Conditional Init Constructs
|
| +32.3.2 Conditional Init Constructs
|
| ----------------------------------
|
|
|
| Readline implements a facility similar in spirit to the conditional
|
| @@ -6341,7 +7911,7 @@ are four parser directives used.
|
|
|
| File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
|
|
|
| -31.3.3 Sample Init File
|
| +32.3.3 Sample Init File
|
| -----------------------
|
|
|
| Here is an example of an INPUTRC file. This illustrates key binding,
|
| @@ -6451,7 +8021,7 @@ variable assignment, and conditional syntax.
|
|
|
| File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
|
|
|
| -31.4 Bindable Readline Commands
|
| +32.4 Bindable Readline Commands
|
| ===============================
|
|
|
| * Menu:
|
| @@ -6477,7 +8047,7 @@ as the "region".
|
|
|
| File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
|
|
|
| -31.4.1 Commands For Moving
|
| +32.4.1 Commands For Moving
|
| --------------------------
|
|
|
| `beginning-of-line (C-a)'
|
| @@ -6511,7 +8081,7 @@ File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bi
|
|
|
| File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
|
|
|
| -31.4.2 Commands For Manipulating The History
|
| +32.4.2 Commands For Manipulating The History
|
| --------------------------------------------
|
|
|
| `accept-line (Newline or Return)'
|
| @@ -6589,7 +8159,7 @@ File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Co
|
|
|
| File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
|
|
|
| -31.4.3 Commands For Changing Text
|
| +32.4.3 Commands For Changing Text
|
| ---------------------------------
|
|
|
| `delete-char (C-d)'
|
| @@ -6657,7 +8227,7 @@ File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Co
|
|
|
| File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
|
|
|
| -31.4.4 Killing And Yanking
|
| +32.4.4 Killing And Yanking
|
| --------------------------
|
|
|
| `kill-line (C-k)'
|
| @@ -6723,7 +8293,7 @@ File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Co
|
|
|
| File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
|
|
|
| -31.4.5 Specifying Numeric Arguments
|
| +32.4.5 Specifying Numeric Arguments
|
| -----------------------------------
|
|
|
| `digit-argument (M-0, M-1, ... M--)'
|
| @@ -6746,7 +8316,7 @@ File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev:
|
|
|
| File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
|
|
|
| -31.4.6 Letting Readline Type For You
|
| +32.4.6 Letting Readline Type For You
|
| ------------------------------------
|
|
|
| `complete (<TAB>)'
|
| @@ -6792,7 +8362,7 @@ File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: N
|
|
|
| File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
|
|
|
| -31.4.7 Keyboard Macros
|
| +32.4.7 Keyboard Macros
|
| ----------------------
|
|
|
| `start-kbd-macro (C-x ()'
|
| @@ -6810,7 +8380,7 @@ File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Co
|
|
|
| File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
|
|
|
| -31.4.8 Some Miscellaneous Commands
|
| +32.4.8 Some Miscellaneous Commands
|
| ----------------------------------
|
|
|
| `re-read-init-file (C-x C-r)'
|
| @@ -6907,7 +8477,7 @@ File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bind
|
|
|
| File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
|
|
|
| -31.5 Readline vi Mode
|
| +32.5 Readline vi Mode
|
| =====================
|
|
|
| While the Readline library does not have a full set of `vi' editing
|
| @@ -6928,7 +8498,7 @@ the standard `vi' movement keys, move to previous history lines with
|
|
|
| File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top
|
|
|
| -32 Using History Interactively
|
| +33 Using History Interactively
|
| ******************************
|
|
|
| This chapter describes how to use the GNU History Library interactively,
|
| @@ -6944,7 +8514,7 @@ History.
|
|
|
| File: gdb.info, Node: History Interaction, Up: Using History Interactively
|
|
|
| -32.1 History Expansion
|
| +33.1 History Expansion
|
| ======================
|
|
|
| The History library provides a history expansion feature that is similar
|
| @@ -6976,7 +8546,7 @@ appearance of the history expansion character, which is `!' by default.
|
|
|
| File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
|
|
|
| -32.1.1 Event Designators
|
| +33.1.1 Event Designators
|
| ------------------------
|
|
|
| An event designator is a reference to a command line entry in the
|
| @@ -7016,7 +8586,7 @@ the current position in the history list.
|
|
|
| File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
|
|
|
| -32.1.2 Word Designators
|
| +33.1.2 Word Designators
|
| -----------------------
|
|
|
| Word designators are used to select desired words from the event. A
|
| @@ -7078,7 +8648,7 @@ previous command is used as the event.
|
|
|
| File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
|
|
|
| -32.1.3 Modifiers
|
| +33.1.3 Modifiers
|
| ----------------
|
|
|
| After the optional word designator, you can add a sequence of one or
|
| @@ -7174,7 +8744,7 @@ and TeX (or `texi2roff') to typeset the printed version.
|
|
|
| GDB includes an already formatted copy of the on-line Info version
|
| of this manual in the `gdb' subdirectory. The main Info file is
|
| -`gdb-7.4.1/gdb/gdb.info', and it refers to subordinate files matching
|
| +`gdb-7.5.1/gdb/gdb.info', and it refers to subordinate files matching
|
| `gdb.info*' in the same directory. If necessary, you can print out
|
| these files, or read them with any editor; but they are easier to read
|
| using the `info' subsystem in GNU Emacs or the standalone `info'
|
| @@ -7184,7 +8754,7 @@ program, available as part of the GNU Texinfo distribution.
|
| Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
|
|
|
| If you have `makeinfo' installed, and are in the top level GDB
|
| -source directory (`gdb-7.4.1', in the case of version 7.4.1), you can
|
| +source directory (`gdb-7.5.1', in the case of version 7.5.1), you can
|
| make the Info file by typing:
|
|
|
| cd gdb
|
| @@ -7210,7 +8780,7 @@ format. On its own, TeX cannot either read or typeset a Texinfo file.
|
|
|
| If you have TeX and a DVI printer program installed, you can typeset
|
| and print this manual. First switch to the `gdb' subdirectory of the
|
| -main source directory (for example, to `gdb-7.4.1/gdb') and type:
|
| +main source directory (for example, to `gdb-7.5.1/gdb') and type:
|
|
|
| make gdb.dvi
|
|
|
| @@ -7218,7 +8788,7 @@ main source directory (for example, to `gdb-7.4.1/gdb') and type:
|
|
|
| ---------- Footnotes ----------
|
|
|
| - (1) In `gdb-7.4.1/gdb/refcard.ps' of the version 7.4.1 release.
|
| + (1) In `gdb-7.5.1/gdb/refcard.ps' of the version 7.5.1 release.
|
|
|
|
|
| File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
|
| @@ -7311,1551 +8881,3 @@ iconv
|
| Libiconv, unpack it, and then rename the directory holding the
|
| Libiconv source code to `libiconv'.
|
|
|
| -
|
| -File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
|
| -
|
| -C.2 Invoking the GDB `configure' Script
|
| -=======================================
|
| -
|
| -GDB comes with a `configure' script that automates the process of
|
| -preparing GDB for installation; you can then use `make' to build the
|
| -`gdb' program.
|
| -
|
| - The GDB distribution includes all the source code you need for GDB
|
| -in a single directory, whose name is usually composed by appending the
|
| -version number to `gdb'.
|
| -
|
| - For example, the GDB version 7.4.1 distribution is in the
|
| -`gdb-7.4.1' directory. That directory contains:
|
| -
|
| -`gdb-7.4.1/configure (and supporting files)'
|
| - script for configuring GDB and all its supporting libraries
|
| -
|
| -`gdb-7.4.1/gdb'
|
| - the source specific to GDB itself
|
| -
|
| -`gdb-7.4.1/bfd'
|
| - source for the Binary File Descriptor library
|
| -
|
| -`gdb-7.4.1/include'
|
| - GNU include files
|
| -
|
| -`gdb-7.4.1/libiberty'
|
| - source for the `-liberty' free software library
|
| -
|
| -`gdb-7.4.1/opcodes'
|
| - source for the library of opcode tables and disassemblers
|
| -
|
| -`gdb-7.4.1/readline'
|
| - source for the GNU command-line interface
|
| -
|
| -`gdb-7.4.1/glob'
|
| - source for the GNU filename pattern-matching subroutine
|
| -
|
| -`gdb-7.4.1/mmalloc'
|
| - source for the GNU memory-mapped malloc package
|
| -
|
| - The simplest way to configure and build GDB is to run `configure'
|
| -from the `gdb-VERSION-NUMBER' source directory, which in this example
|
| -is the `gdb-7.4.1' directory.
|
| -
|
| - First switch to the `gdb-VERSION-NUMBER' source directory if you are
|
| -not already in it; then run `configure'. Pass the identifier for the
|
| -platform on which GDB will run as an argument.
|
| -
|
| - For example:
|
| -
|
| - cd gdb-7.4.1
|
| - ./configure HOST
|
| - make
|
| -
|
| -where HOST is an identifier such as `sun4' or `decstation', that
|
| -identifies the platform where GDB will run. (You can often leave off
|
| -HOST; `configure' tries to guess the correct value by examining your
|
| -system.)
|
| -
|
| - Running `configure HOST' and then running `make' builds the `bfd',
|
| -`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
|
| -The configured source files, and the binaries, are left in the
|
| -corresponding source directories.
|
| -
|
| - `configure' is a Bourne-shell (`/bin/sh') script; if your system
|
| -does not recognize this automatically when you run a different shell,
|
| -you may need to run `sh' on it explicitly:
|
| -
|
| - sh configure HOST
|
| -
|
| - If you run `configure' from a directory that contains source
|
| -directories for multiple libraries or programs, such as the `gdb-7.4.1'
|
| -source directory for version 7.4.1, `configure' creates configuration
|
| -files for every directory level underneath (unless you tell it not to,
|
| -with the `--norecursion' option).
|
| -
|
| - You should run the `configure' script from the top directory in the
|
| -source tree, the `gdb-VERSION-NUMBER' directory. If you run
|
| -`configure' from one of the subdirectories, you will configure only
|
| -that subdirectory. That is usually not what you want. In particular,
|
| -if you run the first `configure' from the `gdb' subdirectory of the
|
| -`gdb-VERSION-NUMBER' directory, you will omit the configuration of
|
| -`bfd', `readline', and other sibling directories of the `gdb'
|
| -subdirectory. This leads to build errors about missing include files
|
| -such as `bfd/bfd.h'.
|
| -
|
| - You can install `gdb' anywhere; it has no hardwired paths. However,
|
| -you should make sure that the shell on your path (named by the `SHELL'
|
| -environment variable) is publicly readable. Remember that GDB uses the
|
| -shell to start your program--some systems refuse to let GDB debug child
|
| -processes whose programs are not readable.
|
| -
|
| -
|
| -File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
|
| -
|
| -C.3 Compiling GDB in Another Directory
|
| -======================================
|
| -
|
| -If you want to run GDB versions for several host or target machines,
|
| -you need a different `gdb' compiled for each combination of host and
|
| -target. `configure' is designed to make this easy by allowing you to
|
| -generate each configuration in a separate subdirectory, rather than in
|
| -the source directory. If your `make' program handles the `VPATH'
|
| -feature (GNU `make' does), running `make' in each of these directories
|
| -builds the `gdb' program specified there.
|
| -
|
| - To build `gdb' in a separate directory, run `configure' with the
|
| -`--srcdir' option to specify where to find the source. (You also need
|
| -to specify a path to find `configure' itself from your working
|
| -directory. If the path to `configure' would be the same as the
|
| -argument to `--srcdir', you can leave out the `--srcdir' option; it is
|
| -assumed.)
|
| -
|
| - For example, with version 7.4.1, you can build GDB in a separate
|
| -directory for a Sun 4 like this:
|
| -
|
| - cd gdb-7.4.1
|
| - mkdir ../gdb-sun4
|
| - cd ../gdb-sun4
|
| - ../gdb-7.4.1/configure sun4
|
| - make
|
| -
|
| - When `configure' builds a configuration using a remote source
|
| -directory, it creates a tree for the binaries with the same structure
|
| -(and using the same names) as the tree under the source directory. In
|
| -the example, you'd find the Sun 4 library `libiberty.a' in the
|
| -directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
|
| -
|
| - Make sure that your path to the `configure' script has just one
|
| -instance of `gdb' in it. If your path to `configure' looks like
|
| -`../gdb-7.4.1/gdb/configure', you are configuring only one subdirectory
|
| -of GDB, not the whole package. This leads to build errors about
|
| -missing include files such as `bfd/bfd.h'.
|
| -
|
| - One popular reason to build several GDB configurations in separate
|
| -directories is to configure GDB for cross-compiling (where GDB runs on
|
| -one machine--the "host"--while debugging programs that run on another
|
| -machine--the "target"). You specify a cross-debugging target by giving
|
| -the `--target=TARGET' option to `configure'.
|
| -
|
| - When you run `make' to build a program or library, you must run it
|
| -in a configured directory--whatever directory you were in when you
|
| -called `configure' (or one of its subdirectories).
|
| -
|
| - The `Makefile' that `configure' generates in each source directory
|
| -also runs recursively. If you type `make' in a source directory such
|
| -as `gdb-7.4.1' (or in a separate configured directory configured with
|
| -`--srcdir=DIRNAME/gdb-7.4.1'), you will build all the required
|
| -libraries, and then build GDB.
|
| -
|
| - When you have multiple hosts or targets configured in separate
|
| -directories, you can run `make' on them in parallel (for example, if
|
| -they are NFS-mounted on each of the hosts); they will not interfere
|
| -with each other.
|
| -
|
| -
|
| -File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
|
| -
|
| -C.4 Specifying Names for Hosts and Targets
|
| -==========================================
|
| -
|
| -The specifications used for hosts and targets in the `configure' script
|
| -are based on a three-part naming scheme, but some short predefined
|
| -aliases are also supported. The full naming scheme encodes three pieces
|
| -of information in the following pattern:
|
| -
|
| - ARCHITECTURE-VENDOR-OS
|
| -
|
| - For example, you can use the alias `sun4' as a HOST argument, or as
|
| -the value for TARGET in a `--target=TARGET' option. The equivalent
|
| -full name is `sparc-sun-sunos4'.
|
| -
|
| - The `configure' script accompanying GDB does not provide any query
|
| -facility to list all supported host and target names or aliases.
|
| -`configure' calls the Bourne shell script `config.sub' to map
|
| -abbreviations to full names; you can read the script, if you wish, or
|
| -you can use it to test your guesses on abbreviations--for example:
|
| -
|
| - % sh config.sub i386-linux
|
| - i386-pc-linux-gnu
|
| - % sh config.sub alpha-linux
|
| - alpha-unknown-linux-gnu
|
| - % sh config.sub hp9k700
|
| - hppa1.1-hp-hpux
|
| - % sh config.sub sun4
|
| - sparc-sun-sunos4.1.1
|
| - % sh config.sub sun3
|
| - m68k-sun-sunos4.1.1
|
| - % sh config.sub i986v
|
| - Invalid configuration `i986v': machine `i986v' not recognized
|
| -
|
| -`config.sub' is also distributed in the GDB source directory
|
| -(`gdb-7.4.1', for version 7.4.1).
|
| -
|
| -
|
| -File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB
|
| -
|
| -C.5 `configure' Options
|
| -=======================
|
| -
|
| -Here is a summary of the `configure' options and arguments that are
|
| -most often useful for building GDB. `configure' also has several other
|
| -options not listed here. *note (configure.info)What Configure Does::,
|
| -for a full explanation of `configure'.
|
| -
|
| - configure [--help]
|
| - [--prefix=DIR]
|
| - [--exec-prefix=DIR]
|
| - [--srcdir=DIRNAME]
|
| - [--norecursion] [--rm]
|
| - [--target=TARGET]
|
| - HOST
|
| -
|
| -You may introduce options with a single `-' rather than `--' if you
|
| -prefer; but you may abbreviate option names if you use `--'.
|
| -
|
| -`--help'
|
| - Display a quick summary of how to invoke `configure'.
|
| -
|
| -`--prefix=DIR'
|
| - Configure the source to install programs and files under directory
|
| - `DIR'.
|
| -
|
| -`--exec-prefix=DIR'
|
| - Configure the source to install programs under directory `DIR'.
|
| -
|
| -`--srcdir=DIRNAME'
|
| - *Warning: using this option requires GNU `make', or another `make'
|
| - that implements the `VPATH' feature.*
|
| - Use this option to make configurations in directories separate
|
| - from the GDB source directories. Among other things, you can use
|
| - this to build (or maintain) several configurations simultaneously,
|
| - in separate directories. `configure' writes
|
| - configuration-specific files in the current directory, but
|
| - arranges for them to use the source in the directory DIRNAME.
|
| - `configure' creates directories under the working directory in
|
| - parallel to the source directories below DIRNAME.
|
| -
|
| -`--norecursion'
|
| - Configure only the directory level where `configure' is executed;
|
| - do not propagate configuration to subdirectories.
|
| -
|
| -`--target=TARGET'
|
| - Configure GDB for cross-debugging programs running on the specified
|
| - TARGET. Without this option, GDB is configured to debug programs
|
| - that run on the same machine (HOST) as GDB itself.
|
| -
|
| - There is no convenient way to generate a list of all available
|
| - targets.
|
| -
|
| -`HOST ...'
|
| - Configure GDB to run on the specified HOST.
|
| -
|
| - There is no convenient way to generate a list of all available
|
| - hosts.
|
| -
|
| - There are many other options available as well, but they are
|
| -generally needed for special purposes only.
|
| -
|
| -
|
| -File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB
|
| -
|
| -C.6 System-wide configuration and settings
|
| -==========================================
|
| -
|
| -GDB can be configured to have a system-wide init file; this file will
|
| -be read and executed at startup (*note What GDB does during startup:
|
| -Startup.).
|
| -
|
| - Here is the corresponding configure option:
|
| -
|
| -`--with-system-gdbinit=FILE'
|
| - Specify that the default location of the system-wide init file is
|
| - FILE.
|
| -
|
| - If GDB has been configured with the option `--prefix=$prefix', it
|
| -may be subject to relocation. Two possible cases:
|
| -
|
| - * If the default location of this init file contains `$prefix', it
|
| - will be subject to relocation. Suppose that the configure options
|
| - are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
|
| - if GDB is moved from `$prefix' to `$install', the system init file
|
| - is looked for as `$install/etc/gdbinit' instead of
|
| - `$prefix/etc/gdbinit'.
|
| -
|
| - * By contrast, if the default location does not contain the prefix,
|
| - it will not be relocated. E.g. if GDB has been configured with
|
| - `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
|
| - then GDB will always look for `/usr/share/gdb/gdbinit', wherever
|
| - GDB is installed.
|
| -
|
| -
|
| -File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
|
| -
|
| -Appendix D Maintenance Commands
|
| -*******************************
|
| -
|
| -In addition to commands intended for GDB users, GDB includes a number
|
| -of commands intended for GDB developers, that are not documented
|
| -elsewhere in this manual. These commands are provided here for
|
| -reference. (For commands that turn on debugging messages, see *Note
|
| -Debugging Output::.)
|
| -
|
| -`maint agent EXPRESSION'
|
| -`maint agent-eval EXPRESSION'
|
| - Translate the given EXPRESSION into remote agent bytecodes. This
|
| - command is useful for debugging the Agent Expression mechanism
|
| - (*note Agent Expressions::). The `agent' version produces an
|
| - expression useful for data collection, such as by tracepoints,
|
| - while `maint agent-eval' produces an expression that evaluates
|
| - directly to a result. For instance, a collection expression for
|
| - `globa + globb' will include bytecodes to record four bytes of
|
| - memory at each of the addresses of `globa' and `globb', while
|
| - discarding the result of the addition, while an evaluation
|
| - expression will do the addition and return the sum.
|
| -
|
| -`maint info breakpoints'
|
| - Using the same format as `info breakpoints', display both the
|
| - breakpoints you've set explicitly, and those GDB is using for
|
| - internal purposes. Internal breakpoints are shown with negative
|
| - breakpoint numbers. The type column identifies what kind of
|
| - breakpoint is shown:
|
| -
|
| - `breakpoint'
|
| - Normal, explicitly set breakpoint.
|
| -
|
| - `watchpoint'
|
| - Normal, explicitly set watchpoint.
|
| -
|
| - `longjmp'
|
| - Internal breakpoint, used to handle correctly stepping through
|
| - `longjmp' calls.
|
| -
|
| - `longjmp resume'
|
| - Internal breakpoint at the target of a `longjmp'.
|
| -
|
| - `until'
|
| - Temporary internal breakpoint used by the GDB `until' command.
|
| -
|
| - `finish'
|
| - Temporary internal breakpoint used by the GDB `finish'
|
| - command.
|
| -
|
| - `shlib events'
|
| - Shared library events.
|
| -
|
| -
|
| -`set displaced-stepping'
|
| -`show displaced-stepping'
|
| - Control whether or not GDB will do "displaced stepping" if the
|
| - target supports it. Displaced stepping is a way to single-step
|
| - over breakpoints without removing them from the inferior, by
|
| - executing an out-of-line copy of the instruction that was
|
| - originally at the breakpoint location. It is also known as
|
| - out-of-line single-stepping.
|
| -
|
| - `set displaced-stepping on'
|
| - If the target architecture supports it, GDB will use
|
| - displaced stepping to step over breakpoints.
|
| -
|
| - `set displaced-stepping off'
|
| - GDB will not use displaced stepping to step over breakpoints,
|
| - even if such is supported by the target architecture.
|
| -
|
| - `set displaced-stepping auto'
|
| - This is the default mode. GDB will use displaced stepping
|
| - only if non-stop mode is active (*note Non-Stop Mode::) and
|
| - the target architecture supports displaced stepping.
|
| -
|
| -`maint check-symtabs'
|
| - Check the consistency of psymtabs and symtabs.
|
| -
|
| -`maint cplus first_component NAME'
|
| - Print the first C++ class/namespace component of NAME.
|
| -
|
| -`maint cplus namespace'
|
| - Print the list of possible C++ namespaces.
|
| -
|
| -`maint demangle NAME'
|
| - Demangle a C++ or Objective-C mangled NAME.
|
| -
|
| -`maint deprecate COMMAND [REPLACEMENT]'
|
| -`maint undeprecate COMMAND'
|
| - Deprecate or undeprecate the named COMMAND. Deprecated commands
|
| - cause GDB to issue a warning when you use them. The optional
|
| - argument REPLACEMENT says which newer command should be used in
|
| - favor of the deprecated one; if it is given, GDB will mention the
|
| - replacement as part of the warning.
|
| -
|
| -`maint dump-me'
|
| - Cause a fatal signal in the debugger and force it to dump its core.
|
| - This is supported only on systems which support aborting a program
|
| - with the `SIGQUIT' signal.
|
| -
|
| -`maint internal-error [MESSAGE-TEXT]'
|
| -`maint internal-warning [MESSAGE-TEXT]'
|
| - Cause GDB to call the internal function `internal_error' or
|
| - `internal_warning' and hence behave as though an internal error or
|
| - internal warning has been detected. In addition to reporting the
|
| - internal problem, these functions give the user the opportunity to
|
| - either quit GDB or create a core file of the current GDB session.
|
| -
|
| - These commands take an optional parameter MESSAGE-TEXT that is
|
| - used as the text of the error or warning message.
|
| -
|
| - Here's an example of using `internal-error':
|
| -
|
| - (gdb) maint internal-error testing, 1, 2
|
| - .../maint.c:121: internal-error: testing, 1, 2
|
| - A problem internal to GDB has been detected. Further
|
| - debugging may prove unreliable.
|
| - Quit this debugging session? (y or n) n
|
| - Create a core file? (y or n) n
|
| - (gdb)
|
| -
|
| -`maint set internal-error ACTION [ask|yes|no]'
|
| -`maint show internal-error ACTION'
|
| -`maint set internal-warning ACTION [ask|yes|no]'
|
| -`maint show internal-warning ACTION'
|
| - When GDB reports an internal problem (error or warning) it gives
|
| - the user the opportunity to both quit GDB and create a core file
|
| - of the current GDB session. These commands let you override the
|
| - default behaviour for each particular ACTION, described in the
|
| - table below.
|
| -
|
| - `quit'
|
| - You can specify that GDB should always (yes) or never (no)
|
| - quit. The default is to ask the user what to do.
|
| -
|
| - `corefile'
|
| - You can specify that GDB should always (yes) or never (no)
|
| - create a core file. The default is to ask the user what to
|
| - do.
|
| -
|
| -`maint packet TEXT'
|
| - If GDB is talking to an inferior via the serial protocol, then
|
| - this command sends the string TEXT to the inferior, and displays
|
| - the response packet. GDB supplies the initial `$' character, the
|
| - terminating `#' character, and the checksum.
|
| -
|
| -`maint print architecture [FILE]'
|
| - Print the entire architecture configuration. The optional argument
|
| - FILE names the file where the output goes.
|
| -
|
| -`maint print c-tdesc'
|
| - Print the current target description (*note Target Descriptions::)
|
| - as a C source file. The created source file can be used in GDB
|
| - when an XML parser is not available to parse the description.
|
| -
|
| -`maint print dummy-frames'
|
| - Prints the contents of GDB's internal dummy-frame stack.
|
| -
|
| - (gdb) b add
|
| - ...
|
| - (gdb) print add(2,3)
|
| - Breakpoint 2, add (a=2, b=3) at ...
|
| - 58 return (a + b);
|
| - The program being debugged stopped while in a function called from GDB.
|
| - ...
|
| - (gdb) maint print dummy-frames
|
| - 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
|
| - top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
|
| - call_lo=0x01014000 call_hi=0x01014001
|
| - (gdb)
|
| -
|
| - Takes an optional file parameter.
|
| -
|
| -`maint print registers [FILE]'
|
| -`maint print raw-registers [FILE]'
|
| -`maint print cooked-registers [FILE]'
|
| -`maint print register-groups [FILE]'
|
| -`maint print remote-registers [FILE]'
|
| - Print GDB's internal register data structures.
|
| -
|
| - The command `maint print raw-registers' includes the contents of
|
| - the raw register cache; the command `maint print cooked-registers'
|
| - includes the (cooked) value of all registers, including registers
|
| - which aren't available on the target nor visible to user; the
|
| - command `maint print register-groups' includes the groups that
|
| - each register is a member of; and the command `maint print
|
| - remote-registers' includes the remote target's register numbers
|
| - and offsets in the `G' packets. *Note Registers:
|
| - (gdbint)Registers.
|
| -
|
| - These commands take an optional parameter, a file name to which to
|
| - write the information.
|
| -
|
| -`maint print reggroups [FILE]'
|
| - Print GDB's internal register group data structures. The optional
|
| - argument FILE tells to what file to write the information.
|
| -
|
| - The register groups info looks like this:
|
| -
|
| - (gdb) maint print reggroups
|
| - Group Type
|
| - general user
|
| - float user
|
| - all user
|
| - vector user
|
| - system user
|
| - save internal
|
| - restore internal
|
| -
|
| -`flushregs'
|
| - This command forces GDB to flush its internal register cache.
|
| -
|
| -`maint print objfiles'
|
| - Print a dump of all known object files. For each object file, this
|
| - command prints its name, address in memory, and all of its psymtabs
|
| - and symtabs.
|
| -
|
| -`maint print section-scripts [REGEXP]'
|
| - Print a dump of scripts specified in the `.debug_gdb_section'
|
| - section. If REGEXP is specified, only print scripts loaded by
|
| - object files matching REGEXP. For each script, this command
|
| - prints its name as specified in the objfile, and the full path if
|
| - known. *Note .debug_gdb_scripts section::.
|
| -
|
| -`maint print statistics'
|
| - This command prints, for each object file in the program, various
|
| - data about that object file followed by the byte cache ("bcache")
|
| - statistics for the object file. The objfile data includes the
|
| - number of minimal, partial, full, and stabs symbols, the number of
|
| - types defined by the objfile, the number of as yet unexpanded psym
|
| - tables, the number of line tables and string tables, and the
|
| - amount of memory used by the various tables. The bcache
|
| - statistics include the counts, sizes, and counts of duplicates of
|
| - all and unique objects, max, average, and median entry size, total
|
| - memory used and its overhead and savings, and various measures of
|
| - the hash table size and chain lengths.
|
| -
|
| -`maint print target-stack'
|
| - A "target" is an interface between the debugger and a particular
|
| - kind of file or process. Targets can be stacked in "strata", so
|
| - that more than one target can potentially respond to a request.
|
| - In particular, memory accesses will walk down the stack of targets
|
| - until they find a target that is interested in handling that
|
| - particular address.
|
| -
|
| - This command prints a short description of each layer that was
|
| - pushed on the "target stack", starting from the top layer down to
|
| - the bottom one.
|
| -
|
| -`maint print type EXPR'
|
| - Print the type chain for a type specified by EXPR. The argument
|
| - can be either a type name or a symbol. If it is a symbol, the
|
| - type of that symbol is described. The type chain produced by this
|
| - command is a recursive definition of the data type as stored in
|
| - GDB's data structures, including its flags and contained types.
|
| -
|
| -`maint set dwarf2 always-disassemble'
|
| -
|
| -`maint show dwarf2 always-disassemble'
|
| - Control the behavior of `info address' when using DWARF debugging
|
| - information.
|
| -
|
| - The default is `off', which means that GDB should try to describe
|
| - a variable's location in an easily readable format. When `on',
|
| - GDB will instead display the DWARF location expression in an
|
| - assembly-like format. Note that some locations are too complex
|
| - for GDB to describe simply; in this case you will always see the
|
| - disassembly form.
|
| -
|
| - Here is an example of the resulting disassembly:
|
| -
|
| - (gdb) info addr argc
|
| - Symbol "argc" is a complex DWARF expression:
|
| - 1: DW_OP_fbreg 0
|
| -
|
| - For more information on these expressions, see the DWARF standard
|
| - (http://www.dwarfstd.org/).
|
| -
|
| -`maint set dwarf2 max-cache-age'
|
| -`maint show dwarf2 max-cache-age'
|
| - Control the DWARF 2 compilation unit cache.
|
| -
|
| - In object files with inter-compilation-unit references, such as
|
| - those produced by the GCC option `-feliminate-dwarf2-dups', the
|
| - DWARF 2 reader needs to frequently refer to previously read
|
| - compilation units. This setting controls how long a compilation
|
| - unit will remain in the cache if it is not referenced. A higher
|
| - limit means that cached compilation units will be stored in memory
|
| - longer, and more total memory will be used. Setting it to zero
|
| - disables caching, which will slow down GDB startup, but reduce
|
| - memory consumption.
|
| -
|
| -`maint set profile'
|
| -`maint show profile'
|
| - Control profiling of GDB.
|
| -
|
| - Profiling will be disabled until you use the `maint set profile'
|
| - command to enable it. When you enable profiling, the system will
|
| - begin collecting timing and execution count data; when you disable
|
| - profiling or exit GDB, the results will be written to a log file.
|
| - Remember that if you use profiling, GDB will overwrite the
|
| - profiling log file (often called `gmon.out'). If you have a
|
| - record of important profiling data in a `gmon.out' file, be sure
|
| - to move it to a safe location.
|
| -
|
| - Configuring with `--enable-profiling' arranges for GDB to be
|
| - compiled with the `-pg' compiler option.
|
| -
|
| -`maint set show-debug-regs'
|
| -`maint show show-debug-regs'
|
| - Control whether to show variables that mirror the hardware debug
|
| - registers. Use `ON' to enable, `OFF' to disable. If enabled, the
|
| - debug registers values are shown when GDB inserts or removes a
|
| - hardware breakpoint or watchpoint, and when the inferior triggers
|
| - a hardware-assisted breakpoint or watchpoint.
|
| -
|
| -`maint set show-all-tib'
|
| -`maint show show-all-tib'
|
| - Control whether to show all non zero areas within a 1k block
|
| - starting at thread local base, when using the `info w32
|
| - thread-information-block' command.
|
| -
|
| -`maint space'
|
| - Control whether to display memory usage for each command. If set
|
| - to a nonzero value, GDB will display how much memory each command
|
| - took, following the command's own output. This can also be
|
| - requested by invoking GDB with the `--statistics' command-line
|
| - switch (*note Mode Options::).
|
| -
|
| -`maint time'
|
| - Control whether to display the execution time of GDB for each
|
| - command. If set to a nonzero value, GDB will display how much
|
| - time it took to execute each command, following the command's own
|
| - output. Both CPU time and wallclock time are printed. Printing
|
| - both is useful when trying to determine whether the cost is CPU
|
| - or, e.g., disk/network, latency. Note that the CPU time printed
|
| - is for GDB only, it does not include the execution time of the
|
| - inferior because there's no mechanism currently to compute how
|
| - much time was spent by GDB and how much time was spent by the
|
| - program been debugged. This can also be requested by invoking GDB
|
| - with the `--statistics' command-line switch (*note Mode Options::).
|
| -
|
| -`maint translate-address [SECTION] ADDR'
|
| - Find the symbol stored at the location specified by the address
|
| - ADDR and an optional section name SECTION. If found, GDB prints
|
| - the name of the closest symbol and an offset from the symbol's
|
| - location to the specified address. This is similar to the `info
|
| - address' command (*note Symbols::), except that this command also
|
| - allows to find symbols in other sections.
|
| -
|
| - If section was not specified, the section in which the symbol was
|
| - found is also printed. For dynamically linked executables, the
|
| - name of executable or shared library containing the symbol is
|
| - printed as well.
|
| -
|
| -
|
| - The following command is useful for non-interactive invocations of
|
| -GDB, such as in the test suite.
|
| -
|
| -`set watchdog NSEC'
|
| - Set the maximum number of seconds GDB will wait for the target
|
| - operation to finish. If this time expires, GDB reports and error
|
| - and the command is aborted.
|
| -
|
| -`show watchdog'
|
| - Show the current setting of the target wait timeout.
|
| -
|
| -
|
| -File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top
|
| -
|
| -Appendix E GDB Remote Serial Protocol
|
| -*************************************
|
| -
|
| -* Menu:
|
| -
|
| -* Overview::
|
| -* Packets::
|
| -* Stop Reply Packets::
|
| -* General Query Packets::
|
| -* Architecture-Specific Protocol Details::
|
| -* Tracepoint Packets::
|
| -* Host I/O Packets::
|
| -* Interrupts::
|
| -* Notification Packets::
|
| -* Remote Non-Stop::
|
| -* Packet Acknowledgment::
|
| -* Examples::
|
| -* File-I/O Remote Protocol Extension::
|
| -* Library List Format::
|
| -* Library List Format for SVR4 Targets::
|
| -* Memory Map Format::
|
| -* Thread List Format::
|
| -* Traceframe Info Format::
|
| -
|
| -
|
| -File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol
|
| -
|
| -E.1 Overview
|
| -============
|
| -
|
| -There may be occasions when you need to know something about the
|
| -protocol--for example, if there is only one serial port to your target
|
| -machine, you might want your program to do something special if it
|
| -recognizes a packet meant for GDB.
|
| -
|
| - In the examples below, `->' and `<-' are used to indicate
|
| -transmitted and received data, respectively.
|
| -
|
| - All GDB commands and responses (other than acknowledgments and
|
| -notifications, see *Note Notification Packets::) are sent as a PACKET.
|
| -A PACKET is introduced with the character `$', the actual PACKET-DATA,
|
| -and the terminating character `#' followed by a two-digit CHECKSUM:
|
| -
|
| - `$'PACKET-DATA`#'CHECKSUM
|
| - The two-digit CHECKSUM is computed as the modulo 256 sum of all
|
| -characters between the leading `$' and the trailing `#' (an eight bit
|
| -unsigned checksum).
|
| -
|
| - Implementors should note that prior to GDB 5.0 the protocol
|
| -specification also included an optional two-digit SEQUENCE-ID:
|
| -
|
| - `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
|
| -
|
| -That SEQUENCE-ID was appended to the acknowledgment. GDB has never
|
| -output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0
|
| -must not accept SEQUENCE-ID.
|
| -
|
| - When either the host or the target machine receives a packet, the
|
| -first response expected is an acknowledgment: either `+' (to indicate
|
| -the package was received correctly) or `-' (to request retransmission):
|
| -
|
| - -> `$'PACKET-DATA`#'CHECKSUM
|
| - <- `+'
|
| - The `+'/`-' acknowledgments can be disabled once a connection is
|
| -established. *Note Packet Acknowledgment::, for details.
|
| -
|
| - The host (GDB) sends COMMANDs, and the target (the debugging stub
|
| -incorporated in your program) sends a RESPONSE. In the case of step
|
| -and continue COMMANDs, the response is only sent when the operation has
|
| -completed, and the target has again stopped all threads in all attached
|
| -processes. This is the default all-stop mode behavior, but the remote
|
| -protocol also supports GDB's non-stop execution mode; see *Note Remote
|
| -Non-Stop::, for details.
|
| -
|
| - PACKET-DATA consists of a sequence of characters with the exception
|
| -of `#' and `$' (see `X' packet for additional exceptions).
|
| -
|
| - Fields within the packet should be separated using `,' `;' or `:'.
|
| -Except where otherwise noted all numbers are represented in HEX with
|
| -leading zeros suppressed.
|
| -
|
| - Implementors should note that prior to GDB 5.0, the character `:'
|
| -could not appear as the third character in a packet (as it would
|
| -potentially conflict with the SEQUENCE-ID).
|
| -
|
| - Binary data in most packets is encoded either as two hexadecimal
|
| -digits per byte of binary data. This allowed the traditional remote
|
| -protocol to work over connections which were only seven-bit clean.
|
| -Some packets designed more recently assume an eight-bit clean
|
| -connection, and use a more efficient encoding to send and receive
|
| -binary data.
|
| -
|
| - The binary data representation uses `7d' (ASCII `}') as an escape
|
| -character. Any escaped byte is transmitted as the escape character
|
| -followed by the original character XORed with `0x20'. For example, the
|
| -byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The
|
| -bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
|
| -must always be escaped. Responses sent by the stub must also escape
|
| -`0x2a' (ASCII `*'), so that it is not interpreted as the start of a
|
| -run-length encoded sequence (described next).
|
| -
|
| - Response DATA can be run-length encoded to save space. Run-length
|
| -encoding replaces runs of identical characters with one instance of the
|
| -repeated character, followed by a `*' and a repeat count. The repeat
|
| -count is itself sent encoded, to avoid binary characters in DATA: a
|
| -value of N is sent as `N+29'. For a repeat count greater or equal to
|
| -3, this produces a printable ASCII character, e.g. a space (ASCII code
|
| -32) for a repeat count of 3. (This is because run-length encoding
|
| -starts to win for counts 3 or more.) Thus, for example, `0* ' is a
|
| -run-length encoding of "0000": the space character after `*' means
|
| -repeat the leading `0' `32 - 29 = 3' more times.
|
| -
|
| - The printable characters `#' and `$' or with a numeric value greater
|
| -than 126 must not be used. Runs of six repeats (`#') or seven repeats
|
| -(`$') can be expanded using a repeat count of only five (`"'). For
|
| -example, `00000000' can be encoded as `0*"00'.
|
| -
|
| - The error response returned for some packets includes a two character
|
| -error number. That number is not well defined.
|
| -
|
| - For any COMMAND not supported by the stub, an empty response
|
| -(`$#00') should be returned. That way it is possible to extend the
|
| -protocol. A newer GDB can tell if a packet is supported based on that
|
| -response.
|
| -
|
| - At a minimum, a stub is required to support the `g' and `G' commands
|
| -for register access, and the `m' and `M' commands for memory access.
|
| -Stubs that only control single-threaded targets can implement run
|
| -control with the `c' (continue), and `s' (step) commands. Stubs that
|
| -support multi-threading targets should support the `vCont' command.
|
| -All other commands are optional.
|
| -
|
| -
|
| -File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol
|
| -
|
| -E.2 Packets
|
| -===========
|
| -
|
| -The following table provides a complete list of all currently defined
|
| -COMMANDs and their corresponding response DATA. *Note File-I/O Remote
|
| -Protocol Extension::, for details about the File I/O extension of the
|
| -remote protocol.
|
| -
|
| - Each packet's description has a template showing the packet's overall
|
| -syntax, followed by an explanation of the packet's meaning. We include
|
| -spaces in some of the templates for clarity; these are not part of the
|
| -packet's syntax. No GDB packet uses spaces to separate its components.
|
| -For example, a template like `foo BAR BAZ' describes a packet
|
| -beginning with the three ASCII bytes `foo', followed by a BAR, followed
|
| -directly by a BAZ. GDB does not transmit a space character between the
|
| -`foo' and the BAR, or between the BAR and the BAZ.
|
| -
|
| - Several packets and replies include a THREAD-ID field to identify a
|
| -thread. Normally these are positive numbers with a target-specific
|
| -interpretation, formatted as big-endian hex strings. A THREAD-ID can
|
| -also be a literal `-1' to indicate all threads, or `0' to pick any
|
| -thread.
|
| -
|
| - In addition, the remote protocol supports a multiprocess feature in
|
| -which the THREAD-ID syntax is extended to optionally include both
|
| -process and thread ID fields, as `pPID.TID'. The PID (process) and TID
|
| -(thread) components each have the format described above: a positive
|
| -number with target-specific interpretation formatted as a big-endian
|
| -hex string, literal `-1' to indicate all processes or threads
|
| -(respectively), or `0' to indicate an arbitrary process or thread.
|
| -Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It
|
| -is an error to specify all processes but a specific thread, such as
|
| -`p-1.TID'. Note that the `p' prefix is _not_ used for those packets
|
| -and replies explicitly documented to include a process ID, rather than
|
| -a THREAD-ID.
|
| -
|
| - The multiprocess THREAD-ID syntax extensions are only used if both
|
| -GDB and the stub report support for the `multiprocess' feature using
|
| -`qSupported'. *Note multiprocess extensions::, for more information.
|
| -
|
| - Note that all packet forms beginning with an upper- or lower-case
|
| -letter, other than those described here, are reserved for future use.
|
| -
|
| - Here are the packet descriptions.
|
| -
|
| -`!'
|
| - Enable extended mode. In extended mode, the remote server is made
|
| - persistent. The `R' packet is used to restart the program being
|
| - debugged.
|
| -
|
| - Reply:
|
| - `OK'
|
| - The remote target both supports and has enabled extended mode.
|
| -
|
| -`?'
|
| - Indicate the reason the target halted. The reply is the same as
|
| - for step and continue. This packet has a special interpretation
|
| - when the target is in non-stop mode; see *Note Remote Non-Stop::.
|
| -
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| -
|
| -`A ARGLEN,ARGNUM,ARG,...'
|
| - Initialized `argv[]' array passed into program. ARGLEN specifies
|
| - the number of bytes in the hex encoded byte stream ARG. See
|
| - `gdbserver' for more details.
|
| -
|
| - Reply:
|
| - `OK'
|
| - The arguments were set.
|
| -
|
| - `E NN'
|
| - An error occurred.
|
| -
|
| -`b BAUD'
|
| - (Don't use this packet; its behavior is not well-defined.) Change
|
| - the serial line speed to BAUD.
|
| -
|
| - JTC: _When does the transport layer state change? When it's
|
| - received, or after the ACK is transmitted. In either case, there
|
| - are problems if the command or the acknowledgment packet is
|
| - dropped._
|
| -
|
| - Stan: _If people really wanted to add something like this, and get
|
| - it working for the first time, they ought to modify ser-unix.c to
|
| - send some kind of out-of-band message to a specially-setup stub
|
| - and have the switch happen "in between" packets, so that from
|
| - remote protocol's point of view, nothing actually happened._
|
| -
|
| -`B ADDR,MODE'
|
| - Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
|
| -
|
| - Don't use this packet. Use the `Z' and `z' packets instead (*note
|
| - insert breakpoint or watchpoint packet::).
|
| -
|
| -`bc'
|
| - Backward continue. Execute the target system in reverse. No
|
| - parameter. *Note Reverse Execution::, for more information.
|
| -
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| -
|
| -`bs'
|
| - Backward single step. Execute one instruction in reverse. No
|
| - parameter. *Note Reverse Execution::, for more information.
|
| -
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| -
|
| -`c [ADDR]'
|
| - Continue. ADDR is address to resume. If ADDR is omitted, resume
|
| - at current address.
|
| -
|
| - This packet is deprecated for multi-threading support. *Note
|
| - vCont packet::.
|
| -
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| -
|
| -`C SIG[;ADDR]'
|
| - Continue with signal SIG (hex signal number). If `;ADDR' is
|
| - omitted, resume at same address.
|
| -
|
| - This packet is deprecated for multi-threading support. *Note
|
| - vCont packet::.
|
| -
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| -
|
| -`d'
|
| - Toggle debug flag.
|
| -
|
| - Don't use this packet; instead, define a general set packet (*note
|
| - General Query Packets::).
|
| -
|
| -`D'
|
| -`D;PID'
|
| - The first form of the packet is used to detach GDB from the remote
|
| - system. It is sent to the remote target before GDB disconnects
|
| - via the `detach' command.
|
| -
|
| - The second form, including a process ID, is used when multiprocess
|
| - protocol extensions are enabled (*note multiprocess extensions::),
|
| - to detach only a specific process. The PID is specified as a
|
| - big-endian hex string.
|
| -
|
| - Reply:
|
| - `OK'
|
| - for success
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`F RC,EE,CF;XX'
|
| - A reply from GDB to an `F' packet sent by the target. This is
|
| - part of the File-I/O protocol extension. *Note File-I/O Remote
|
| - Protocol Extension::, for the specification.
|
| -
|
| -`g'
|
| - Read general registers.
|
| -
|
| - Reply:
|
| - `XX...'
|
| - Each byte of register data is described by two hex digits.
|
| - The bytes with the register are transmitted in target byte
|
| - order. The size of each register and their position within
|
| - the `g' packet are determined by the GDB internal gdbarch
|
| - functions `DEPRECATED_REGISTER_RAW_SIZE' and
|
| - `gdbarch_register_name'. The specification of several
|
| - standard `g' packets is specified below.
|
| -
|
| - When reading registers from a trace frame (*note Using the
|
| - Collected Data: Analyze Collected Data.), the stub may also
|
| - return a string of literal `x''s in place of the register
|
| - data digits, to indicate that the corresponding register has
|
| - not been collected, thus its value is unavailable. For
|
| - example, for an architecture with 4 registers of 4 bytes
|
| - each, the following reply indicates to GDB that registers 0
|
| - and 2 have not been collected, while registers 1 and 3 have
|
| - been collected, and both have zero value:
|
| -
|
| - -> `g'
|
| - <- `xxxxxxxx00000000xxxxxxxx00000000'
|
| -
|
| - `E NN'
|
| - for an error.
|
| -
|
| -`G XX...'
|
| - Write general registers. *Note read registers packet::, for a
|
| - description of the XX... data.
|
| -
|
| - Reply:
|
| - `OK'
|
| - for success
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`H OP THREAD-ID'
|
| - Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
|
| - OP depends on the operation to be performed: it should be `c' for
|
| - step and continue operations (note that this is deprecated,
|
| - supporting the `vCont' command is a better option), `g' for other
|
| - operations. The thread designator THREAD-ID has the format and
|
| - interpretation described in *Note thread-id syntax::.
|
| -
|
| - Reply:
|
| - `OK'
|
| - for success
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`i [ADDR[,NNN]]'
|
| - Step the remote target by a single clock cycle. If `,NNN' is
|
| - present, cycle step NNN cycles. If ADDR is present, cycle step
|
| - starting at that address.
|
| -
|
| -`I'
|
| - Signal, then cycle step. *Note step with signal packet::. *Note
|
| - cycle step packet::.
|
| -
|
| -`k'
|
| - Kill request.
|
| -
|
| - FIXME: _There is no description of how to operate when a specific
|
| - thread context has been selected (i.e. does 'k' kill only that
|
| - thread?)_.
|
| -
|
| -`m ADDR,LENGTH'
|
| - Read LENGTH bytes of memory starting at address ADDR. Note that
|
| - ADDR may not be aligned to any particular boundary.
|
| -
|
| - The stub need not use any particular size or alignment when
|
| - gathering data from memory for the response; even if ADDR is
|
| - word-aligned and LENGTH is a multiple of the word size, the stub
|
| - is free to use byte accesses, or not. For this reason, this
|
| - packet may not be suitable for accessing memory-mapped I/O devices.
|
| -
|
| - Reply:
|
| - `XX...'
|
| - Memory contents; each byte is transmitted as a two-digit
|
| - hexadecimal number. The reply may contain fewer bytes than
|
| - requested if the server was able to read only part of the
|
| - region of memory.
|
| -
|
| - `E NN'
|
| - NN is errno
|
| -
|
| -`M ADDR,LENGTH:XX...'
|
| - Write LENGTH bytes of memory starting at address ADDR. XX... is
|
| - the data; each byte is transmitted as a two-digit hexadecimal
|
| - number.
|
| -
|
| - Reply:
|
| - `OK'
|
| - for success
|
| -
|
| - `E NN'
|
| - for an error (this includes the case where only part of the
|
| - data was written).
|
| -
|
| -`p N'
|
| - Read the value of register N; N is in hex. *Note read registers
|
| - packet::, for a description of how the returned register value is
|
| - encoded.
|
| -
|
| - Reply:
|
| - `XX...'
|
| - the register's value
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| - `'
|
| - Indicating an unrecognized QUERY.
|
| -
|
| -`P N...=R...'
|
| - Write register N... with value R.... The register number N is in
|
| - hexadecimal, and R... contains two hex digits for each byte in the
|
| - register (target byte order).
|
| -
|
| - Reply:
|
| - `OK'
|
| - for success
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`q NAME PARAMS...'
|
| -`Q NAME PARAMS...'
|
| - General query (`q') and set (`Q'). These packets are described
|
| - fully in *Note General Query Packets::.
|
| -
|
| -`r'
|
| - Reset the entire system.
|
| -
|
| - Don't use this packet; use the `R' packet instead.
|
| -
|
| -`R XX'
|
| - Restart the program being debugged. XX, while needed, is ignored.
|
| - This packet is only available in extended mode (*note extended
|
| - mode::).
|
| -
|
| - The `R' packet has no reply.
|
| -
|
| -`s [ADDR]'
|
| - Single step. ADDR is the address at which to resume. If ADDR is
|
| - omitted, resume at same address.
|
| -
|
| - This packet is deprecated for multi-threading support. *Note
|
| - vCont packet::.
|
| -
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| -
|
| -`S SIG[;ADDR]'
|
| - Step with signal. This is analogous to the `C' packet, but
|
| - requests a single-step, rather than a normal resumption of
|
| - execution.
|
| -
|
| - This packet is deprecated for multi-threading support. *Note
|
| - vCont packet::.
|
| -
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| -
|
| -`t ADDR:PP,MM'
|
| - Search backwards starting at address ADDR for a match with pattern
|
| - PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3
|
| - digits.
|
| -
|
| -`T THREAD-ID'
|
| - Find out if the thread THREAD-ID is alive. *Note thread-id
|
| - syntax::.
|
| -
|
| - Reply:
|
| - `OK'
|
| - thread is still alive
|
| -
|
| - `E NN'
|
| - thread is dead
|
| -
|
| -`v'
|
| - Packets starting with `v' are identified by a multi-letter name,
|
| - up to the first `;' or `?' (or the end of the packet).
|
| -
|
| -`vAttach;PID'
|
| - Attach to a new process with the specified process ID PID. The
|
| - process ID is a hexadecimal integer identifying the process. In
|
| - all-stop mode, all threads in the attached process are stopped; in
|
| - non-stop mode, it may be attached without being stopped if that is
|
| - supported by the target.
|
| -
|
| - This packet is only available in extended mode (*note extended
|
| - mode::).
|
| -
|
| - Reply:
|
| - `E NN'
|
| - for an error
|
| -
|
| - `Any stop packet'
|
| - for success in all-stop mode (*note Stop Reply Packets::)
|
| -
|
| - `OK'
|
| - for success in non-stop mode (*note Remote Non-Stop::)
|
| -
|
| -`vCont[;ACTION[:THREAD-ID]]...'
|
| - Resume the inferior, specifying different actions for each thread.
|
| - If an action is specified with no THREAD-ID, then it is applied to
|
| - any threads that don't have a specific action specified; if no
|
| - default action is specified then other threads should remain
|
| - stopped in all-stop mode and in their current state in non-stop
|
| - mode. Specifying multiple default actions is an error; specifying
|
| - no actions is also an error. Thread IDs are specified using the
|
| - syntax described in *Note thread-id syntax::.
|
| -
|
| - Currently supported actions are:
|
| -
|
| - `c'
|
| - Continue.
|
| -
|
| - `C SIG'
|
| - Continue with signal SIG. The signal SIG should be two hex
|
| - digits.
|
| -
|
| - `s'
|
| - Step.
|
| -
|
| - `S SIG'
|
| - Step with signal SIG. The signal SIG should be two hex
|
| - digits.
|
| -
|
| - `t'
|
| - Stop.
|
| -
|
| - The optional argument ADDR normally associated with the `c', `C',
|
| - `s', and `S' packets is not supported in `vCont'.
|
| -
|
| - The `t' action is only relevant in non-stop mode (*note Remote
|
| - Non-Stop::) and may be ignored by the stub otherwise. A stop
|
| - reply should be generated for any affected thread not already
|
| - stopped. When a thread is stopped by means of a `t' action, the
|
| - corresponding stop reply should indicate that the thread has
|
| - stopped with signal `0', regardless of whether the target uses
|
| - some other signal as an implementation detail.
|
| -
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| -
|
| -`vCont?'
|
| - Request a list of actions supported by the `vCont' packet.
|
| -
|
| - Reply:
|
| - `vCont[;ACTION...]'
|
| - The `vCont' packet is supported. Each ACTION is a supported
|
| - command in the `vCont' packet.
|
| -
|
| - `'
|
| - The `vCont' packet is not supported.
|
| -
|
| -`vFile:OPERATION:PARAMETER...'
|
| - Perform a file operation on the target system. For details, see
|
| - *Note Host I/O Packets::.
|
| -
|
| -`vFlashErase:ADDR,LENGTH'
|
| - Direct the stub to erase LENGTH bytes of flash starting at ADDR.
|
| - The region may enclose any number of flash blocks, but its start
|
| - and end must fall on block boundaries, as indicated by the flash
|
| - block size appearing in the memory map (*note Memory Map
|
| - Format::). GDB groups flash memory programming operations
|
| - together, and sends a `vFlashDone' request after each group; the
|
| - stub is allowed to delay erase operation until the `vFlashDone'
|
| - packet is received.
|
| -
|
| - The stub must support `vCont' if it reports support for
|
| - multiprocess extensions (*note multiprocess extensions::). Note
|
| - that in this case `vCont' actions can be specified to apply to all
|
| - threads in a process by using the `pPID.-1' form of the THREAD-ID.
|
| -
|
| - Reply:
|
| - `OK'
|
| - for success
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`vFlashWrite:ADDR:XX...'
|
| - Direct the stub to write data to flash address ADDR. The data is
|
| - passed in binary form using the same encoding as for the `X'
|
| - packet (*note Binary Data::). The memory ranges specified by
|
| - `vFlashWrite' packets preceding a `vFlashDone' packet must not
|
| - overlap, and must appear in order of increasing addresses
|
| - (although `vFlashErase' packets for higher addresses may already
|
| - have been received; the ordering is guaranteed only between
|
| - `vFlashWrite' packets). If a packet writes to an address that was
|
| - neither erased by a preceding `vFlashErase' packet nor by some
|
| - other target-specific method, the results are unpredictable.
|
| -
|
| - Reply:
|
| - `OK'
|
| - for success
|
| -
|
| - `E.memtype'
|
| - for vFlashWrite addressing non-flash memory
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`vFlashDone'
|
| - Indicate to the stub that flash programming operation is finished.
|
| - The stub is permitted to delay or batch the effects of a group of
|
| - `vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
|
| - packet is received. The contents of the affected regions of flash
|
| - memory are unpredictable until the `vFlashDone' request is
|
| - completed.
|
| -
|
| -`vKill;PID'
|
| - Kill the process with the specified process ID. PID is a
|
| - hexadecimal integer identifying the process. This packet is used
|
| - in preference to `k' when multiprocess protocol extensions are
|
| - supported; see *Note multiprocess extensions::.
|
| -
|
| - Reply:
|
| - `E NN'
|
| - for an error
|
| -
|
| - `OK'
|
| - for success
|
| -
|
| -`vRun;FILENAME[;ARGUMENT]...'
|
| - Run the program FILENAME, passing it each ARGUMENT on its command
|
| - line. The file and arguments are hex-encoded strings. If
|
| - FILENAME is an empty string, the stub may use a default program
|
| - (e.g. the last program run). The program is created in the stopped
|
| - state.
|
| -
|
| - This packet is only available in extended mode (*note extended
|
| - mode::).
|
| -
|
| - Reply:
|
| - `E NN'
|
| - for an error
|
| -
|
| - `Any stop packet'
|
| - for success (*note Stop Reply Packets::)
|
| -
|
| -`vStopped'
|
| - In non-stop mode (*note Remote Non-Stop::), acknowledge a previous
|
| - stop reply and prompt for the stub to report another one.
|
| -
|
| - Reply:
|
| - `Any stop packet'
|
| - if there is another unreported stop event (*note Stop Reply
|
| - Packets::)
|
| -
|
| - `OK'
|
| - if there are no unreported stop events
|
| -
|
| -`X ADDR,LENGTH:XX...'
|
| - Write data to memory, where the data is transmitted in binary.
|
| - ADDR is address, LENGTH is number of bytes, `XX...' is binary data
|
| - (*note Binary Data::).
|
| -
|
| - Reply:
|
| - `OK'
|
| - for success
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`z TYPE,ADDR,KIND'
|
| -`Z TYPE,ADDR,KIND'
|
| - Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
|
| - starting at address ADDRESS of kind KIND.
|
| -
|
| - Each breakpoint and watchpoint packet TYPE is documented
|
| - separately.
|
| -
|
| - _Implementation notes: A remote target shall return an empty string
|
| - for an unrecognized breakpoint or watchpoint packet TYPE. A
|
| - remote target shall support either both or neither of a given
|
| - `ZTYPE...' and `zTYPE...' packet pair. To avoid potential
|
| - problems with duplicate packets, the operations should be
|
| - implemented in an idempotent way._
|
| -
|
| -`z0,ADDR,KIND'
|
| -`Z0,ADDR,KIND'
|
| - Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
|
| - of type KIND.
|
| -
|
| - A memory breakpoint is implemented by replacing the instruction at
|
| - ADDR with a software breakpoint or trap instruction. The KIND is
|
| - target-specific and typically indicates the size of the breakpoint
|
| - in bytes that should be inserted. E.g., the ARM and MIPS can
|
| - insert either a 2 or 4 byte breakpoint. Some architectures have
|
| - additional meanings for KIND; see *Note Architecture-Specific
|
| - Protocol Details::.
|
| -
|
| - _Implementation note: It is possible for a target to copy or move
|
| - code that contains memory breakpoints (e.g., when implementing
|
| - overlays). The behavior of this packet, in the presence of such a
|
| - target, is not defined._
|
| -
|
| - Reply:
|
| - `OK'
|
| - success
|
| -
|
| - `'
|
| - not supported
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`z1,ADDR,KIND'
|
| -`Z1,ADDR,KIND'
|
| - Insert (`Z1') or remove (`z1') a hardware breakpoint at address
|
| - ADDR.
|
| -
|
| - A hardware breakpoint is implemented using a mechanism that is not
|
| - dependant on being able to modify the target's memory. KIND has
|
| - the same meaning as in `Z0' packets.
|
| -
|
| - _Implementation note: A hardware breakpoint is not affected by code
|
| - movement._
|
| -
|
| - Reply:
|
| - `OK'
|
| - success
|
| -
|
| - `'
|
| - not supported
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`z2,ADDR,KIND'
|
| -`Z2,ADDR,KIND'
|
| - Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND
|
| - is interpreted as the number of bytes to watch.
|
| -
|
| - Reply:
|
| - `OK'
|
| - success
|
| -
|
| - `'
|
| - not supported
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`z3,ADDR,KIND'
|
| -`Z3,ADDR,KIND'
|
| - Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is
|
| - interpreted as the number of bytes to watch.
|
| -
|
| - Reply:
|
| - `OK'
|
| - success
|
| -
|
| - `'
|
| - not supported
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -`z4,ADDR,KIND'
|
| -`Z4,ADDR,KIND'
|
| - Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND
|
| - is interpreted as the number of bytes to watch.
|
| -
|
| - Reply:
|
| - `OK'
|
| - success
|
| -
|
| - `'
|
| - not supported
|
| -
|
| - `E NN'
|
| - for an error
|
| -
|
| -
|
| -
|
| -File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol
|
| -
|
| -E.3 Stop Reply Packets
|
| -======================
|
| -
|
| -The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?'
|
| -packets can receive any of the below as a reply. Except for `?' and
|
| -`vStopped', that reply is only returned when the target halts. In the
|
| -below the exact meaning of "signal number" is defined by the header
|
| -`include/gdb/signals.h' in the GDB source code.
|
| -
|
| - As in the description of request packets, we include spaces in the
|
| -reply templates for clarity; these are not part of the reply packet's
|
| -syntax. No GDB stop reply packet uses spaces to separate its
|
| -components.
|
| -
|
| -`S AA'
|
| - The program received signal number AA (a two-digit hexadecimal
|
| - number). This is equivalent to a `T' response with no N:R pairs.
|
| -
|
| -`T AA N1:R1;N2:R2;...'
|
| - The program received signal number AA (a two-digit hexadecimal
|
| - number). This is equivalent to an `S' response, except that the
|
| - `N:R' pairs can carry values of important registers and other
|
| - information directly in the stop reply packet, reducing round-trip
|
| - latency. Single-step and breakpoint traps are reported this way.
|
| - Each `N:R' pair is interpreted as follows:
|
| -
|
| - * If N is a hexadecimal number, it is a register number, and the
|
| - corresponding R gives that register's value. R is a series
|
| - of bytes in target byte order, with each byte given by a
|
| - two-digit hex number.
|
| -
|
| - * If N is `thread', then R is the THREAD-ID of the stopped
|
| - thread, as specified in *Note thread-id syntax::.
|
| -
|
| - * If N is `core', then R is the hexadecimal number of the core
|
| - on which the stop event was detected.
|
| -
|
| - * If N is a recognized "stop reason", it describes a more
|
| - specific event that stopped the target. The currently
|
| - defined stop reasons are listed below. AA should be `05',
|
| - the trap signal. At most one stop reason should be present.
|
| -
|
| - * Otherwise, GDB should ignore this `N:R' pair and go on to the
|
| - next; this allows us to extend the protocol in the future.
|
| -
|
| - The currently defined stop reasons are:
|
| -
|
| - `watch'
|
| - `rwatch'
|
| - `awatch'
|
| - The packet indicates a watchpoint hit, and R is the data
|
| - address, in hex.
|
| -
|
| - `library'
|
| - The packet indicates that the loaded libraries have changed.
|
| - GDB should use `qXfer:libraries:read' to fetch a new list of
|
| - loaded libraries. R is ignored.
|
| -
|
| - `replaylog'
|
| - The packet indicates that the target cannot continue replaying
|
| - logged execution events, because it has reached the end (or
|
| - the beginning when executing backward) of the log. The value
|
| - of R will be either `begin' or `end'. *Note Reverse
|
| - Execution::, for more information.
|
| -
|
| -`W AA'
|
| -`W AA ; process:PID'
|
| - The process exited, and AA is the exit status. This is only
|
| - applicable to certain targets.
|
| -
|
| - The second form of the response, including the process ID of the
|
| - exited process, can be used only when GDB has reported support for
|
| - multiprocess protocol extensions; see *Note multiprocess
|
| - extensions::. The PID is formatted as a big-endian hex string.
|
| -
|
| -`X AA'
|
| -`X AA ; process:PID'
|
| - The process terminated with signal AA.
|
| -
|
| - The second form of the response, including the process ID of the
|
| - terminated process, can be used only when GDB has reported support
|
| - for multiprocess protocol extensions; see *Note multiprocess
|
| - extensions::. The PID is formatted as a big-endian hex string.
|
| -
|
| -`O XX...'
|
| - `XX...' is hex encoding of ASCII data, to be written as the
|
| - program's console output. This can happen at any time while the
|
| - program is running and the debugger should continue to wait for
|
| - `W', `T', etc. This reply is not permitted in non-stop mode.
|
| -
|
| -`F CALL-ID,PARAMETER...'
|
| - CALL-ID is the identifier which says which host system call should
|
| - be called. This is just the name of the function. Translation
|
| - into the correct system call is only applicable as it's defined in
|
| - GDB. *Note File-I/O Remote Protocol Extension::, for a list of
|
| - implemented system calls.
|
| -
|
| - `PARAMETER...' is a list of parameters as defined for this very
|
| - system call.
|
| -
|
| - The target replies with this packet when it expects GDB to call a
|
| - host system call on behalf of the target. GDB replies with an
|
| - appropriate `F' packet and keeps up waiting for the next reply
|
| - packet from the target. The latest `C', `c', `S' or `s' action is
|
| - expected to be continued. *Note File-I/O Remote Protocol
|
| - Extension::, for more details.
|
| -
|
| -
|
|
|
Chromium Code Reviews
Issue 11969036:
Merge GDB 7.5.1 (Closed)
Base URL: http://git.chromium.org/native_client/nacl-gdb.git@master