| This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo. |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| 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 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 |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| 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.5. |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 2010 2011, 2012 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| 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::). |
| |
| `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 |
| --------------------------- |
| |
| The output from GDB/MI consists of zero or more out-of-band records |
| followed, optionally, by a single result record. This result record is |
| for the most recent command. The sequence of output records is |
| terminated by `(gdb)'. |
| |
| If an input command was prefixed with a `TOKEN' then the |
| corresponding output for that command will also be prefixed by that same |
| TOKEN. |
| |
| `OUTPUT ==>' |
| `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' |
| |
| `RESULT-RECORD ==>' |
| ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' |
| |
| `OUT-OF-BAND-RECORD ==>' |
| `ASYNC-RECORD | STREAM-RECORD' |
| |
| `ASYNC-RECORD ==>' |
| `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' |
| |
| `EXEC-ASYNC-OUTPUT ==>' |
| `[ TOKEN ] "*" ASYNC-OUTPUT' |
| |
| `STATUS-ASYNC-OUTPUT ==>' |
| `[ TOKEN ] "+" ASYNC-OUTPUT' |
| |
| `NOTIFY-ASYNC-OUTPUT ==>' |
| `[ TOKEN ] "=" ASYNC-OUTPUT' |
| |
| `ASYNC-OUTPUT ==>' |
| `ASYNC-CLASS ( "," RESULT )* NL' |
| |
| `RESULT-CLASS ==>' |
| `"done" | "running" | "connected" | "error" | "exit"' |
| |
| `ASYNC-CLASS ==>' |
| `"stopped" | OTHERS' (where OTHERS will be added depending on the |
| needs--this is still in development). |
| |
| `RESULT ==>' |
| ` VARIABLE "=" VALUE' |
| |
| `VARIABLE ==>' |
| ` STRING ' |
| |
| `VALUE ==>' |
| ` CONST | TUPLE | LIST ' |
| |
| `CONST ==>' |
| `C-STRING' |
| |
| `TUPLE ==>' |
| ` "{}" | "{" RESULT ( "," RESULT )* "}" ' |
| |
| `LIST ==>' |
| ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* |
| "]" ' |
| |
| `STREAM-RECORD ==>' |
| `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' |
| |
| `CONSOLE-STREAM-OUTPUT ==>' |
| `"~" C-STRING' |
| |
| `TARGET-STREAM-OUTPUT ==>' |
| `"@" C-STRING' |
| |
| `LOG-STREAM-OUTPUT ==>' |
| `"&" C-STRING' |
| |
| `NL ==>' |
| `CR | CR-LF' |
| |
| `TOKEN ==>' |
| _any sequence of digits_. |
| |
| Notes: |
| |
| * All output sequences end in a single line containing a period. |
| |
| * The `TOKEN' is from the corresponding request. Note that for all |
| async output, while the token is allowed by the grammar and may be |
| output by future versions of GDB for select async output messages, |
| it is generally omitted. Frontends should treat all async output |
| as reporting general changes in the state of the target and there |
| should be no need to associate async output to any prior command. |
| |
| * STATUS-ASYNC-OUTPUT contains on-going status information about the |
| progress of a slow operation. It can be discarded. All status |
| output is prefixed by `+'. |
| |
| * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target |
| (stopped, started, disappeared). All async output is prefixed by |
| `*'. |
| |
| * NOTIFY-ASYNC-OUTPUT contains supplementary information that the |
| client should handle (e.g., a new breakpoint information). All |
| notify output is prefixed by `='. |
| |
| * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in |
| the console. It is the textual response to a CLI command. All |
| the console output is prefixed by `~'. |
| |
| * TARGET-STREAM-OUTPUT is the output produced by the target program. |
| All the target output is prefixed by `@'. |
| |
| * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for |
| instance messages that should be displayed as part of an error |
| log. All the log output is prefixed by `&'. |
| |
| * New GDB/MI commands should only output LISTS containing VALUES. |
| |
| |
| *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details |
| about the various output records. |
| |
| |
| File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI |
| |
| 27.3 GDB/MI Compatibility with CLI |
| ================================== |
| |
| For the developers convenience CLI commands can be entered directly, |
| but there may be some unexpected behaviour. For example, commands that |
| query the user will behave as if the user replied yes, breakpoint |
| command lists are not executed and some CLI commands, such as `if', |
| `when' and `define', prompt for further input with `>', which is not |
| valid MI output. |
| |
| This feature may be removed at some stage in the future and it is |
| recommended that front ends use the `-interpreter-exec' command (*note |
| -interpreter-exec::). |
| |
| |
| File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI |
| |
| 27.4 GDB/MI Development and Front Ends |
| ====================================== |
| |
| The application which takes the MI output and presents the state of the |
| program being debugged to the user is called a "front end". |
| |
| Although GDB/MI is still incomplete, it is currently being used by a |
| variety of front ends to GDB. This makes it difficult to introduce new |
| functionality without breaking existing usage. This section tries to |
| minimize the problems by describing how the protocol might change. |
| |
| Some changes in MI need not break a carefully designed front end, and |
| for these the MI version will remain unchanged. The following is a |
| list of changes that may occur within one level, so front ends should |
| parse MI output in a way that can handle them: |
| |
| * New MI commands may be added. |
| |
| * New fields may be added to the output of any MI command. |
| |
| * The range of values for fields with specified values, e.g., |
| `in_scope' (*note -var-update::) may be extended. |
| |
| |
| If the changes are likely to break front ends, the MI version level |
| will be increased by one. This will allow the front end to parse the |
| output according to the MI version. Apart from mi0, new versions of |
| GDB will not support old versions of MI and it will be the |
| responsibility of the front end to work with the new one. |
| |
| The best way to avoid unexpected changes in MI that might break your |
| front end is to make your project known to GDB developers and follow |
| development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>. |
| |
| |
| File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI |
| |
| 27.5 GDB/MI Output Records |
| ========================== |
| |
| * Menu: |
| |
| * GDB/MI Result Records:: |
| * GDB/MI Stream Records:: |
| * GDB/MI Async Records:: |
| * GDB/MI Frame Information:: |
| * GDB/MI Thread Information:: |
| * GDB/MI Ada Exception Information:: |
| |
| |
| File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records |
| |
| 27.5.1 GDB/MI Result Records |
| ---------------------------- |
| |
| In addition to a number of out-of-band notifications, the response to a |
| GDB/MI command includes one of the following result indications: |
| |
| `"^done" [ "," RESULTS ]' |
| The synchronous operation was successful, `RESULTS' are the return |
| values. |
| |
| `"^running"' |
| This result record is equivalent to `^done'. Historically, it was |
| output instead of `^done' if the command has resumed the target. |
| This behaviour is maintained for backward compatibility, but all |
| frontends should treat `^done' and `^running' identically and rely |
| on the `*running' output record to determine which threads are |
| resumed. |
| |
| `"^connected"' |
| GDB has connected to a remote target. |
| |
| `"^error" "," C-STRING' |
| The operation failed. The `C-STRING' contains the corresponding |
| error message. |
| |
| `"^exit"' |
| GDB has terminated. |
| |
| |
| |
| File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records |
| |
| 27.5.2 GDB/MI Stream Records |
| ---------------------------- |
| |
| GDB internally maintains a number of output streams: the console, the |
| target, and the log. The output intended for each of these streams is |
| funneled through the GDB/MI interface using "stream records". |
| |
| Each stream record begins with a unique "prefix character" which |
| identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output |
| Syntax.). In addition to the prefix, each stream record contains a |
| `STRING-OUTPUT'. This is either raw text (with an implicit new line) |
| or a quoted C string (which does not contain an implicit newline). |
| |
| `"~" STRING-OUTPUT' |
| The console output stream contains text that should be displayed |
| in the CLI console window. It contains the textual responses to |
| CLI commands. |
| |
| `"@" STRING-OUTPUT' |
| The target output stream contains any textual output from the |
| running target. This is only present when GDB's event loop is |
| truly asynchronous, which is currently only the case for remote |
| targets. |
| |
| `"&" STRING-OUTPUT' |
| The log stream contains debugging messages being produced by GDB's |
| internals. |
| |
| |
| File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Frame Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records |
| |
| 27.5.3 GDB/MI Async Records |
| --------------------------- |
| |
| "Async" records are used to notify the GDB/MI client of additional |
| changes that have occurred. Those changes can either be a consequence |
| of GDB/MI commands (e.g., a breakpoint modified) or a result of target |
| activity (e.g., target stopped). |
| |
| The following is the list of possible async records: |
| |
| `*running,thread-id="THREAD"' |
| The target is now running. The THREAD field tells which specific |
| thread is now running, and can be `all' if all threads are |
| running. The frontend should assume that no interaction with a |
| running thread is possible after this notification is produced. |
| The frontend should not assume that this notification is output |
| only once for any command. GDB may emit this notification several |
| times, either for different threads, because it cannot resume all |
| threads together, or even for a single thread, if the thread must |
| be stepped though some code before letting it run freely. |
| |
| `*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"' |
| The target has stopped. The REASON field can have one of the |
| following values: |
| |
| `breakpoint-hit' |
| A breakpoint was reached. |
| |
| `watchpoint-trigger' |
| A watchpoint was triggered. |
| |
| `read-watchpoint-trigger' |
| A read watchpoint was triggered. |
| |
| `access-watchpoint-trigger' |
| An access watchpoint was triggered. |
| |
| `function-finished' |
| An -exec-finish or similar CLI command was accomplished. |
| |
| `location-reached' |
| An -exec-until or similar CLI command was accomplished. |
| |
| `watchpoint-scope' |
| A watchpoint has gone out of scope. |
| |
| `end-stepping-range' |
| An -exec-next, -exec-next-instruction, -exec-step, |
| -exec-step-instruction or similar CLI command was |
| accomplished. |
| |
| `exited-signalled' |
| The inferior exited because of a signal. |
| |
| `exited' |
| The inferior exited. |
| |
| `exited-normally' |
| The inferior exited normally. |
| |
| `signal-received' |
| A signal was received by the inferior. |
| |
| `solib-event' |
| The inferior has stopped due to a library being loaded or |
| 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' |
| (*note Set Catchpoints::) has been used. |
| |
| `vfork' |
| The inferior has vforked. This is reported in when `catch |
| vfork' (*note Set Catchpoints::) has been used. |
| |
| `syscall-entry' |
| The inferior entered a system call. This is reported when |
| `catch syscall' (*note Set Catchpoints::) has been used. |
| |
| `syscall-entry' |
| The inferior returned from a system call. This is reported |
| when `catch syscall' (*note Set Catchpoints::) has been used. |
| |
| `exec' |
| The inferior called `exec'. This is reported when `catch |
| exec' (*note Set Catchpoints::) has been used. |
| |
| The ID field identifies the thread that directly caused the stop - |
| for example by hitting a breakpoint. Depending on whether all-stop |
| mode is in effect (*note All-Stop Mode::), GDB may either stop all |
| threads, or only the thread that directly triggered the stop. If |
| all threads are stopped, the STOPPED field will have the value of |
| `"all"'. Otherwise, the value of the STOPPED field will be a list |
| of thread identifiers. Presently, this list will always include a |
| single thread, but frontend should be prepared to see several |
| threads in the list. The CORE field reports the processor core on |
| which the stop event has happened. This field may be absent if |
| such information is not available. |
| |
| `=thread-group-added,id="ID"' |
| `=thread-group-removed,id="ID"' |
| A thread group was either added or removed. The ID field contains |
| the GDB identifier of the thread group. When a thread group is |
| added, it generally might not be associated with a running |
| process. When a thread group is removed, its id becomes invalid |
| and cannot be used in any way. |
| |
| `=thread-group-started,id="ID",pid="PID"' |
| A thread group became associated with a running program, either |
| because the program was just started or the thread group was |
| attached to a program. The ID field contains the GDB identifier |
| of the thread group. The PID field contains process identifier, |
| specific to the operating system. |
| |
| `=thread-group-exited,id="ID"[,exit-code="CODE"]' |
| A thread group is no longer associated with a running program, |
| either because the program has exited, or because it was detached |
| from. The ID field contains the GDB identifier of the thread |
| group. CODE is the exit code of the inferior; it exists only when |
| the inferior exited with some code. |
| |
| `=thread-created,id="ID",group-id="GID"' |
| `=thread-exited,id="ID",group-id="GID"' |
| A thread either was created, or has exited. The ID field contains |
| the GDB identifier of the thread. The GID field identifies the |
| thread group this thread belongs to. |
| |
| `=thread-selected,id="ID"' |
| Informs that the selected thread was changed as result of the last |
| command. This notification is not emitted as result of |
| `-thread-select' command but is emitted whenever an MI command |
| that is not documented to change the selected thread actually |
| changes it. In particular, invoking, directly or indirectly (via |
| user-defined command), the CLI `thread' command, will generate |
| this notification. |
| |
| We suggest that in response to this notification, front ends |
| highlight the selected thread and cause subsequent commands to |
| apply to that thread. |
| |
| `=library-loaded,...' |
| Reports that a new library file was loaded by the program. This |
| notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and |
| SYMBOLS-LOADED. The ID field is an opaque identifier of the |
| library. For remote debugging case, TARGET-NAME and HOST-NAME |
| fields give the name of the library file on the target, and on the |
| host respectively. For native debugging, both those fields have |
| the same value. The SYMBOLS-LOADED field is emitted only for |
| backward compatibility and should not be relied on to convey any |
| useful information. The THREAD-GROUP field, if present, specifies |
| the id of the thread group in whose context the library was |
| loaded. If the field is absent, it means the library was loaded |
| in the context of all present thread groups. |
| |
| `=library-unloaded,...' |
| Reports that a library was unloaded by the program. This |
| notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the |
| same meaning as for the `=library-loaded' notification. The |
| THREAD-GROUP field, if present, specifies the id of the thread |
| group in whose context the library was unloaded. If the field is |
| absent, it means the library was unloaded in the context of all |
| present thread groups. |
| |
| `=breakpoint-created,bkpt={...}' |
| `=breakpoint-modified,bkpt={...}' |
| `=breakpoint-deleted,bkpt={...}' |
| Reports that a breakpoint was created, modified, or deleted, |
| respectively. Only user-visible breakpoints are reported to the MI |
| user. |
| |
| The BKPT argument is of the same form as returned by the various |
| breakpoint commands; *Note GDB/MI Breakpoint Commands::. |
| |
| Note that if a breakpoint is emitted in the result record of a |
| command, then it will not also be emitted in an async record. |
| |
| |
| |
| File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records |
| |
| 27.5.4 GDB/MI Frame Information |
| ------------------------------- |
| |
| Response from many MI commands includes an information about stack |
| frame. This information is a tuple that may have the following fields: |
| |
| `level' |
| The level of the stack frame. The innermost frame has the level of |
| zero. This field is always present. |
| |
| `func' |
| The name of the function corresponding to the frame. This field |
| may be absent if GDB is unable to determine the function name. |
| |
| `addr' |
| The code address for the frame. This field is always present. |
| |
| `file' |
| The name of the source files that correspond to the frame's code |
| address. This field may be absent. |
| |
| `line' |
| The source line corresponding to the frames' code address. This |
| field may be absent. |
| |
| `from' |
| The name of the binary file (either executable or shared library) |
| the corresponds to the frame's code address. This field may be |
| absent. |
| |
| |
| |
| File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records |
| |
| 27.5.5 GDB/MI Thread Information |
| -------------------------------- |
| |
| Whenever GDB has to report an information about a thread, it uses a |
| tuple with the following fields: |
| |
| `id' |
| The numeric id assigned to the thread by GDB. This field is |
| always present. |
| |
| `target-id' |
| Target-specific string identifying the thread. This field is |
| always present. |
| |
| `details' |
| Additional information about the thread provided by the target. |
| It is supposed to be human-readable and not interpreted by the |
| frontend. This field is optional. |
| |
| `state' |
| Either `stopped' or `running', depending on whether the thread is |
| presently running. This field is always present. |
| |
| `core' |
| The value of this field is an integer number of the processor core |
| the thread was last seen on. This field is optional. |
| |
| |
| File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records |
| |
| 27.5.6 GDB/MI Ada Exception Information |
| --------------------------------------- |
| |
| Whenever a `*stopped' record is emitted because the program stopped |
| after hitting an exception catchpoint (*note Set Catchpoints::), GDB |
| provides the name of the exception that was raised via the |
| `exception-name' field. |
| |
| |
| File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI |
| |
| 27.6 Simple Examples of GDB/MI Interaction |
| ========================================== |
| |
| This subsection presents several simple examples of interaction using |
| the GDB/MI interface. In these examples, `->' means that the following |
| line is passed to GDB/MI as input, while `<-' means the output received |
| from GDB/MI. |
| |
| Note the line breaks shown in the examples are here only for |
| readability, they don't appear in the real output. |
| |
| Setting a Breakpoint |
| -------------------- |
| |
| Setting a breakpoint generates synchronous output which contains |
| detailed information of the breakpoint. |
| |
| -> -break-insert main |
| <- ^done,bkpt={number="1",type="breakpoint",disp="keep", |
| enabled="y",addr="0x08048564",func="main",file="myprog.c", |
| fullname="/home/nickrob/myprog.c",line="68",times="0"} |
| <- (gdb) |
| |
| Program Execution |
| ----------------- |
| |
| Program execution generates asynchronous records and MI gives the |
| reason that execution stopped. |
| |
| -> -exec-run |
| <- ^running |
| <- (gdb) |
| <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", |
| frame={addr="0x08048564",func="main", |
| args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], |
| file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"} |
| <- (gdb) |
| -> -exec-continue |
| <- ^running |
| <- (gdb) |
| <- *stopped,reason="exited-normally" |
| <- (gdb) |
| |
| Quitting GDB |
| ------------ |
| |
| Quitting GDB just prints the result class `^exit'. |
| |
| -> (gdb) |
| <- -gdb-exit |
| <- ^exit |
| |
| Please note that `^exit' is printed immediately, but it might take |
| some time for GDB to actually exit. During that time, GDB performs |
| necessary cleanups, including killing programs being debugged or |
| disconnecting from debug hardware, so the frontend should wait till GDB |
| exits and should only forcibly kill GDB if it fails to exit in |
| reasonable time. |
| |
| A Bad Command |
| ------------- |
| |
| Here's what happens if you pass a non-existent command: |
| |
| -> -rubbish |
| <- ^error,msg="Undefined MI command: rubbish" |
| <- (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI |
| |
| 27.7 GDB/MI Command Description Format |
| ====================================== |
| |
| The remaining sections describe blocks of commands. Each block of |
| commands is laid out in a fashion similar to this section. |
| |
| Motivation |
| ---------- |
| |
| The motivation for this collection of commands. |
| |
| Introduction |
| ------------ |
| |
| A brief introduction to this collection of commands as a whole. |
| |
| Commands |
| -------- |
| |
| For each command in the block, the following is described: |
| |
| Synopsis |
| ........ |
| |
| -command ARGS... |
| |
| Result |
| ...... |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB CLI command(s), if any. |
| |
| Example |
| ....... |
| |
| Example(s) formatted for readability. Some of the described commands |
| have not been implemented yet and these are labeled N.A. (not |
| available). |
| |
| |
| File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI |
| |
| 27.8 GDB/MI Breakpoint Commands |
| =============================== |
| |
| This section documents GDB/MI commands for manipulating breakpoints. |
| |
| The `-break-after' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-after NUMBER COUNT |
| |
| The breakpoint number NUMBER is not in effect until it has been hit |
| COUNT times. To see how this is reflected in the output of the |
| `-break-list' command, see the description of the `-break-list' command |
| below. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `ignore'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",type="breakpoint",disp="keep", |
| enabled="y",addr="0x000100d0",func="main",file="hello.c", |
| fullname="/home/foo/hello.c",line="5",times="0"} |
| (gdb) |
| -break-after 1 3 |
| ~ |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",times="0",ignore="3"}]} |
| (gdb) |
| |
| The `-break-commands' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-commands NUMBER [ COMMAND1 ... COMMANDN ] |
| |
| Specifies the CLI commands that should be executed when breakpoint |
| NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands. |
| If no command is specified, any previously-set commands are cleared. |
| *Note Break Commands::. Typical use of this functionality is tracing a |
| program, that is, printing of values of some variables whenever |
| breakpoint is hit and then continuing. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `commands'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",type="breakpoint",disp="keep", |
| enabled="y",addr="0x000100d0",func="main",file="hello.c", |
| fullname="/home/foo/hello.c",line="5",times="0"} |
| (gdb) |
| -break-commands 1 "print v" "continue" |
| ^done |
| (gdb) |
| |
| The `-break-condition' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -break-condition NUMBER EXPR |
| |
| Breakpoint NUMBER will stop the program only if the condition in |
| EXPR is true. The condition becomes part of the `-break-list' output |
| (see the description of the `-break-list' command below). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `condition'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-condition 1 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",cond="1",times="0",ignore="3"}]} |
| (gdb) |
| |
| The `-break-delete' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-delete ( BREAKPOINT )+ |
| |
| Delete the breakpoint(s) whose number(s) are specified in the |
| argument list. This is obviously reflected in the breakpoint list. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `delete'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-delete 1 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="0",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[]} |
| (gdb) |
| |
| The `-break-disable' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-disable ( BREAKPOINT )+ |
| |
| Disable the named BREAKPOINT(s). The field `enabled' in the break |
| list is now set to `n' for the named BREAKPOINT(s). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `disable'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-disable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",times="0"}]} |
| (gdb) |
| |
| The `-break-enable' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-enable ( BREAKPOINT )+ |
| |
| Enable (previously disabled) BREAKPOINT(s). |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `enable'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-enable 2 |
| ^done |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", |
| line="5",times="0"}]} |
| (gdb) |
| |
| The `-break-info' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-info BREAKPOINT |
| |
| Get information about a single breakpoint. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info break BREAKPOINT'. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-break-insert' Command |
| --------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] |
| [ -c CONDITION ] [ -i IGNORE-COUNT ] |
| [ -p THREAD-ID ] [ LOCATION ] |
| |
| If specified, LOCATION, can be one of: |
| |
| * function |
| |
| * filename:linenum |
| |
| * filename:function |
| |
| * *address |
| |
| The possible optional parameters of this command are: |
| |
| `-t' |
| Insert a temporary breakpoint. |
| |
| `-h' |
| Insert a hardware breakpoint. |
| |
| `-f' |
| If LOCATION cannot be parsed (for example if it refers to unknown |
| files or functions), create a pending breakpoint. Without this |
| flag, GDB will report an error, and won't create a breakpoint, if |
| LOCATION cannot be parsed. |
| |
| `-d' |
| Create a disabled breakpoint. |
| |
| `-a' |
| 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 |
| ...... |
| |
| The result is in the form: |
| |
| ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep", |
| enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME", |
| fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,] |
| times="TIMES"} |
| |
| where NUMBER is the GDB number for this breakpoint, FUNCNAME is the |
| name of the function where the breakpoint was inserted, FILENAME is the |
| name of the source file which contains this function, LINENO is the |
| source line number within that file and TIMES the number of times that |
| the breakpoint has been hit (always 0 for -break-insert but may be |
| greater for -break-info or -break-list which use the same output). |
| |
| Note: this format is open to change. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `break', `tbreak', `hbreak', and |
| `thbreak'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,line="4",times="0"} |
| (gdb) |
| -break-insert -t foo |
| ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,line="11",times="0"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x0001072c", func="main",file="recursive2.c", |
| fullname="/home/foo/recursive2.c,"line="4",times="0"}, |
| bkpt={number="2",type="breakpoint",disp="del",enabled="y", |
| addr="0x00010774",func="foo",file="recursive2.c", |
| fullname="/home/foo/recursive2.c",line="11",times="0"}]} |
| (gdb) |
| |
| The `-break-list' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-list |
| |
| Displays the list of inserted breakpoints, showing the following |
| fields: |
| |
| `Number' |
| number of the breakpoint |
| |
| `Type' |
| type of the breakpoint: `breakpoint' or `watchpoint' |
| |
| `Disposition' |
| should the breakpoint be deleted or disabled when it is hit: `keep' |
| or `nokeep' |
| |
| `Enabled' |
| is the breakpoint enabled or no: `y' or `n' |
| |
| `Address' |
| memory location at which the breakpoint is set |
| |
| `What' |
| logical location of the breakpoint, expressed by function name, |
| file name, line number |
| |
| `Times' |
| number of times the breakpoint has been hit |
| |
| If there are no breakpoints or watchpoints, the `BreakpointTable' |
| `body' field is an empty list. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info break'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}, |
| bkpt={number="2",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", |
| line="13",times="0"}]} |
| (gdb) |
| |
| Here's an example of the result when there are no breakpoints: |
| |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="0",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[]} |
| (gdb) |
| |
| The `-break-passcount' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -break-passcount TRACEPOINT-NUMBER PASSCOUNT |
| |
| Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If |
| the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint, |
| error is emitted. This corresponds to CLI command `passcount'. |
| |
| The `-break-watch' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -break-watch [ -a | -r ] |
| |
| Create a watchpoint. With the `-a' option it will create an |
| "access" watchpoint, i.e., a watchpoint that triggers either on a read |
| from or on a write to the memory location. With the `-r' option, the |
| watchpoint created is a "read" watchpoint, i.e., it will trigger only |
| when the memory location is accessed for reading. Without either of |
| the options, the watchpoint created is a regular watchpoint, i.e., it |
| will trigger when the memory location is accessed for writing. *Note |
| Setting Watchpoints: Set Watchpoints. |
| |
| Note that `-break-list' will report a single list of watchpoints and |
| breakpoints inserted. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `watch', `awatch', and `rwatch'. |
| |
| Example |
| ....... |
| |
| Setting a watchpoint on a variable in the `main' function: |
| |
| (gdb) |
| -break-watch x |
| ^done,wpt={number="2",exp="x"} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, |
| value={old="-268439212",new="55"}, |
| frame={func="main",args=[],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="5"} |
| (gdb) |
| |
| Setting a watchpoint on a variable local to a function. GDB will |
| stop the program execution twice: first for the variable changing |
| value, then for the watchpoint going out of scope. |
| |
| (gdb) |
| -break-watch C |
| ^done,wpt={number="5",exp="C"} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-trigger", |
| wpt={number="5",exp="C"},value={old="-276895068",new="3"}, |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-scope",wpnum="5", |
| frame={func="callee3",args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} |
| (gdb) |
| |
| Listing breakpoints and watchpoints, at different points in the |
| program execution. Note that once the watchpoint goes out of scope, it |
| is deleted. |
| |
| (gdb) |
| -break-watch C |
| ^done,wpt={number="2",exp="C"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"}, |
| bkpt={number="2",type="watchpoint",disp="keep", |
| enabled="y",addr="",what="C",times="0"}]} |
| (gdb) |
| -exec-continue |
| ^running |
| (gdb) |
| *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, |
| value={old="-276895068",new="3"}, |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, |
| bkpt={number="2",type="watchpoint",disp="keep", |
| enabled="y",addr="",what="C",times="-5"}]} |
| (gdb) |
| -exec-continue |
| ^running |
| ^done,reason="watchpoint-scope",wpnum="2", |
| frame={func="callee3",args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} |
| (gdb) |
| -break-list |
| ^done,BreakpointTable={nr_rows="1",nr_cols="6", |
| hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
| {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
| {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
| {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
| {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
| {width="40",alignment="2",col_name="what",colhdr="What"}], |
| body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", |
| times="1"}]} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI |
| |
| 27.9 GDB/MI Program Context |
| ============================ |
| |
| The `-exec-arguments' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-arguments ARGS |
| |
| Set the inferior program arguments, to be used in the next |
| `-exec-run'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `set args'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-arguments -v word |
| ^done |
| (gdb) |
| |
| The `-environment-cd' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -environment-cd PATHDIR |
| |
| Set GDB's working directory. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `cd'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done |
| (gdb) |
| |
| The `-environment-directory' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -environment-directory [ -r ] [ PATHDIR ]+ |
| |
| Add directories PATHDIR to beginning of search path for source files. |
| If the `-r' option is used, the search path is reset to the default |
| search path. If directories PATHDIR are supplied in addition to the |
| `-r' option, the search path is first reset and then addition occurs as |
| normal. Multiple directories may be specified, separated by blanks. |
| Specifying multiple directories in a single command results in the |
| directories added to the beginning of the search path in the same order |
| they were presented in the command. If blanks are needed as part of a |
| directory name, double-quotes should be used around the name. In the |
| command output, the path will show up separated by the system |
| directory-separator character. The directory-separator character must |
| not be used in any directory name. If no directories are specified, |
| the current search path is displayed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `dir'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb |
| ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" |
| (gdb) |
| -environment-directory "" |
| ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" |
| (gdb) |
| -environment-directory -r /home/jjohnstn/src/gdb /usr/src |
| ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" |
| (gdb) |
| -environment-directory -r |
| ^done,source-path="$cdir:$cwd" |
| (gdb) |
| |
| The `-environment-path' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -environment-path [ -r ] [ PATHDIR ]+ |
| |
| Add directories PATHDIR to beginning of search path for object files. |
| If the `-r' option is used, the search path is reset to the original |
| search path that existed at gdb start-up. If directories PATHDIR are |
| supplied in addition to the `-r' option, the search path is first reset |
| and then addition occurs as normal. Multiple directories may be |
| specified, separated by blanks. Specifying multiple directories in a |
| single command results in the directories added to the beginning of the |
| search path in the same order they were presented in the command. If |
| blanks are needed as part of a directory name, double-quotes should be |
| used around the name. In the command output, the path will show up |
| separated by the system directory-separator character. The |
| directory-separator character must not be used in any directory name. |
| If no directories are specified, the current path is displayed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `path'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-path |
| ^done,path="/usr/bin" |
| (gdb) |
| -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin |
| ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" |
| (gdb) |
| -environment-path -r /usr/local/bin |
| ^done,path="/usr/local/bin:/usr/bin" |
| (gdb) |
| |
| The `-environment-pwd' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -environment-pwd |
| |
| Show the current working directory. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `pwd'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -environment-pwd |
| ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI |
| |
| 27.10 GDB/MI Thread Commands |
| ============================ |
| |
| The `-thread-info' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-info [ THREAD-ID ] |
| |
| Reports information about either a specific thread, if the THREAD-ID |
| parameter is present, or about all threads. When printing information |
| about all threads, also reports the current thread. |
| |
| GDB Command |
| ........... |
| |
| The `info thread' command prints the same information about all threads. |
| |
| Result |
| ...... |
| |
| The result is a list of threads. The following attributes are defined |
| for a given thread: |
| |
| `current' |
| This field exists only for the current thread. It has the value |
| `*'. |
| |
| `id' |
| The identifier that GDB uses to refer to the thread. |
| |
| `target-id' |
| The identifier that the target uses to refer to the thread. |
| |
| `details' |
| Extra information about the thread, in a target-specific format. |
| This field is optional. |
| |
| `name' |
| The name of the thread. If the user specified a name using the |
| `thread name' command, then this name is given. Otherwise, if GDB |
| can extract the thread name from the target, then that name is |
| given. If GDB cannot find the thread name, then this field is |
| omitted. |
| |
| `frame' |
| The stack frame currently executing in the thread. |
| |
| `state' |
| The thread's state. The `state' field may have the following |
| values: |
| |
| `stopped' |
| The thread is stopped. Frame information is available for |
| stopped threads. |
| |
| `running' |
| The thread is running. There's no frame information for |
| running threads. |
| |
| |
| `core' |
| If GDB can find the CPU core on which this thread is running, then |
| this field is the core identifier. This field is optional. |
| |
| |
| Example |
| ....... |
| |
| -thread-info |
| ^done,threads=[ |
| {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", |
| frame={level="0",addr="0xffffe410",func="__kernel_vsyscall", |
| args=[]},state="running"}, |
| {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", |
| frame={level="0",addr="0x0804891f",func="foo", |
| args=[{name="i",value="10"}], |
| file="/tmp/a.c",fullname="/tmp/a.c",line="158"}, |
| state="running"}], |
| current-thread-id="1" |
| (gdb) |
| |
| The `-thread-list-ids' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -thread-list-ids |
| |
| Produces a list of the currently known GDB thread ids. At the end |
| of the list it also prints the total number of such threads. |
| |
| This command is retained for historical reasons, the `-thread-info' |
| command should be used instead. |
| |
| GDB Command |
| ........... |
| |
| Part of `info threads' supplies the same information. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -thread-list-ids |
| ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, |
| current-thread-id="1",number-of-threads="3" |
| (gdb) |
| |
| The `-thread-select' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -thread-select THREADNUM |
| |
| Make THREADNUM the current thread. It prints the number of the new |
| current thread, and the topmost frame for that thread. |
| |
| This command is deprecated in favor of explicitly using the |
| `--thread' option to each command. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `thread'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",thread-id="2",line="187", |
| file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" |
| (gdb) |
| -thread-list-ids |
| ^done, |
| thread-ids={thread-id="3",thread-id="2",thread-id="1"}, |
| number-of-threads="3" |
| (gdb) |
| -thread-select 3 |
| ^done,new-thread-id="3", |
| frame={level="0",func="vprintf", |
| args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, |
| {name="arg",value="0x2"}],file="vprintf.c",line="31"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI |
| |
| 27.11 GDB/MI Ada Tasking Commands |
| ================================= |
| |
| The `-ada-task-info' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -ada-task-info [ TASK-ID ] |
| |
| Reports information about either a specific Ada task, if the TASK-ID |
| parameter is present, or about all Ada tasks. |
| |
| GDB Command |
| ........... |
| |
| The `info tasks' command prints the same information about all Ada |
| tasks (*note Ada Tasks::). |
| |
| Result |
| ...... |
| |
| The result is a table of Ada tasks. The following columns are defined |
| for each Ada task: |
| |
| `current' |
| This field exists only for the current thread. It has the value |
| `*'. |
| |
| `id' |
| The identifier that GDB uses to refer to the Ada task. |
| |
| `task-id' |
| The identifier that the target uses to refer to the Ada task. |
| |
| `thread-id' |
| The identifier of the thread corresponding to the Ada task. |
| |
| This field should always exist, as Ada tasks are always implemented |
| on top of a thread. But if GDB cannot find this corresponding |
| thread for any reason, the field is omitted. |
| |
| `parent-id' |
| This field exists only when the task was created by another task. |
| In this case, it provides the ID of the parent task. |
| |
| `priority' |
| The base priority of the task. |
| |
| `state' |
| The current state of the task. For a detailed description of the |
| possible states, see *Note Ada Tasks::. |
| |
| `name' |
| The name of the task. |
| |
| |
| Example |
| ....... |
| |
| -ada-task-info |
| ^done,tasks={nr_rows="3",nr_cols="8", |
| hdr=[{width="1",alignment="-1",col_name="current",colhdr=""}, |
| {width="3",alignment="1",col_name="id",colhdr="ID"}, |
| {width="9",alignment="1",col_name="task-id",colhdr="TID"}, |
| {width="4",alignment="1",col_name="thread-id",colhdr=""}, |
| {width="4",alignment="1",col_name="parent-id",colhdr="P-ID"}, |
| {width="3",alignment="1",col_name="priority",colhdr="Pri"}, |
| {width="22",alignment="-1",col_name="state",colhdr="State"}, |
| {width="1",alignment="2",col_name="name",colhdr="Name"}], |
| body=[{current="*",id="1",task-id=" 644010",thread-id="1",priority="48", |
| state="Child Termination Wait",name="main_task"}]} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI |
| |
| 27.12 GDB/MI Program Execution |
| ============================== |
| |
| These are the asynchronous commands which generate the out-of-band |
| record `*stopped'. Currently GDB only really executes asynchronously |
| with remote targets and this interaction is mimicked in other cases. |
| |
| The `-exec-continue' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-continue [--reverse] [--all|--thread-group N] |
| |
| Resumes the execution of the inferior program, which will continue |
| to execute until it reaches a debugger stop event. If the `--reverse' |
| option is specified, execution resumes in reverse until it reaches a |
| stop event. Stop events may include |
| * breakpoints or watchpoints |
| |
| * signals or exceptions |
| |
| * the end of the process (or its beginning under `--reverse') |
| |
| * the end or beginning of a replay log if one is being used. |
| In all-stop mode (*note All-Stop Mode::), may resume only one |
| thread, or all threads, depending on the value of the |
| `scheduler-locking' variable. If `--all' is specified, all threads (in |
| all inferiors) will be resumed. The `--all' option is ignored in |
| all-stop mode. If the `--thread-group' options is specified, then all |
| threads in that thread group are resumed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB corresponding is `continue'. |
| |
| Example |
| ....... |
| |
| -exec-continue |
| ^running |
| (gdb) |
| @Hello world |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ |
| func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", |
| line="13"} |
| (gdb) |
| |
| The `-exec-finish' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-finish [--reverse] |
| |
| Resumes the execution of the inferior program until the current |
| function is exited. Displays the results returned by the function. If |
| the `--reverse' option is specified, resumes the reverse execution of |
| the inferior program until the point where current function was called. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `finish'. |
| |
| Example |
| ....... |
| |
| Function returning `void'. |
| |
| -exec-finish |
| ^running |
| (gdb) |
| @hello from foo |
| *stopped,reason="function-finished",frame={func="main",args=[], |
| file="hello.c",fullname="/home/foo/bar/hello.c",line="7"} |
| (gdb) |
| |
| Function returning other than `void'. The name of the internal GDB |
| variable storing the result is printed, together with the value itself. |
| |
| -exec-finish |
| ^running |
| (gdb) |
| *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", |
| args=[{name="a",value="1"],{name="b",value="9"}}, |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| gdb-result-var="$1",return-value="0" |
| (gdb) |
| |
| The `-exec-interrupt' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-interrupt [--all|--thread-group N] |
| |
| Interrupts the background execution of the target. Note how the |
| token associated with the stop message is the one for the execution |
| command that has been interrupted. The token for the interrupt itself |
| only appears in the `^done' output. If the user is trying to interrupt |
| a non-running program, an error message will be printed. |
| |
| Note that when asynchronous execution is enabled, this command is |
| asynchronous just like other execution commands. That is, first the |
| `^done' response will be printed, and the target stop will be reported |
| after that using the `*stopped' notification. |
| |
| In non-stop mode, only the context thread is interrupted by default. |
| All threads (in all inferiors) will be interrupted if the `--all' |
| option is specified. If the `--thread-group' option is specified, all |
| threads in that group will be interrupted. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `interrupt'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| 111-exec-continue |
| 111^running |
| |
| (gdb) |
| 222-exec-interrupt |
| 222^done |
| (gdb) |
| 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", |
| frame={addr="0x00010140",func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="13"} |
| (gdb) |
| |
| (gdb) |
| -exec-interrupt |
| ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." |
| (gdb) |
| |
| The `-exec-jump' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-jump LOCATION |
| |
| Resumes execution of the inferior program at the location specified |
| by parameter. *Note Specify Location::, for a description of the |
| different forms of LOCATION. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `jump'. |
| |
| Example |
| ....... |
| |
| -exec-jump foo.c:10 |
| *running,thread-id="all" |
| ^running |
| |
| The `-exec-next' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-next [--reverse] |
| |
| Resumes execution of the inferior program, stopping when the |
| beginning of the next source line is reached. |
| |
| If the `--reverse' option is specified, resumes reverse execution of |
| the inferior program, stopping at the beginning of the previous source |
| line. If you issue this command on the first line of a function, it |
| will take you back to the caller of that function, to the source line |
| where the function was called. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `next'. |
| |
| Example |
| ....... |
| |
| -exec-next |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="8",file="hello.c" |
| (gdb) |
| |
| The `-exec-next-instruction' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-next-instruction [--reverse] |
| |
| Executes one machine instruction. If the instruction is a function |
| call, continues until the function returns. If the program stops at an |
| instruction in the middle of a source line, the address will be printed |
| as well. |
| |
| If the `--reverse' option is specified, resumes reverse execution of |
| the inferior program, stopping at the previous instruction. If the |
| previously executed instruction was a return from another function, it |
| will continue to execute in reverse until the call to that function |
| (from the current stack frame) is reached. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `nexti'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-next-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| addr="0x000100d4",line="5",file="hello.c" |
| (gdb) |
| |
| The `-exec-return' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-return |
| |
| Makes current function return immediately. Doesn't execute the |
| inferior. Displays the new current frame. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `return'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| 200-break-insert callee4 |
| 200^done,bkpt={number="1",addr="0x00010734", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} |
| (gdb) |
| 000-exec-run |
| 000^running |
| (gdb) |
| 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", |
| frame={func="callee4",args=[], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"} |
| (gdb) |
| 205-break-delete |
| 205^done |
| (gdb) |
| 111-exec-return |
| 111^done,frame={level="0",func="callee3", |
| args=[{name="strarg", |
| value="0x11940 \"A string argument.\""}], |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} |
| (gdb) |
| |
| The `-exec-run' Command |
| ----------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-run [--all | --thread-group N] |
| |
| Starts execution of the inferior from the beginning. The inferior |
| executes until either a breakpoint is encountered or the program exits. |
| In the latter case the output will include an exit code, if the |
| program has exited exceptionally. |
| |
| When no option is specified, the current inferior is started. If the |
| `--thread-group' option is specified, it should refer to a thread group |
| of type `process', and that thread group will be started. If the |
| `--all' option is specified, then all inferiors will be started. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `run'. |
| |
| Examples |
| ........ |
| |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", |
| frame={func="main",args=[],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="4"} |
| (gdb) |
| |
| Program exited normally: |
| |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited-normally" |
| (gdb) |
| |
| Program exited exceptionally: |
| |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="exited",exit-code="01" |
| (gdb) |
| |
| Another way the program can terminate is if it receives a signal |
| such as `SIGINT'. In this case, GDB/MI displays this: |
| |
| (gdb) |
| *stopped,reason="exited-signalled",signal-name="SIGINT", |
| signal-meaning="Interrupt" |
| |
| The `-exec-step' Command |
| ------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-step [--reverse] |
| |
| Resumes execution of the inferior program, stopping when the |
| beginning of the next source line is reached, if the next source line |
| is not a function call. If it is, stop at the first instruction of the |
| called function. If the `--reverse' option is specified, resumes |
| reverse execution of the inferior program, stopping at the beginning of |
| the previously executed source line. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `step'. |
| |
| Example |
| ....... |
| |
| Stepping into a function: |
| |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={func="foo",args=[{name="a",value="10"}, |
| {name="b",value="0"}],file="recursive2.c", |
| fullname="/home/foo/bar/recursive2.c",line="11"} |
| (gdb) |
| |
| Regular stepping: |
| |
| -exec-step |
| ^running |
| (gdb) |
| *stopped,reason="end-stepping-range",line="14",file="recursive2.c" |
| (gdb) |
| |
| The `-exec-step-instruction' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -exec-step-instruction [--reverse] |
| |
| Resumes the inferior which executes one machine instruction. If the |
| `--reverse' option is specified, resumes reverse execution of the |
| inferior program, stopping at the previously executed instruction. The |
| output, once GDB has stopped, will vary depending on whether we have |
| stopped in the middle of a source line or not. In the former case, the |
| address at which the program stopped will be printed as well. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `stepi'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="10"} |
| (gdb) |
| -exec-step-instruction |
| ^running |
| |
| (gdb) |
| *stopped,reason="end-stepping-range", |
| frame={addr="0x000100f4",func="foo",args=[],file="try.c", |
| fullname="/home/foo/bar/try.c",line="10"} |
| (gdb) |
| |
| The `-exec-until' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -exec-until [ LOCATION ] |
| |
| Executes the inferior until the LOCATION specified in the argument |
| is reached. If there is no argument, the inferior executes until a |
| source line greater than the current one is reached. The reason for |
| stopping in this case will be `location-reached'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `until'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -exec-until recursive2.c:6 |
| ^running |
| (gdb) |
| x = 55 |
| *stopped,reason="location-reached",frame={func="main",args=[], |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI |
| |
| 27.13 GDB/MI Stack Manipulation Commands |
| ======================================== |
| |
| The `-stack-info-frame' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-info-frame |
| |
| Get info on the selected frame. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `info frame' or `frame' (without |
| arguments). |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-info-frame |
| ^done,frame={level="1",addr="0x0001076c",func="callee3", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"} |
| (gdb) |
| |
| The `-stack-info-depth' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-info-depth [ MAX-DEPTH ] |
| |
| Return the depth of the stack. If the integer argument MAX-DEPTH is |
| specified, do not count beyond MAX-DEPTH frames. |
| |
| GDB Command |
| ........... |
| |
| There's no equivalent GDB command. |
| |
| Example |
| ....... |
| |
| For a stack with frame levels 0 through 11: |
| |
| (gdb) |
| -stack-info-depth |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 4 |
| ^done,depth="4" |
| (gdb) |
| -stack-info-depth 12 |
| ^done,depth="12" |
| (gdb) |
| -stack-info-depth 11 |
| ^done,depth="11" |
| (gdb) |
| -stack-info-depth 13 |
| ^done,depth="12" |
| (gdb) |
| |
| The `-stack-list-arguments' Command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-arguments PRINT-VALUES |
| [ LOW-FRAME HIGH-FRAME ] |
| |
| Display a list of the arguments for the frames between LOW-FRAME and |
| HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, |
| list the arguments for the whole call stack. If the two arguments are |
| equal, show the single frame at the corresponding level. It is an |
| error if LOW-FRAME is larger than the actual number of frames. On the |
| other hand, HIGH-FRAME may be larger than the actual number of frames, |
| in which case only existing frames will be returned. |
| |
| If PRINT-VALUES is 0 or `--no-values', print only the names of the |
| variables; if it is 1 or `--all-values', print also their values; and |
| if it is 2 or `--simple-values', print the name, type and value for |
| simple data types, and the name and type for arrays, structures and |
| unions. |
| |
| Use of this command to obtain arguments in a single frame is |
| deprecated in favor of the `-stack-list-variables' command. |
| |
| GDB Command |
| ........... |
| |
| GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args' |
| command which partially overlaps with the functionality of |
| `-stack-list-arguments'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-frames |
| ^done, |
| stack=[ |
| frame={level="0",addr="0x00010734",func="callee4", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, |
| frame={level="1",addr="0x0001076c",func="callee3", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, |
| frame={level="2",addr="0x0001078c",func="callee2", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, |
| frame={level="3",addr="0x000107b4",func="callee1", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, |
| frame={level="4",addr="0x000107e0",func="main", |
| file="../../../devo/gdb/testsuite/gdb.mi/basics.c", |
| fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] |
| (gdb) |
| -stack-list-arguments 0 |
| ^done, |
| stack-args=[ |
| frame={level="0",args=[]}, |
| frame={level="1",args=[name="strarg"]}, |
| frame={level="2",args=[name="intarg",name="strarg"]}, |
| frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, |
| frame={level="4",args=[]}] |
| (gdb) |
| -stack-list-arguments 1 |
| ^done, |
| stack-args=[ |
| frame={level="0",args=[]}, |
| frame={level="1", |
| args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, |
| frame={level="2",args=[ |
| {name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}]}, |
| {frame={level="3",args=[ |
| {name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}, |
| {name="fltarg",value="3.5"}]}, |
| frame={level="4",args=[]}] |
| (gdb) |
| -stack-list-arguments 0 2 2 |
| ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] |
| (gdb) |
| -stack-list-arguments 1 2 2 |
| ^done,stack-args=[frame={level="2", |
| args=[{name="intarg",value="2"}, |
| {name="strarg",value="0x11940 \"A string argument.\""}]}] |
| (gdb) |
| |
| The `-stack-list-frames' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-frames [ LOW-FRAME HIGH-FRAME ] |
| |
| List the frames currently on the stack. For each frame it displays |
| the following info: |
| |
| `LEVEL' |
| The frame number, 0 being the topmost frame, i.e., the innermost |
| function. |
| |
| `ADDR' |
| The `$pc' value for that frame. |
| |
| `FUNC' |
| Function name. |
| |
| `FILE' |
| File name of the source file where the function lives. |
| |
| `FULLNAME' |
| The full file name of the source file where the function lives. |
| |
| `LINE' |
| Line number corresponding to the `$pc'. |
| |
| `FROM' |
| The shared library where this function is defined. This is only |
| given if the frame's function is not known. |
| |
| If invoked without arguments, this command prints a backtrace for the |
| whole stack. If given two integer arguments, it shows the frames whose |
| levels are between the two arguments (inclusive). If the two arguments |
| are equal, it shows the single frame at the corresponding level. It is |
| an error if LOW-FRAME is larger than the actual number of frames. On |
| the other hand, HIGH-FRAME may be larger than the actual number of |
| frames, in which case only existing frames will be returned. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `backtrace' and `where'. |
| |
| Example |
| ....... |
| |
| Full stack backtrace: |
| |
| (gdb) |
| -stack-list-frames |
| ^done,stack= |
| [frame={level="0",addr="0x0001076c",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"}, |
| frame={level="1",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="2",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="4",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="5",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="6",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="7",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="8",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="9",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="10",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="11",addr="0x00010738",func="main", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}] |
| (gdb) |
| |
| Show frames between LOW_FRAME and HIGH_FRAME: |
| |
| (gdb) |
| -stack-list-frames 3 5 |
| ^done,stack= |
| [frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="4",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, |
| frame={level="5",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] |
| (gdb) |
| |
| Show a single frame: |
| |
| (gdb) |
| -stack-list-frames 3 3 |
| ^done,stack= |
| [frame={level="3",addr="0x000107a4",func="foo", |
| file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] |
| (gdb) |
| |
| The `-stack-list-locals' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-locals PRINT-VALUES |
| |
| Display the local variable names for the selected frame. If |
| PRINT-VALUES is 0 or `--no-values', print only the names of the |
| variables; if it is 1 or `--all-values', print also their values; and |
| if it is 2 or `--simple-values', print the name, type and value for |
| simple data types, and the name and type for arrays, structures and |
| unions. In this last case, a frontend can immediately display the |
| value of simple data types and create variable objects for other data |
| types when the user wishes to explore their values in more detail. |
| |
| This command is deprecated in favor of the `-stack-list-variables' |
| command. |
| |
| GDB Command |
| ........... |
| |
| `info locals' in GDB, `gdb_get_locals' in `gdbtk'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-locals 0 |
| ^done,locals=[name="A",name="B",name="C"] |
| (gdb) |
| -stack-list-locals --all-values |
| ^done,locals=[{name="A",value="1"},{name="B",value="2"}, |
| {name="C",value="{1, 2, 3}"}] |
| -stack-list-locals --simple-values |
| ^done,locals=[{name="A",type="int",value="1"}, |
| {name="B",type="int",value="2"},{name="C",type="int [3]"}] |
| (gdb) |
| |
| The `-stack-list-variables' Command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-list-variables PRINT-VALUES |
| |
| Display the names of local variables and function arguments for the |
| selected frame. If PRINT-VALUES is 0 or `--no-values', print only the |
| names of the variables; if it is 1 or `--all-values', print also their |
| values; and if it is 2 or `--simple-values', print the name, type and |
| value for simple data types, and the name and type for arrays, |
| structures and unions. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-list-variables --thread 1 --frame 0 --all-values |
| ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] |
| (gdb) |
| |
| The `-stack-select-frame' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -stack-select-frame FRAMENUM |
| |
| Change the selected frame. Select a different frame FRAMENUM on the |
| stack. |
| |
| This command in deprecated in favor of passing the `--frame' option |
| to every command. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `frame', `up', `down', |
| `select-frame', `up-silent', and `down-silent'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -stack-select-frame 2 |
| ^done |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI |
| |
| 27.14 GDB/MI Variable Objects |
| ============================= |
| |
| Introduction to Variable Objects |
| -------------------------------- |
| |
| Variable objects are "object-oriented" MI interface for examining and |
| changing values of expressions. Unlike some other MI interfaces that |
| work with expressions, variable objects are specifically designed for |
| simple and efficient presentation in the frontend. A variable object |
| is identified by string name. When a variable object is created, the |
| frontend specifies the expression for that variable object. The |
| expression can be a simple variable, or it can be an arbitrary complex |
| expression, and can even involve CPU registers. After creating a |
| variable object, the frontend can invoke other variable object |
| operations--for example to obtain or change the value of a variable |
| object, or to change display format. |
| |
| Variable objects have hierarchical tree structure. Any variable |
| object that corresponds to a composite type, such as structure in C, has |
| a number of child variable objects, for example corresponding to each |
| element of a structure. A child variable object can itself have |
| children, recursively. Recursion ends when we reach leaf variable |
| objects, which always have built-in types. Child variable objects are |
| created only by explicit request, so if a frontend is not interested in |
| the children of a particular variable object, no child will be created. |
| |
| For a leaf variable object it is possible to obtain its value as a |
| string, or set the value from a string. String value can be also |
| obtained for a non-leaf variable object, but it's generally a string |
| that only indicates the type of the object, and does not list its |
| contents. Assignment to a non-leaf variable object is not allowed. |
| |
| A frontend does not need to read the values of all variable objects |
| each time the program stops. Instead, MI provides an update command |
| that lists all variable objects whose values has changed since the last |
| update operation. This considerably reduces the amount of data that |
| must be transferred to the frontend. As noted above, children variable |
| objects are created on demand, and only leaf variable objects have a |
| real value. As result, gdb will read target memory only for leaf |
| variables that frontend has created. |
| |
| The automatic update is not always desirable. For example, a |
| frontend might want to keep a value of some expression for future |
| reference, and never update it. For another example, fetching memory |
| is relatively slow for embedded targets, so a frontend might want to |
| disable automatic update for the variables that are either not visible |
| on the screen, or "closed". This is possible using so called "frozen |
| variable objects". Such variable objects are never implicitly updated. |
| |
| Variable objects can be either "fixed" or "floating". For the fixed |
| variable object, the expression is parsed when the variable object is |
| created, including associating identifiers to specific variables. The |
| meaning of expression never changes. For a floating variable object |
| the values of variables whose names appear in the expressions are |
| re-evaluated every time in the context of the current frame. Consider |
| this example: |
| |
| void do_work(...) |
| { |
| struct work_state state; |
| |
| if (...) |
| do_work(...); |
| } |
| |
| If a fixed variable object for the `state' variable is created in |
| this function, and we enter the recursive call, the variable object |
| will report the value of `state' in the top-level `do_work' invocation. |
| On the other hand, a floating variable object will report the value of |
| `state' in the current frame. |
| |
| If an expression specified when creating a fixed variable object |
| refers to a local variable, the variable object becomes bound to the |
| thread and frame in which the variable object is created. When such |
| variable object is updated, GDB makes sure that the thread/frame |
| combination the variable object is bound to still exists, and |
| re-evaluates the variable object in context of that thread/frame. |
| |
| The following is the complete set of GDB/MI operations defined to |
| access this functionality: |
| |
| *Operation* *Description* |
| `-enable-pretty-printing' enable Python-based pretty-printing |
| `-var-create' create a variable object |
| `-var-delete' delete the variable object and/or its |
| children |
| `-var-set-format' set the display format of this variable |
| `-var-show-format' show the display format of this variable |
| `-var-info-num-children' tells how many children this object has |
| `-var-list-children' return a list of the object's children |
| `-var-info-type' show the type of this variable object |
| `-var-info-expression' print parent-relative expression that this |
| variable object represents |
| `-var-info-path-expression' print full expression that this variable |
| object represents |
| `-var-show-attributes' is this variable editable? does it exist |
| here? |
| `-var-evaluate-expression' get the value of this variable |
| `-var-assign' set the value of this variable |
| `-var-update' update the variable and its children |
| `-var-set-frozen' set frozeness attribute |
| `-var-set-update-range' set range of children to display on update |
| |
| In the next subsection we describe each operation in detail and |
| suggest how it can be used. |
| |
| Description And Use of Operations on Variable Objects |
| ----------------------------------------------------- |
| |
| The `-enable-pretty-printing' Command |
| ------------------------------------- |
| |
| -enable-pretty-printing |
| |
| GDB allows Python-based visualizers to affect the output of the MI |
| variable object commands. However, because there was no way to |
| implement this in a fully backward-compatible way, a front end must |
| request that this functionality be enabled. |
| |
| Once enabled, this feature cannot be disabled. |
| |
| Note that if Python support has not been compiled into GDB, this |
| command will still succeed (and do nothing). |
| |
| This feature is currently (as of GDB 7.0) experimental, and may work |
| differently in future versions of GDB. |
| |
| The `-var-create' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-create {NAME | "-"} |
| {FRAME-ADDR | "*" | "@"} EXPRESSION |
| |
| This operation creates a variable object, which allows the |
| monitoring of a variable, the result of an expression, a memory cell or |
| a CPU register. |
| |
| The NAME parameter is the string by which the object can be |
| referenced. It must be unique. If `-' is specified, the varobj system |
| will generate a string "varNNNNNN" automatically. It will be unique |
| provided that one does not specify NAME of that format. The command |
| fails if a duplicate name is found. |
| |
| The frame under which the expression should be evaluated can be |
| specified by FRAME-ADDR. A `*' indicates that the current frame should |
| be used. A `@' indicates that a floating variable object must be |
| created. |
| |
| EXPRESSION is any expression valid on the current language set (must |
| not begin with a `*'), or one of the following: |
| |
| * `*ADDR', where ADDR is the address of a memory cell |
| |
| * `*ADDR-ADDR' -- a memory address range (TBD) |
| |
| * `$REGNAME' -- a CPU register name |
| |
| A varobj's contents may be provided by a Python-based |
| pretty-printer. In this case the varobj is known as a "dynamic |
| varobj". Dynamic varobjs have slightly different semantics in some |
| cases. If the `-enable-pretty-printing' command is not sent, then GDB |
| will never create a dynamic varobj. This ensures backward |
| compatibility for existing clients. |
| |
| Result |
| ...... |
| |
| This operation returns attributes of the newly-created varobj. These |
| are: |
| |
| `name' |
| The name of the varobj. |
| |
| `numchild' |
| The number of children of the varobj. This number is not |
| necessarily reliable for a dynamic varobj. Instead, you must |
| examine the `has_more' attribute. |
| |
| `value' |
| The varobj's scalar value. For a varobj whose type is some sort of |
| aggregate (e.g., a `struct'), or for a dynamic varobj, this value |
| will not be interesting. |
| |
| `type' |
| The varobj's type. This is a string representation of the type, as |
| 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 |
| the thread's identifier. |
| |
| `has_more' |
| For a dynamic varobj, this indicates whether there appear to be any |
| children available. For a non-dynamic varobj, this will be 0. |
| |
| `dynamic' |
| This attribute will be present and have the value `1' if the |
| varobj is a dynamic varobj. If the varobj is not a dynamic varobj, |
| then this attribute will not be present. |
| |
| `displayhint' |
| A dynamic varobj can supply a display hint to the front end. The |
| value comes directly from the Python pretty-printer object's |
| `display_hint' method. *Note Pretty Printing API::. |
| |
| Typical output will look like this: |
| |
| name="NAME",numchild="N",type="TYPE",thread-id="M", |
| has_more="HAS_MORE" |
| |
| The `-var-delete' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-delete [ -c ] NAME |
| |
| Deletes a previously created variable object and all of its children. |
| With the `-c' option, just deletes the children. |
| |
| Returns an error if the object NAME is not found. |
| |
| The `-var-set-format' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-format NAME FORMAT-SPEC |
| |
| Sets the output format for the value of the object NAME to be |
| FORMAT-SPEC. |
| |
| The syntax for the FORMAT-SPEC is as follows: |
| |
| FORMAT-SPEC ==> |
| {binary | decimal | hexadecimal | octal | natural} |
| |
| The natural format is the default format choosen automatically based |
| on the variable type (like decimal for an `int', hex for pointers, |
| etc.). |
| |
| For a variable with children, the format is set only on the variable |
| itself, and the children are not affected. |
| |
| The `-var-show-format' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -var-show-format NAME |
| |
| Returns the format used to display the value of the object NAME. |
| |
| FORMAT ==> |
| FORMAT-SPEC |
| |
| The `-var-info-num-children' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -var-info-num-children NAME |
| |
| Returns the number of children of a variable object NAME: |
| |
| numchild=N |
| |
| Note that this number is not completely reliable for a dynamic |
| varobj. It will return the current number of children, but more |
| children may be available. |
| |
| The `-var-list-children' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-list-children [PRINT-VALUES] NAME [FROM TO] |
| |
| Return a list of the children of the specified variable object and |
| create variable objects for them, if they do not already exist. With a |
| single argument or if PRINT-VALUES has a value of 0 or `--no-values', |
| print only the names of the variables; if PRINT-VALUES is 1 or |
| `--all-values', also print their values; and if it is 2 or |
| `--simple-values' print the name and value for simple data types and |
| just the name for arrays, structures and unions. |
| |
| FROM and TO, if specified, indicate the range of children to report. |
| If FROM or TO is less than zero, the range is reset and all children |
| will be reported. Otherwise, children starting at FROM (zero-based) |
| and up to and excluding TO will be reported. |
| |
| If a child range is requested, it will only affect the current call |
| to `-var-list-children', but not future calls to `-var-update'. For |
| this, you must instead use `-var-set-update-range'. The intent of this |
| approach is to enable a front end to implement any update approach it |
| likes; for example, scrolling a view may cause the front end to request |
| more children with `-var-list-children', and then the front end could |
| call `-var-set-update-range' with a different range to ensure that |
| future updates are restricted to just the visible items. |
| |
| For each child the following results are returned: |
| |
| NAME |
| Name of the variable object created for this child. |
| |
| EXP |
| The expression to be shown to the user by the front end to |
| designate this child. For example this may be the name of a |
| structure member. |
| |
| For a dynamic varobj, this value cannot be used to form an |
| expression. There is no way to do this at all with a dynamic |
| varobj. |
| |
| For C/C++ structures there are several pseudo children returned to |
| designate access qualifiers. For these pseudo children EXP is |
| `public', `private', or `protected'. In this case the type and |
| value are not present. |
| |
| A dynamic varobj will not report the access qualifying |
| pseudo-children, regardless of the language. This information is |
| not available at all with a dynamic varobj. |
| |
| NUMCHILD |
| Number of children this child has. For a dynamic varobj, this |
| will be 0. |
| |
| TYPE |
| 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. |
| |
| THREAD-ID |
| If this variable object is associated with a thread, this is the |
| thread id. Otherwise this result is not present. |
| |
| FROZEN |
| If the variable object is frozen, this variable will be present |
| with a value of 1. |
| |
| The result may have its own attributes: |
| |
| `displayhint' |
| A dynamic varobj can supply a display hint to the front end. The |
| value comes directly from the Python pretty-printer object's |
| `display_hint' method. *Note Pretty Printing API::. |
| |
| `has_more' |
| This is an integer attribute which is nonzero if there are children |
| remaining after the end of the selected range. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-list-children n |
| ^done,numchild=N,children=[child={name=NAME,exp=EXP, |
| numchild=N,type=TYPE},(repeats N times)] |
| (gdb) |
| -var-list-children --all-values n |
| ^done,numchild=N,children=[child={name=NAME,exp=EXP, |
| numchild=N,value=VALUE,type=TYPE},(repeats N times)] |
| |
| The `-var-info-type' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-type NAME |
| |
| Returns the type of the specified variable NAME. The type is |
| returned as a string in the same format as it is output by the GDB CLI: |
| |
| type=TYPENAME |
| |
| The `-var-info-expression' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-expression NAME |
| |
| Returns a string that is suitable for presenting this variable |
| object in user interface. The string is generally not valid expression |
| in the current language, and cannot be evaluated. |
| |
| For example, if `a' is an array, and variable object `A' was created |
| for `a', then we'll get this output: |
| |
| (gdb) -var-info-expression A.1 |
| ^done,lang="C",exp="1" |
| |
| Here, the values of `lang' can be `{"C" | "C++" | "Java"}'. |
| |
| Note that the output of the `-var-list-children' command also |
| includes those expressions, so the `-var-info-expression' command is of |
| limited use. |
| |
| The `-var-info-path-expression' Command |
| --------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-info-path-expression NAME |
| |
| Returns an expression that can be evaluated in the current context |
| and will yield the same value that a variable object has. Compare this |
| with the `-var-info-expression' command, which result can be used only |
| for UI presentation. Typical use of the `-var-info-path-expression' |
| command is creating a watchpoint from a variable object. |
| |
| This command is currently not valid for children of a dynamic varobj, |
| and will give an error when invoked on one. |
| |
| For example, suppose `C' is a C++ class, derived from class `Base', |
| and that the `Base' class has a member called `m_size'. Assume a |
| variable `c' is has the type of `C' and a variable object `C' was |
| created for variable `c'. Then, we'll get this output: |
| (gdb) -var-info-path-expression C.Base.public.m_size |
| ^done,path_expr=((Base)c).m_size) |
| |
| The `-var-show-attributes' Command |
| ---------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-show-attributes NAME |
| |
| List attributes of the specified variable object NAME: |
| |
| status=ATTR [ ( ,ATTR )* ] |
| |
| where ATTR is `{ { editable | noneditable } | TBD }'. |
| |
| The `-var-evaluate-expression' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-evaluate-expression [-f FORMAT-SPEC] NAME |
| |
| Evaluates the expression that is represented by the specified |
| variable object and returns its value as a string. The format of the |
| string can be specified with the `-f' option. The possible values of |
| this option are the same as for `-var-set-format' (*note |
| -var-set-format::). If the `-f' option is not specified, the current |
| display format will be used. The current display format can be changed |
| using the `-var-set-format' command. |
| |
| value=VALUE |
| |
| Note that one must invoke `-var-list-children' for a variable before |
| the value of a child variable can be evaluated. |
| |
| The `-var-assign' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-assign NAME EXPRESSION |
| |
| Assigns the value of EXPRESSION to the variable object specified by |
| NAME. The object must be `editable'. If the variable's value is |
| altered by the assign, the variable will show up in any subsequent |
| `-var-update' list. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-assign var1 3 |
| ^done,value="3" |
| (gdb) |
| -var-update * |
| ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] |
| (gdb) |
| |
| The `-var-update' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-update [PRINT-VALUES] {NAME | "*"} |
| |
| Reevaluate the expressions corresponding to the variable object NAME |
| and all its direct and indirect children, and return the list of |
| variable objects whose values have changed; NAME must be a root |
| variable object. Here, "changed" means that the result of |
| `-var-evaluate-expression' before and after the `-var-update' is |
| different. If `*' is used as the variable object names, all existing |
| variable objects are updated, except for frozen ones (*note |
| -var-set-frozen::). The option PRINT-VALUES determines whether both |
| names and values, or just names are printed. The possible values of |
| this option are the same as for `-var-list-children' (*note |
| -var-list-children::). It is recommended to use the `--all-values' |
| option, to reduce the number of MI commands needed on each program stop. |
| |
| With the `*' parameter, if a variable object is bound to a currently |
| running thread, it will not be updated, without any diagnostic. |
| |
| If `-var-set-update-range' was previously used on a varobj, then |
| only the selected range of children will be reported. |
| |
| `-var-update' reports all the changed varobjs in a tuple named |
| `changelist'. |
| |
| Each item in the change list is itself a tuple holding: |
| |
| `name' |
| The name of the varobj. |
| |
| `value' |
| If values were requested for this update, then this field will be |
| present and will hold the value of the varobj. |
| |
| `in_scope' |
| This field is a string which may take one of three values: |
| |
| `"true"' |
| The variable object's current value is valid. |
| |
| `"false"' |
| The variable object does not currently hold a valid value but |
| it may hold one in the future if its associated expression |
| comes back into scope. |
| |
| `"invalid"' |
| The variable object no longer holds a valid value. This can |
| occur when the executable file being debugged has changed, |
| either through recompilation or by using the GDB `file' |
| command. The front end should normally choose to delete |
| these variable objects. |
| |
| In the future new values may be added to this list so the front |
| should be prepared for this possibility. *Note GDB/MI Development |
| and Front Ends: GDB/MI Development and Front Ends. |
| |
| `type_changed' |
| This is only present if the varobj is still valid. If the type |
| 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. |
| |
| `new_num_children' |
| For a dynamic varobj, if the number of children changed, or if the |
| type changed, this will be the new number of children. |
| |
| The `numchild' field in other varobj responses is generally not |
| valid for a dynamic varobj - it will show the number of children |
| that GDB knows about, but because dynamic varobjs lazily |
| instantiate their children, this will not reflect the number of |
| children which may be available. |
| |
| The `new_num_children' attribute only reports changes to the |
| number of children known by GDB. This is the only way to detect |
| whether an update has removed children (which necessarily can only |
| happen at the end of the update range). |
| |
| `displayhint' |
| The display hint, if any. |
| |
| `has_more' |
| This is an integer value, which will be 1 if there are more |
| children available outside the varobj's update range. |
| |
| `dynamic' |
| This attribute will be present and have the value `1' if the |
| varobj is a dynamic varobj. If the varobj is not a dynamic varobj, |
| then this attribute will not be present. |
| |
| `new_children' |
| If new children were added to a dynamic varobj within the selected |
| update range (as set by `-var-set-update-range'), then they will |
| be listed in this attribute. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-assign var1 3 |
| ^done,value="3" |
| (gdb) |
| -var-update --all-values var1 |
| ^done,changelist=[{name="var1",value="3",in_scope="true", |
| type_changed="false"}] |
| (gdb) |
| |
| The `-var-set-frozen' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-frozen NAME FLAG |
| |
| Set the frozenness flag on the variable object NAME. The FLAG |
| parameter should be either `1' to make the variable frozen or `0' to |
| make it unfrozen. If a variable object is frozen, then neither itself, |
| nor any of its children, are implicitly updated by `-var-update' of a |
| parent variable or by `-var-update *'. Only `-var-update' of the |
| variable itself will update its value and values of its children. |
| After a variable object is unfrozen, it is implicitly updated by all |
| subsequent `-var-update' operations. Unfreezing a variable does not |
| update it, only subsequent `-var-update' does. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-set-frozen V 1 |
| ^done |
| (gdb) |
| |
| The `-var-set-update-range' command |
| ----------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-update-range NAME FROM TO |
| |
| Set the range of children to be returned by future invocations of |
| `-var-update'. |
| |
| FROM and TO indicate the range of children to report. If FROM or TO |
| is less than zero, the range is reset and all children will be |
| reported. Otherwise, children starting at FROM (zero-based) and up to |
| and excluding TO will be reported. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -var-set-update-range V 1 2 |
| ^done |
| |
| The `-var-set-visualizer' command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -var-set-visualizer NAME VISUALIZER |
| |
| Set a visualizer for the variable object NAME. |
| |
| VISUALIZER is the visualizer to use. The special value `None' means |
| to disable any visualizer in use. |
| |
| If not `None', VISUALIZER must be a Python expression. This |
| expression must evaluate to a callable object which accepts a single |
| argument. GDB will call this object with the value of the varobj NAME |
| as an argument (this is done so that the same Python pretty-printing |
| code can be used for both the CLI and MI). When called, this object |
| must return an object which conforms to the pretty-printing interface |
| (*note Pretty Printing API::). |
| |
| The pre-defined function `gdb.default_visualizer' may be used to |
| select a visualizer by following the built-in process (*note Selecting |
| Pretty-Printers::). This is done automatically when a varobj is |
| created, and so ordinarily is not needed. |
| |
| This feature is only available if Python support is enabled. The MI |
| command `-list-features' (*note GDB/MI Miscellaneous Commands::) can be |
| used to check this. |
| |
| Example |
| ....... |
| |
| Resetting the visualizer: |
| |
| (gdb) |
| -var-set-visualizer V None |
| ^done |
| |
| Reselecting the default (type-based) visualizer: |
| |
| (gdb) |
| -var-set-visualizer V gdb.default_visualizer |
| ^done |
| |
| Suppose `SomeClass' is a visualizer class. A lambda expression can |
| be used to instantiate this class for a varobj: |
| |
| (gdb) |
| -var-set-visualizer V "lambda val: SomeClass()" |
| ^done |
| |
| |
| File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI |
| |
| 27.15 GDB/MI Data Manipulation |
| ============================== |
| |
| This section describes the GDB/MI commands that manipulate data: |
| examine memory and registers, evaluate expressions, etc. |
| |
| The `-data-disassemble' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-disassemble |
| [ -s START-ADDR -e END-ADDR ] |
| | [ -f FILENAME -l LINENUM [ -n LINES ] ] |
| -- MODE |
| |
| Where: |
| |
| `START-ADDR' |
| is the beginning address (or `$pc') |
| |
| `END-ADDR' |
| is the end address |
| |
| `FILENAME' |
| is the name of the file to disassemble |
| |
| `LINENUM' |
| is the line number to disassemble around |
| |
| `LINES' |
| is the number of disassembly lines to be produced. If it is -1, |
| the whole function will be disassembled, in case no END-ADDR is |
| specified. If END-ADDR is specified as a non-zero value, and |
| LINES is lower than the number of disassembly lines between |
| START-ADDR and END-ADDR, only LINES lines are displayed; if LINES |
| is higher than the number of lines between START-ADDR and |
| END-ADDR, only the lines up to END-ADDR are displayed. |
| |
| `MODE' |
| is either 0 (meaning only disassembly), 1 (meaning mixed source and |
| disassembly), 2 (meaning disassembly with raw opcodes), or 3 |
| (meaning mixed source and disassembly with raw opcodes). |
| |
| Result |
| ...... |
| |
| The output for each instruction is composed of four fields: |
| |
| * Address |
| |
| * Func-name |
| |
| * Offset |
| |
| * Instruction |
| |
| Note that whatever included in the instruction field, is not |
| manipulated directly by GDB/MI, i.e., it is not possible to adjust its |
| format. |
| |
| GDB Command |
| ........... |
| |
| There's no direct mapping from this command to the CLI. |
| |
| Example |
| ....... |
| |
| Disassemble from the current value of `$pc' to `$pc + 20': |
| |
| (gdb) |
| -data-disassemble -s $pc -e "$pc + 20" -- 0 |
| ^done, |
| asm_insns=[ |
| {address="0x000107c0",func-name="main",offset="4", |
| inst="mov 2, %o0"}, |
| {address="0x000107c4",func-name="main",offset="8", |
| inst="sethi %hi(0x11800), %o2"}, |
| {address="0x000107c8",func-name="main",offset="12", |
| inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, |
| {address="0x000107cc",func-name="main",offset="16", |
| inst="sethi %hi(0x11800), %o2"}, |
| {address="0x000107d0",func-name="main",offset="20", |
| inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] |
| (gdb) |
| |
| Disassemble the whole `main' function. Line 32 is part of `main'. |
| |
| -data-disassemble -f basics.c -l 32 -- 0 |
| ^done,asm_insns=[ |
| {address="0x000107bc",func-name="main",offset="0", |
| inst="save %sp, -112, %sp"}, |
| {address="0x000107c0",func-name="main",offset="4", |
| inst="mov 2, %o0"}, |
| {address="0x000107c4",func-name="main",offset="8", |
| inst="sethi %hi(0x11800), %o2"}, |
| [...] |
| {address="0x0001081c",func-name="main",offset="96",inst="ret "}, |
| {address="0x00010820",func-name="main",offset="100",inst="restore "}] |
| (gdb) |
| |
| Disassemble 3 instructions from the start of `main': |
| |
| (gdb) |
| -data-disassemble -f basics.c -l 32 -n 3 -- 0 |
| ^done,asm_insns=[ |
| {address="0x000107bc",func-name="main",offset="0", |
| inst="save %sp, -112, %sp"}, |
| {address="0x000107c0",func-name="main",offset="4", |
| inst="mov 2, %o0"}, |
| {address="0x000107c4",func-name="main",offset="8", |
| inst="sethi %hi(0x11800), %o2"}] |
| (gdb) |
| |
| Disassemble 3 instructions from the start of `main' in mixed mode: |
| |
| (gdb) |
| -data-disassemble -f basics.c -l 32 -n 3 -- 1 |
| ^done,asm_insns=[ |
| src_and_asm_line={line="31", |
| file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ |
| testsuite/gdb.mi/basics.c",line_asm_insn=[ |
| {address="0x000107bc",func-name="main",offset="0", |
| inst="save %sp, -112, %sp"}]}, |
| src_and_asm_line={line="32", |
| file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ |
| testsuite/gdb.mi/basics.c",line_asm_insn=[ |
| {address="0x000107c0",func-name="main",offset="4", |
| inst="mov 2, %o0"}, |
| {address="0x000107c4",func-name="main",offset="8", |
| inst="sethi %hi(0x11800), %o2"}]}] |
| (gdb) |
| |
| The `-data-evaluate-expression' Command |
| --------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-evaluate-expression EXPR |
| |
| Evaluate EXPR as an expression. The expression could contain an |
| inferior function call. The function call will execute synchronously. |
| If the expression contains spaces, it must be enclosed in double quotes. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `print', `output', and `call'. In |
| `gdbtk' only, there's a corresponding `gdb_eval' command. |
| |
| Example |
| ....... |
| |
| In the following example, the numbers that precede the commands are the |
| "tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command |
| Syntax. Notice how GDB/MI returns the same tokens in its output. |
| |
| 211-data-evaluate-expression A |
| 211^done,value="1" |
| (gdb) |
| 311-data-evaluate-expression &A |
| 311^done,value="0xefffeb7c" |
| (gdb) |
| 411-data-evaluate-expression A+3 |
| 411^done,value="4" |
| (gdb) |
| 511-data-evaluate-expression "A + 3" |
| 511^done,value="4" |
| (gdb) |
| |
| The `-data-list-changed-registers' Command |
| ------------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -data-list-changed-registers |
| |
| Display a list of the registers that have changed. |
| |
| GDB Command |
| ........... |
| |
| GDB doesn't have a direct analog for this command; `gdbtk' has the |
| corresponding command `gdb_changed_register_list'. |
| |
| Example |
| ....... |
| |
| On a PPC MBX board: |
| |
| (gdb) |
| -exec-continue |
| ^running |
| |
| (gdb) |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={ |
| func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", |
| line="5"} |
| (gdb) |
| -data-list-changed-registers |
| ^done,changed-registers=["0","1","2","4","5","6","7","8","9", |
| "10","11","13","14","15","16","17","18","19","20","21","22","23", |
| "24","25","26","27","28","30","31","64","65","66","67","69"] |
| (gdb) |
| |
| The `-data-list-register-names' Command |
| --------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-list-register-names [ ( REGNO )+ ] |
| |
| Show a list of register names for the current target. If no |
| arguments are given, it shows a list of the names of all the registers. |
| If integer numbers are given as arguments, it will print a list of the |
| names of the registers corresponding to the arguments. To ensure |
| consistency between a register name and its number, the output list may |
| include empty register names. |
| |
| GDB Command |
| ........... |
| |
| GDB does not have a command which corresponds to |
| `-data-list-register-names'. In `gdbtk' there is a corresponding |
| command `gdb_regnames'. |
| |
| Example |
| ....... |
| |
| For the PPC MBX board: |
| (gdb) |
| -data-list-register-names |
| ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", |
| "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", |
| "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", |
| "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", |
| "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", |
| "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", |
| "", "pc","ps","cr","lr","ctr","xer"] |
| (gdb) |
| -data-list-register-names 1 2 3 |
| ^done,register-names=["r1","r2","r3"] |
| (gdb) |
| |
| The `-data-list-register-values' Command |
| ---------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-list-register-values FMT [ ( REGNO )*] |
| |
| Display the registers' contents. FMT is the format according to |
| which the registers' contents are to be returned, followed by an |
| optional list of numbers specifying the registers to display. A |
| missing list of numbers indicates that the contents of all the |
| registers must be returned. |
| |
| Allowed formats for FMT are: |
| |
| `x' |
| Hexadecimal |
| |
| `o' |
| Octal |
| |
| `t' |
| Binary |
| |
| `d' |
| Decimal |
| |
| `r' |
| Raw |
| |
| `N' |
| Natural |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB commands are `info reg', `info all-reg', and (in |
| `gdbtk') `gdb_fetch_registers'. |
| |
| Example |
| ....... |
| |
| For a PPC MBX board (note: line breaks are for readability only, they |
| don't appear in the actual output): |
| |
| (gdb) |
| -data-list-register-values r 64 65 |
| ^done,register-values=[{number="64",value="0xfe00a300"}, |
| {number="65",value="0x00029002"}] |
| (gdb) |
| -data-list-register-values x |
| ^done,register-values=[{number="0",value="0xfe0043c8"}, |
| {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, |
| {number="3",value="0x0"},{number="4",value="0xa"}, |
| {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, |
| {number="7",value="0xfe011e98"},{number="8",value="0x2"}, |
| {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, |
| {number="11",value="0x1"},{number="12",value="0x0"}, |
| {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, |
| {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, |
| {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, |
| {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, |
| {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, |
| {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, |
| {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, |
| {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, |
| {number="29",value="0x0"},{number="30",value="0xfe010000"}, |
| {number="31",value="0x0"},{number="32",value="0x0"}, |
| {number="33",value="0x0"},{number="34",value="0x0"}, |
| {number="35",value="0x0"},{number="36",value="0x0"}, |
| {number="37",value="0x0"},{number="38",value="0x0"}, |
| {number="39",value="0x0"},{number="40",value="0x0"}, |
| {number="41",value="0x0"},{number="42",value="0x0"}, |
| {number="43",value="0x0"},{number="44",value="0x0"}, |
| {number="45",value="0x0"},{number="46",value="0x0"}, |
| {number="47",value="0x0"},{number="48",value="0x0"}, |
| {number="49",value="0x0"},{number="50",value="0x0"}, |
| {number="51",value="0x0"},{number="52",value="0x0"}, |
| {number="53",value="0x0"},{number="54",value="0x0"}, |
| {number="55",value="0x0"},{number="56",value="0x0"}, |
| {number="57",value="0x0"},{number="58",value="0x0"}, |
| {number="59",value="0x0"},{number="60",value="0x0"}, |
| {number="61",value="0x0"},{number="62",value="0x0"}, |
| {number="63",value="0x0"},{number="64",value="0xfe00a300"}, |
| {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, |
| {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, |
| {number="69",value="0x20002b03"}] |
| (gdb) |
| |
| The `-data-read-memory' Command |
| ------------------------------- |
| |
| This command is deprecated, use `-data-read-memory-bytes' instead. |
| |
| Synopsis |
| ........ |
| |
| -data-read-memory [ -o BYTE-OFFSET ] |
| ADDRESS WORD-FORMAT WORD-SIZE |
| NR-ROWS NR-COLS [ ASCHAR ] |
| |
| where: |
| |
| `ADDRESS' |
| An expression specifying the address of the first memory word to be |
| read. Complex expressions containing embedded white space should |
| be quoted using the C convention. |
| |
| `WORD-FORMAT' |
| The format to be used to print the memory words. The notation is |
| the same as for GDB's `print' command (*note Output Formats: |
| Output Formats.). |
| |
| `WORD-SIZE' |
| The size of each memory word in bytes. |
| |
| `NR-ROWS' |
| The number of rows in the output table. |
| |
| `NR-COLS' |
| The number of columns in the output table. |
| |
| `ASCHAR' |
| If present, indicates that each row should include an ASCII dump. |
| The value of ASCHAR is used as a padding character when a byte is |
| not a member of the printable ASCII character set (printable ASCII |
| characters are those whose code is between 32 and 126, |
| inclusively). |
| |
| `BYTE-OFFSET' |
| An offset to add to the ADDRESS before fetching memory. |
| |
| This command displays memory contents as a table of NR-ROWS by |
| NR-COLS words, each word being WORD-SIZE bytes. In total, `NR-ROWS * |
| NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes'). |
| Should less than the requested number of bytes be returned by the |
| target, the missing words are identified using `N/A'. The number of |
| bytes read from the target is returned in `nr-bytes' and the starting |
| address used to read memory in `addr'. |
| |
| The address of the next/previous row or page is available in |
| `next-row' and `prev-row', `next-page' and `prev-page'. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory |
| read command. |
| |
| Example |
| ....... |
| |
| Read six bytes of memory starting at `bytes+6' but then offset by `-6' |
| bytes. Format as three rows of two columns. One byte per word. |
| Display each word in hex. |
| |
| (gdb) |
| 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 |
| 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", |
| next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", |
| prev-page="0x0000138a",memory=[ |
| {addr="0x00001390",data=["0x00","0x01"]}, |
| {addr="0x00001392",data=["0x02","0x03"]}, |
| {addr="0x00001394",data=["0x04","0x05"]}] |
| (gdb) |
| |
| Read two bytes of memory starting at address `shorts + 64' and |
| display as a single word formatted in decimal. |
| |
| (gdb) |
| 5-data-read-memory shorts+64 d 2 1 1 |
| 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", |
| next-row="0x00001512",prev-row="0x0000150e", |
| next-page="0x00001512",prev-page="0x0000150e",memory=[ |
| {addr="0x00001510",data=["128"]}] |
| (gdb) |
| |
| Read thirty two bytes of memory starting at `bytes+16' and format as |
| eight rows of four columns. Include a string encoding with `x' used as |
| the non-printable character. |
| |
| (gdb) |
| 4-data-read-memory bytes+16 x 1 8 4 x |
| 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", |
| next-row="0x000013c0",prev-row="0x0000139c", |
| next-page="0x000013c0",prev-page="0x00001380",memory=[ |
| {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, |
| {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, |
| {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, |
| {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, |
| {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, |
| {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, |
| {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, |
| {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] |
| (gdb) |
| |
| The `-data-read-memory-bytes' Command |
| ------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-read-memory-bytes [ -o BYTE-OFFSET ] |
| ADDRESS COUNT |
| |
| where: |
| |
| `ADDRESS' |
| An expression specifying the address of the first memory word to be |
| read. Complex expressions containing embedded white space should |
| be quoted using the C convention. |
| |
| `COUNT' |
| The number of bytes to read. This should be an integer literal. |
| |
| `BYTE-OFFSET' |
| The offsets in bytes relative to ADDRESS at which to start |
| reading. This should be an integer literal. This option is |
| provided so that a frontend is not required to first evaluate |
| address and then perform address arithmetics itself. |
| |
| |
| This command attempts to read all accessible memory regions in the |
| specified range. First, all regions marked as unreadable in the memory |
| map (if one is defined) will be skipped. *Note Memory Region |
| Attributes::. Second, GDB will attempt to read the remaining regions. |
| For each one, if reading full region results in an errors, GDB will try |
| to read a subset of the region. |
| |
| In general, every single byte in the region may be readable or not, |
| and the only way to read every readable byte is to try a read at every |
| address, which is not practical. Therefore, GDB will attempt to read |
| all accessible bytes at either beginning or the end of the region, |
| using a binary division scheme. This heuristic works well for reading |
| accross a memory map boundary. Note that if a region has a readable |
| range that is neither at the beginning or the end, GDB will not read it. |
| |
| The result record (*note GDB/MI Result Records::) that is output of |
| the command includes a field named `memory' whose content is a list of |
| tuples. Each tuple represent a successfully read memory block and has |
| the following fields: |
| |
| `begin' |
| The start address of the memory block, as hexadecimal literal. |
| |
| `end' |
| The end address of the memory block, as hexadecimal literal. |
| |
| `offset' |
| The offset of the memory block, as hexadecimal literal, relative to |
| the start address passed to `-data-read-memory-bytes'. |
| |
| `contents' |
| The contents of the memory block, in hex. |
| |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `x'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -data-read-memory-bytes &a 10 |
| ^done,memory=[{begin="0xbffff154",offset="0x00000000", |
| end="0xbffff15e", |
| contents="01000000020000000300"}] |
| (gdb) |
| |
| The `-data-write-memory-bytes' Command |
| -------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -data-write-memory-bytes ADDRESS CONTENTS |
| |
| where: |
| |
| `ADDRESS' |
| An expression specifying the address of the first memory word to be |
| read. Complex expressions containing embedded white space should |
| be quoted using the C convention. |
| |
| `CONTENTS' |
| The hex-encoded bytes to write. |
| |
| |
| GDB Command |
| ........... |
| |
| There's no corresponding GDB command. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -data-write-memory-bytes &a "aabbccdd" |
| ^done |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI |
| |
| 27.16 GDB/MI Tracepoint Commands |
| ================================ |
| |
| The commands defined in this section implement MI support for |
| tracepoints. For detailed introduction, see *Note Tracepoints::. |
| |
| The `-trace-find' Command |
| ------------------------- |
| |
| Synopsis |
| ........ |
| |
| -trace-find MODE [PARAMETERS...] |
| |
| Find a trace frame using criteria defined by MODE and PARAMETERS. |
| The following table lists permissible modes and their parameters. For |
| details of operation, see *Note tfind::. |
| |
| `none' |
| No parameters are required. Stops examining trace frames. |
| |
| `frame-number' |
| An integer is required as parameter. Selects tracepoint frame with |
| that index. |
| |
| `tracepoint-number' |
| An integer is required as parameter. Finds next trace frame that |
| corresponds to tracepoint with the specified number. |
| |
| `pc' |
| An address is required as parameter. Finds next trace frame that |
| corresponds to any tracepoint at the specified address. |
| |
| `pc-inside-range' |
| Two addresses are required as parameters. Finds next trace frame |
| that corresponds to a tracepoint at an address inside the |
| specified range. Both bounds are considered to be inside the |
| range. |
| |
| `pc-outside-range' |
| Two addresses are required as parameters. Finds next trace frame |
| that corresponds to a tracepoint at an address outside the |
| specified range. Both bounds are considered to be inside the |
| range. |
| |
| `line' |
| Line specification is required as parameter. *Note Specify |
| Location::. Finds next trace frame that corresponds to a |
| tracepoint at the specified location. |
| |
| |
| If `none' was passed as MODE, the response does not have fields. |
| Otherwise, the response may have the following fields: |
| |
| `found' |
| This field has either `0' or `1' as the value, depending on |
| whether a matching tracepoint was found. |
| |
| `traceframe' |
| The index of the found traceframe. This field is present iff the |
| `found' field has value of `1'. |
| |
| `tracepoint' |
| The index of the found tracepoint. This field is present iff the |
| `found' field has value of `1'. |
| |
| `frame' |
| The information about the frame corresponding to the found trace |
| frame. This field is present only if a trace frame was found. |
| *Note GDB/MI Frame Information::, for description of this field. |
| |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `tfind'. |
| |
| -trace-define-variable |
| ---------------------- |
| |
| Synopsis |
| ........ |
| |
| -trace-define-variable NAME [ VALUE ] |
| |
| Create trace variable NAME if it does not exist. If VALUE is |
| specified, sets the initial value of the specified trace variable to |
| that value. Note that the NAME should start with the `$' character. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `tvariable'. |
| |
| -trace-list-variables |
| --------------------- |
| |
| Synopsis |
| ........ |
| |
| -trace-list-variables |
| |
| Return a table of all defined trace variables. Each element of the |
| table has the following fields: |
| |
| `name' |
| The name of the trace variable. This field is always present. |
| |
| `initial' |
| The initial value. This is a 64-bit signed integer. This field |
| is always present. |
| |
| `current' |
| The value the trace variable has at the moment. This is a 64-bit |
| signed integer. This field is absent iff current value is not |
| defined, for example if the trace was never run, or is presently |
| running. |
| |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `tvariables'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -trace-list-variables |
| ^done,trace-variables={nr_rows="1",nr_cols="3", |
| hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"}, |
| {width="11",alignment="-1",col_name="initial",colhdr="Initial"}, |
| {width="11",alignment="-1",col_name="current",colhdr="Current"}], |
| body=[variable={name="$trace_timestamp",initial="0"} |
| variable={name="$foo",initial="10",current="15"}]} |
| (gdb) |
| |
| -trace-save |
| ----------- |
| |
| Synopsis |
| ........ |
| |
| -trace-save [-r ] FILENAME |
| |
| Saves the collected trace data to FILENAME. Without the `-r' |
| option, the data is downloaded from the target and saved in a local |
| file. With the `-r' option the target is asked to perform the save. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `tsave'. |
| |
| -trace-start |
| ------------ |
| |
| Synopsis |
| ........ |
| |
| -trace-start |
| |
| Starts a tracing experiments. The result of this command does not |
| have any fields. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `tstart'. |
| |
| -trace-status |
| ------------- |
| |
| Synopsis |
| ........ |
| |
| -trace-status |
| |
| Obtains the status of a tracing experiment. The result may include |
| the following fields: |
| |
| `supported' |
| May have a value of either `0', when no tracing operations are |
| supported, `1', when all tracing operations are supported, or |
| `file' when examining trace file. In the latter case, examining |
| of trace frame is possible but new tracing experiement cannot be |
| started. This field is always present. |
| |
| `running' |
| May have a value of either `0' or `1' depending on whether tracing |
| experiement is in progress on target. This field is present if |
| `supported' field is not `0'. |
| |
| `stop-reason' |
| Report the reason why the tracing was stopped last time. This |
| field may be absent iff tracing was never stopped on target yet. |
| The value of `request' means the tracing was stopped as result of |
| the `-trace-stop' command. The value of `overflow' means the |
| tracing buffer is full. The value of `disconnection' means |
| tracing was automatically stopped when GDB has disconnected. The |
| value of `passcount' means tracing was stopped when a tracepoint |
| was passed a maximal number of times for that tracepoint. This |
| field is present if `supported' field is not `0'. |
| |
| `stopping-tracepoint' |
| The number of tracepoint whose passcount as exceeded. This field |
| is present iff the `stop-reason' field has the value of |
| `passcount'. |
| |
| `frames' |
| `frames-created' |
| The `frames' field is a count of the total number of trace frames |
| in the trace buffer, while `frames-created' is the total created |
| during the run, including ones that were discarded, such as when a |
| circular trace buffer filled up. Both fields are optional. |
| |
| `buffer-size' |
| `buffer-free' |
| These fields tell the current size of the tracing buffer and the |
| remaining space. These fields are optional. |
| |
| `circular' |
| The value of the circular trace buffer flag. `1' means that the |
| trace buffer is circular and old trace frames will be discarded if |
| necessary to make room, `0' means that the trace buffer is linear |
| and may fill up. |
| |
| `disconnected' |
| The value of the disconnected tracing flag. `1' means that |
| tracing will continue after GDB disconnects, `0' means that the |
| trace run will stop. |
| |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `tstatus'. |
| |
| -trace-stop |
| ----------- |
| |
| Synopsis |
| ........ |
| |
| -trace-stop |
| |
| Stops a tracing experiment. The result of this command has the same |
| fields as `-trace-status', except that the `supported' and `running' |
| fields are not output. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `tstop'. |
| |
| |
| File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI |
| |
| 27.17 GDB/MI Symbol Query Commands |
| ================================== |
| |
| The `-symbol-list-lines' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -symbol-list-lines FILENAME |
| |
| Print the list of lines that contain code and their associated |
| program addresses for the given source filename. The entries are |
| sorted in ascending PC order. |
| |
| GDB Command |
| ........... |
| |
| There is no corresponding GDB command. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -symbol-list-lines basics.c |
| ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI |
| |
| 27.18 GDB/MI File Commands |
| ========================== |
| |
| This section describes the GDB/MI commands to specify executable file |
| names and to read in and obtain symbol table information. |
| |
| The `-file-exec-and-symbols' Command |
| ------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -file-exec-and-symbols FILE |
| |
| Specify the executable file to be debugged. This file is the one |
| from which the symbol table is also read. If no file is specified, the |
| command clears the executable and symbol information. If breakpoints |
| are set when using this command with no arguments, GDB will produce |
| error messages. Otherwise, no output is produced, except a completion |
| notification. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `file'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx |
| ^done |
| (gdb) |
| |
| The `-file-exec-file' Command |
| ----------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-exec-file FILE |
| |
| Specify the executable file to be debugged. Unlike |
| `-file-exec-and-symbols', the symbol table is _not_ read from this |
| file. If used without argument, GDB clears the information about the |
| executable file. No output is produced, except a completion |
| notification. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `exec-file'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx |
| ^done |
| (gdb) |
| |
| The `-file-list-exec-source-file' Command |
| ----------------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-list-exec-source-file |
| |
| List the line number, the current source file, and the absolute path |
| to the current source file for the current executable. The macro |
| information field has a value of `1' or `0' depending on whether or not |
| the file includes preprocessor macro information. |
| |
| GDB Command |
| ........... |
| |
| The GDB equivalent is `info source' |
| |
| Example |
| ....... |
| |
| (gdb) |
| 123-file-list-exec-source-file |
| 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" |
| (gdb) |
| |
| The `-file-list-exec-source-files' Command |
| ------------------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -file-list-exec-source-files |
| |
| List the source files for the current executable. |
| |
| It will always output the filename, but only when GDB can find the |
| absolute file name of a source file, will it output the fullname. |
| |
| GDB Command |
| ........... |
| |
| The GDB equivalent is `info sources'. `gdbtk' has an analogous command |
| `gdb_listfiles'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -file-list-exec-source-files |
| ^done,files=[ |
| {file=foo.c,fullname=/home/foo.c}, |
| {file=/home/bar.c,fullname=/home/bar.c}, |
| {file=gdb_could_not_find_fullpath.c}] |
| (gdb) |
| |
| The `-file-symbol-file' Command |
| ------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -file-symbol-file FILE |
| |
| Read symbol table info from the specified FILE argument. When used |
| without arguments, clears GDB's symbol table info. No output is |
| produced, except for a completion notification. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `symbol-file'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx |
| ^done |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI |
| |
| 27.19 GDB/MI Target Manipulation Commands |
| ========================================= |
| |
| The `-target-attach' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-attach PID | GID | FILE |
| |
| Attach to a process PID or a file FILE outside of GDB, or a thread |
| group GID. If attaching to a thread group, the id previously returned |
| by `-list-thread-groups --available' must be used. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `attach'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-attach 34 |
| =thread-created,id="1" |
| *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]} |
| ^done |
| (gdb) |
| |
| The `-target-detach' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-detach [ PID | GID ] |
| |
| Detach from the remote target which normally resumes its execution. |
| If either PID or GID is specified, detaches from either the specified |
| process, or specified thread group. There's no output. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `detach'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-detach |
| ^done |
| (gdb) |
| |
| The `-target-disconnect' Command |
| -------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-disconnect |
| |
| Disconnect from the remote target. There's no output and the target |
| is generally not resumed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `disconnect'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-disconnect |
| ^done |
| (gdb) |
| |
| The `-target-download' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -target-download |
| |
| Loads the executable onto the remote target. It prints out an |
| update message every half second, which includes the fields: |
| |
| `section' |
| The name of the section. |
| |
| `section-sent' |
| The size of what has been sent so far for that section. |
| |
| `section-size' |
| The size of the section. |
| |
| `total-sent' |
| The total size of what was sent so far (the current and the |
| previous sections). |
| |
| `total-size' |
| The size of the overall executable to download. |
| |
| Each message is sent as status record (*note GDB/MI Output Syntax: |
| GDB/MI Output Syntax.). |
| |
| In addition, it prints the name and size of the sections, as they are |
| downloaded. These messages include the following fields: |
| |
| `section' |
| The name of the section. |
| |
| `section-size' |
| The size of the section. |
| |
| `total-size' |
| The size of the overall executable to download. |
| |
| At the end, a summary is printed. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `load'. |
| |
| Example |
| ....... |
| |
| Note: each status message appears on a single line. Here the messages |
| have been broken down so that they can fit onto a page. |
| |
| (gdb) |
| -target-download |
| +download,{section=".text",section-size="6668",total-size="9880"} |
| +download,{section=".text",section-sent="512",section-size="6668", |
| total-sent="512",total-size="9880"} |
| +download,{section=".text",section-sent="1024",section-size="6668", |
| total-sent="1024",total-size="9880"} |
| +download,{section=".text",section-sent="1536",section-size="6668", |
| total-sent="1536",total-size="9880"} |
| +download,{section=".text",section-sent="2048",section-size="6668", |
| total-sent="2048",total-size="9880"} |
| +download,{section=".text",section-sent="2560",section-size="6668", |
| total-sent="2560",total-size="9880"} |
| +download,{section=".text",section-sent="3072",section-size="6668", |
| total-sent="3072",total-size="9880"} |
| +download,{section=".text",section-sent="3584",section-size="6668", |
| total-sent="3584",total-size="9880"} |
| +download,{section=".text",section-sent="4096",section-size="6668", |
| total-sent="4096",total-size="9880"} |
| +download,{section=".text",section-sent="4608",section-size="6668", |
| total-sent="4608",total-size="9880"} |
| +download,{section=".text",section-sent="5120",section-size="6668", |
| total-sent="5120",total-size="9880"} |
| +download,{section=".text",section-sent="5632",section-size="6668", |
| total-sent="5632",total-size="9880"} |
| +download,{section=".text",section-sent="6144",section-size="6668", |
| total-sent="6144",total-size="9880"} |
| +download,{section=".text",section-sent="6656",section-size="6668", |
| total-sent="6656",total-size="9880"} |
| +download,{section=".init",section-size="28",total-size="9880"} |
| +download,{section=".fini",section-size="28",total-size="9880"} |
| +download,{section=".data",section-size="3156",total-size="9880"} |
| +download,{section=".data",section-sent="512",section-size="3156", |
| total-sent="7236",total-size="9880"} |
| +download,{section=".data",section-sent="1024",section-size="3156", |
| total-sent="7748",total-size="9880"} |
| +download,{section=".data",section-sent="1536",section-size="3156", |
| total-sent="8260",total-size="9880"} |
| +download,{section=".data",section-sent="2048",section-size="3156", |
| total-sent="8772",total-size="9880"} |
| +download,{section=".data",section-sent="2560",section-size="3156", |
| total-sent="9284",total-size="9880"} |
| +download,{section=".data",section-sent="3072",section-size="3156", |
| total-sent="9796",total-size="9880"} |
| ^done,address="0x10004",load-size="9880",transfer-rate="6586", |
| write-rate="429" |
| (gdb) |
| |
| GDB Command |
| ........... |
| |
| No equivalent. |
| |
| Example |
| ....... |
| |
| N.A. |
| |
| The `-target-select' Command |
| ---------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-select TYPE PARAMETERS ... |
| |
| Connect GDB to the remote target. This command takes two args: |
| |
| `TYPE' |
| The type of target, for instance `remote', etc. |
| |
| `PARAMETERS' |
| Device names, host names and the like. *Note Commands for |
| Managing Targets: Target Commands, for more details. |
| |
| The output is a connection notification, followed by the address at |
| which the target program is, in the following form: |
| |
| ^connected,addr="ADDRESS",func="FUNCTION NAME", |
| args=[ARG LIST] |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `target'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-select remote /dev/ttya |
| ^connected,addr="0xfe00a300",func="??",args=[] |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI |
| |
| 27.20 GDB/MI File Transfer Commands |
| =================================== |
| |
| The `-target-file-put' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -target-file-put HOSTFILE TARGETFILE |
| |
| Copy file HOSTFILE from the host system (the machine running GDB) to |
| TARGETFILE on the target system. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `remote put'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-file-put localfile remotefile |
| ^done |
| (gdb) |
| |
| The `-target-file-get' Command |
| ------------------------------ |
| |
| Synopsis |
| ........ |
| |
| -target-file-get TARGETFILE HOSTFILE |
| |
| Copy file TARGETFILE from the target system to HOSTFILE on the host |
| system. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `remote get'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-file-get remotefile localfile |
| ^done |
| (gdb) |
| |
| The `-target-file-delete' Command |
| --------------------------------- |
| |
| Synopsis |
| ........ |
| |
| -target-file-delete TARGETFILE |
| |
| Delete TARGETFILE from the target system. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `remote delete'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -target-file-delete remotefile |
| ^done |
| (gdb) |
| |
| |
| File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI |
| |
| 27.21 Miscellaneous GDB/MI Commands |
| =================================== |
| |
| The `-gdb-exit' Command |
| ----------------------- |
| |
| Synopsis |
| ........ |
| |
| -gdb-exit |
| |
| Exit GDB immediately. |
| |
| GDB Command |
| ........... |
| |
| Approximately corresponds to `quit'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -gdb-exit |
| ^exit |
| |
| The `-gdb-set' Command |
| ---------------------- |
| |
| Synopsis |
| ........ |
| |
| -gdb-set |
| |
| Set an internal GDB variable. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `set'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -gdb-set $foo=3 |
| ^done |
| (gdb) |
| |
| The `-gdb-show' Command |
| ----------------------- |
| |
| Synopsis |
| ........ |
| |
| -gdb-show |
| |
| Show the current value of a GDB variable. |
| |
| GDB Command |
| ........... |
| |
| The corresponding GDB command is `show'. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -gdb-show annotate |
| ^done,value="0" |
| (gdb) |
| |
| The `-gdb-version' Command |
| -------------------------- |
| |
| Synopsis |
| ........ |
| |
| -gdb-version |
| |
| Show version information for GDB. Used mostly in testing. |
| |
| GDB Command |
| ........... |
| |
| The GDB equivalent is `show version'. GDB by default shows this |
| information when you start an interactive session. |
| |
| Example |
| ....... |
| |
| (gdb) |
| -gdb-version |
| ~GNU gdb 5.2.1 |
| ~Copyright 2000 Free Software Foundation, Inc. |
| ~GDB is free software, covered by the GNU General Public License, and |
| ~you are welcome to change it and/or distribute copies of it under |
| ~ certain conditions. |
| ~Type "show copying" to see the conditions. |
| ~There is absolutely no warranty for GDB. Type "show warranty" for |
| ~ details. |
| ~This GDB was configured as |
| "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". |
| ^done |
| (gdb) |
| |
| The `-list-features' Command |
| ---------------------------- |
| |
| Returns a list of particular features of the MI protocol that this |
| version of gdb implements. A feature can be a command, or a new field |
| in an output of some command, or even an important bugfix. While a |
| frontend can sometimes detect presence of a feature at runtime, it is |
| easier to perform detection at debugger startup. |
| |
| The command returns a list of strings, with each string naming an |
| available feature. Each returned string is just a name, it does not |
| have any internal structure. The list of possible feature names is |
| given below. |
| |
| Example output: |
| |
| (gdb) -list-features |
| ^done,result=["feature1","feature2"] |
| |
| The current list of features is: |
| |
| `frozen-varobjs' |
| Indicates support for the `-var-set-frozen' command, as well as |
| possible presense of the `frozen' field in the output of |
| `-varobj-create'. |
| |
| `pending-breakpoints' |
| Indicates support for the `-f' option to the `-break-insert' |
| command. |
| |
| `python' |
| Indicates Python scripting support, Python-based pretty-printing |
| commands, and possible presence of the `display_hint' field in the |
| output of `-var-list-children' |
| |
| `thread-info' |
| Indicates support for the `-thread-info' command. |
| |
| `data-read-memory-bytes' |
| Indicates support for the `-data-read-memory-bytes' and the |
| `-data-write-memory-bytes' commands. |
| |
| `breakpoint-notifications' |
| Indicates that changes to breakpoints and breakpoints created via |
| the CLI will be announced via async records. |
| |
| `ada-task-info' |
| Indicates support for the `-ada-task-info' command. |
| |
| The `-list-target-features' Command |
| ----------------------------------- |
| |
| Returns a list of particular features that are supported by the target. |
| Those features affect the permitted MI commands, but unlike the |
| features reported by the `-list-features' command, the features depend |
| on which target GDB is using at the moment. Whenever a target can |
| change, due to commands such as `-target-select', `-target-attach' or |
| `-exec-run', the list of target features may change, and the frontend |
| should obtain it again. Example output: |
| |
| (gdb) -list-features |
| ^done,result=["async"] |
| |
| The current list of features is: |
| |
| `async' |
| Indicates that the target is capable of asynchronous command |
| execution, which means that GDB will accept further commands while |
| the target is running. |
| |
| `reverse' |
| Indicates that the target is capable of reverse execution. *Note |
| Reverse Execution::, for more information. |
| |
| |
| The `-list-thread-groups' Command |
| --------------------------------- |
| |
| Synopsis |
| -------- |
| |
| -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ] |
| |
| Lists thread groups (*note Thread groups::). When a single thread |
| group is passed as the argument, lists the children of that group. |
| When several thread group are passed, lists information about those |
| thread groups. Without any parameters, lists information about all |
| top-level thread groups. |
| |
| Normally, thread groups that are being debugged are reported. With |
| the `--available' option, GDB reports thread groups available on the |
| target. |
| |
| The output of this command may have either a `threads' result or a |
| `groups' result. The `thread' result has a list of tuples as value, |
| with each tuple describing a thread (*note GDB/MI Thread |
| Information::). The `groups' result has a list of tuples as value, |
| each tuple describing a thread group. If top-level groups are |
| requested (that is, no parameter is passed), or when several groups are |
| passed, the output always has a `groups' result. The format of the |
| `group' result is described below. |
| |
| To reduce the number of roundtrips it's possible to list thread |
| groups together with their children, by passing the `--recurse' option |
| and the recursion depth. Presently, only recursion depth of 1 is |
| permitted. If this option is present, then every reported thread group |
| will also include its children, either as `group' or `threads' field. |
| |
| In general, any combination of option and parameters is permitted, |
| with the following caveats: |
| |
| * When a single thread group is passed, the output will typically be |
| the `threads' result. Because threads may not contain anything, |
| the `recurse' option will be ignored. |
| |
| * When the `--available' option is passed, limited information may |
| be available. In particular, the list of threads of a process |
| might be inaccessible. Further, specifying specific thread groups |
| might not give any performance advantage over listing all thread |
| groups. The frontend should assume that `-list-thread-groups |
| --available' is always an expensive operation and cache the |
| results. |
| |
| |
| The `groups' result is a list of tuples, where each tuple may have |
| the following fields: |
| |
| `id' |
| Identifier of the thread group. This field is always present. |
| The identifier is an opaque string; frontends should not try to |
| convert it to an integer, even though it might look like one. |
| |
| `type' |
| The type of the thread group. At present, only `process' is a |
| valid type. |
| |
| `pid' |
| The target-specific process identifier. This field is only present |
| for thread groups of type `process' and only if the process exists. |
| |
| `num_children' |
| The number of children this thread group has. This field may be |
| absent for an available thread group. |
| |
| `threads' |
| This field has a list of tuples as value, each tuple describing a |
| thread. It may be present if the `--recurse' option is specified, |
| and it's actually possible to obtain the threads. |
| |
| `cores' |
| This field is a list of integers, each identifying a core that one |
| thread of the group is running on. This field may be absent if |
| such information is not available. |
| |
| `executable' |
| The name of the executable file that corresponds to this thread |
| group. The field is only present for thread groups of type |
| `process', and only if there is a corresponding executable file. |
| |
| |
| Example |
| ------- |
| |
| gdb |
| -list-thread-groups |
| ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}] |
| -list-thread-groups 17 |
| ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", |
| frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, |
| {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", |
| frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], |
| file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]] |
| -list-thread-groups --available |
| ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}] |
| -list-thread-groups --available --recurse 1 |
| ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], |
| threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, |
| {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..] |
| -list-thread-groups --available --recurse 1 17 18 |
| ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], |
| 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 |
| --------------------------- |
| |
| Synopsis |
| -------- |
| |
| -add-inferior |
| |
| Creates a new inferior (*note Inferiors and Programs::). The created |
| inferior is not associated with any executable. Such association may |
| be established with the `-file-exec-and-symbols' command (*note GDB/MI |
| File Commands::). The command response has a single field, |
| `thread-group', whose value is the identifier of the thread group |
| corresponding to the new inferior. |
| |
| Example |
| ------- |
| |
| gdb |
| -add-inferior |
| ^done,thread-group="i3" |
| |
| The `-interpreter-exec' Command |
| ------------------------------- |
| |
| Synopsis |
| -------- |
| |
| -interpreter-exec INTERPRETER COMMAND |
| |
| Execute the specified COMMAND in the given INTERPRETER. |
| |
| GDB Command |
| ----------- |
| |
| The corresponding GDB command is `interpreter-exec'. |
| |
| Example |
| ------- |
| |
| (gdb) |
| -interpreter-exec console "break main" |
| &"During symbol reading, couldn't parse type; debugger out of date?.\n" |
| &"During symbol reading, bad structure-type format.\n" |
| ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" |
| ^done |
| (gdb) |
| |
| The `-inferior-tty-set' Command |
| ------------------------------- |
| |
| Synopsis |
| -------- |
| |
| -inferior-tty-set /dev/pts/1 |
| |
| Set terminal for future runs of the program being debugged. |
| |
| GDB Command |
| ----------- |
| |
| The corresponding GDB command is `set inferior-tty' /dev/pts/1. |
| |
| Example |
| ------- |
| |
| (gdb) |
| -inferior-tty-set /dev/pts/1 |
| ^done |
| (gdb) |
| |
| The `-inferior-tty-show' Command |
| -------------------------------- |
| |
| Synopsis |
| -------- |
| |
| -inferior-tty-show |
| |
| Show terminal for future runs of program being debugged. |
| |
| GDB Command |
| ----------- |
| |
| The corresponding GDB command is `show inferior-tty'. |
| |
| Example |
| ------- |
| |
| (gdb) |
| -inferior-tty-set /dev/pts/1 |
| ^done |
| (gdb) |
| -inferior-tty-show |
| ^done,inferior_tty_terminal="/dev/pts/1" |
| (gdb) |
| |
| The `-enable-timings' Command |
| ----------------------------- |
| |
| Synopsis |
| -------- |
| |
| -enable-timings [yes | no] |
| |
| Toggle the printing of the wallclock, user and system times for an MI |
| command as a field in its output. This command is to help frontend |
| developers optimize the performance of their code. No argument is |
| equivalent to `yes'. |
| |
| GDB Command |
| ----------- |
| |
| No equivalent. |
| |
| Example |
| ------- |
| |
| (gdb) |
| -enable-timings |
| ^done |
| (gdb) |
| -break-insert main |
| ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
| addr="0x080484ed",func="main",file="myprog.c", |
| fullname="/home/nickrob/myprog.c",line="73",times="0"}, |
| time={wallclock="0.05185",user="0.00800",system="0.00000"} |
| (gdb) |
| -enable-timings no |
| ^done |
| (gdb) |
| -exec-run |
| ^running |
| (gdb) |
| *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", |
| frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"}, |
| {name="argv",value="0xbfb60364"}],file="myprog.c", |
| fullname="/home/nickrob/myprog.c",line="73"} |
| (gdb) |
| |
| |
| File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top |
| |
| 28 GDB Annotations |
| ****************** |
| |
| This chapter describes annotations in GDB. Annotations were designed |
| to interface GDB to graphical user interfaces or other similar programs |
| which want to interact with GDB at a relatively high level. |
| |
| The annotation mechanism has largely been superseded by GDB/MI |
| (*note GDB/MI::). |
| |
| * Menu: |
| |
| * Annotations Overview:: What annotations are; the general syntax. |
| * Server Prefix:: Issuing a command without affecting user state. |
| * Prompting:: Annotations marking GDB's need for input. |
| * Errors:: Annotations for error messages. |
| * Invalidation:: Some annotations describe things now invalid. |
| * Annotations for Running:: |
| Whether the program is running, how it stopped, etc. |
| * Source Annotations:: Annotations describing source code. |
| |
| |
| File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations |
| |
| 28.1 What is an Annotation? |
| =========================== |
| |
| Annotations start with a newline character, two `control-z' characters, |
| and the name of the annotation. If there is no additional information |
| associated with this annotation, the name of the annotation is followed |
| immediately by a newline. If there is additional information, the name |
| of the annotation is followed by a space, the additional information, |
| and a newline. The additional information cannot contain newline |
| characters. |
| |
| Any output not beginning with a newline and two `control-z' |
| characters denotes literal output from GDB. Currently there is no need |
| for GDB to output a newline followed by two `control-z' characters, but |
| if there was such a need, the annotations could be extended with an |
| `escape' annotation which means those three characters as output. |
| |
| The annotation LEVEL, which is specified using the `--annotate' |
| command line option (*note Mode Options::), controls how much |
| information GDB prints together with its prompt, values of expressions, |
| source lines, and other types of output. Level 0 is for no |
| annotations, level 1 is for use when GDB is run as a subprocess of GNU |
| Emacs, level 3 is the maximum annotation suitable for programs that |
| control GDB, and level 2 annotations have been made obsolete (*note |
| Limitations of the Annotation Interface: (annotate)Limitations.). |
| |
| `set annotate LEVEL' |
| The GDB command `set annotate' sets the level of annotations to |
| the specified LEVEL. |
| |
| `show annotate' |
| Show the current annotation level. |
| |
| This chapter describes level 3 annotations. |
| |
| A simple example of starting up GDB with annotations is: |
| |
| $ gdb --annotate=3 |
| GNU gdb 6.0 |
| Copyright 2003 Free Software Foundation, Inc. |
| GDB is free software, covered by the GNU General Public License, |
| and you are welcome to change it and/or distribute copies of it |
| under certain conditions. |
| Type "show copying" to see the conditions. |
| There is absolutely no warranty for GDB. Type "show warranty" |
| for details. |
| This GDB was configured as "i386-pc-linux-gnu" |
| |
| ^Z^Zpre-prompt |
| (gdb) |
| ^Z^Zprompt |
| quit |
| |
| ^Z^Zpost-prompt |
| $ |
| |
| Here `quit' is input to GDB; the rest is output from GDB. The three |
| lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are |
| annotations; the rest is output from GDB. |
| |
| |
| File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations |
| |
| 28.2 The Server Prefix |
| ====================== |
| |
| If you prefix a command with `server ' then it will not affect the |
| command history, nor will it affect GDB's notion of which command to |
| repeat if <RET> is pressed on a line by itself. This means that |
| commands can be run behind a user's back by a front-end in a |
| transparent manner. |
| |
| The `server ' prefix does not affect the recording of values into |
| the value history; to print a value without recording it into the value |
| history, use the `output' command instead of the `print' command. |
| |
| Using this prefix also disables confirmation requests (*note |
| confirmation requests::). |
| |
| |
| File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations |
| |
| 28.3 Annotation for GDB Input |
| ============================= |
| |
| When GDB prompts for input, it annotates this fact so it is possible to |
| know when to send output, when the output from a given command is over, |
| etc. |
| |
| Different kinds of input each have a different "input type". Each |
| input type has three annotations: a `pre-' annotation, which denotes |
| the beginning of any prompt which is being output, a plain annotation, |
| which denotes the end of the prompt, and then a `post-' annotation |
| which denotes the end of any echo which may (or may not) be associated |
| with the input. For example, the `prompt' input type features the |
| following annotations: |
| |
| ^Z^Zpre-prompt |
| ^Z^Zprompt |
| ^Z^Zpost-prompt |
| |
| The input types are |
| |
| `prompt' |
| When GDB is prompting for a command (the main GDB prompt). |
| |
| `commands' |
| When GDB prompts for a set of commands, like in the `commands' |
| command. The annotations are repeated for each command which is |
| input. |
| |
| `overload-choice' |
| When GDB wants the user to select between various overloaded |
| functions. |
| |
| `query' |
| When GDB wants the user to confirm a potentially dangerous |
| operation. |
| |
| `prompt-for-continue' |
| When GDB is asking the user to press return to continue. Note: |
| Don't expect this to work well; instead use `set height 0' to |
| disable prompting. This is because the counting of lines is buggy |
| in the presence of annotations. |
| |
| |
| File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations |
| |
| 28.4 Errors |
| =========== |
| |
| ^Z^Zquit |
| |
| This annotation occurs right before GDB responds to an interrupt. |
| |
| ^Z^Zerror |
| |
| This annotation occurs right before GDB responds to an error. |
| |
| Quit and error annotations indicate that any annotations which GDB |
| was in the middle of may end abruptly. For example, if a |
| `value-history-begin' annotation is followed by a `error', one cannot |
| expect to receive the matching `value-history-end'. One cannot expect |
| not to receive it either, however; an error annotation does not |
| necessarily mean that GDB is immediately returning all the way to the |
| top level. |
| |
| A quit or error annotation may be preceded by |
| |
| ^Z^Zerror-begin |
| |
| Any output between that and the quit or error annotation is the error |
| message. |
| |
| Warning messages are not yet annotated. |
| |
| |
| File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations |
| |
| 28.5 Invalidation Notices |
| ========================= |
| |
| The following annotations say that certain pieces of state may have |
| changed. |
| |
| `^Z^Zframes-invalid' |
| The frames (for example, output from the `backtrace' command) may |
| have changed. |
| |
| `^Z^Zbreakpoints-invalid' |
| The breakpoints may have changed. For example, the user just |
| added or deleted a breakpoint. |
| |
| |
| File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations |
| |
| 28.6 Running the Program |
| ======================== |
| |
| When the program starts executing due to a GDB command such as `step' |
| or `continue', |
| |
| ^Z^Zstarting |
| |
| is output. When the program stops, |
| |
| ^Z^Zstopped |
| |
| is output. Before the `stopped' annotation, a variety of |
| annotations describe how the program stopped. |
| |
| `^Z^Zexited EXIT-STATUS' |
| The program exited, and EXIT-STATUS is the exit status (zero for |
| successful exit, otherwise nonzero). |
| |
| `^Z^Zsignalled' |
| The program exited with a signal. After the `^Z^Zsignalled', the |
| annotation continues: |
| |
| INTRO-TEXT |
| ^Z^Zsignal-name |
| NAME |
| ^Z^Zsignal-name-end |
| MIDDLE-TEXT |
| ^Z^Zsignal-string |
| STRING |
| ^Z^Zsignal-string-end |
| END-TEXT |
| |
| where NAME is the name of the signal, such as `SIGILL' or |
| `SIGSEGV', and STRING is the explanation of the signal, such as |
| `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT, |
| MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no |
| particular format. |
| |
| `^Z^Zsignal' |
| The syntax of this annotation is just like `signalled', but GDB is |
| just saying that the program received the signal, not that it was |
| terminated with it. |
| |
| `^Z^Zbreakpoint NUMBER' |
| The program hit breakpoint number NUMBER. |
| |
| `^Z^Zwatchpoint NUMBER' |
| The program hit watchpoint number NUMBER. |
| |
| |
| File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations |
| |
| 28.7 Displaying Source |
| ====================== |
| |
| The following annotation is used instead of displaying source code: |
| |
| ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR |
| |
| where FILENAME is an absolute file name indicating which source |
| file, LINE is the line number within that file (where 1 is the first |
| line in the file), CHARACTER is the character position within the file |
| (where 0 is the first character in the file) (for most debug formats |
| this will necessarily point to the beginning of a line), MIDDLE is |
| `middle' if ADDR is in the middle of the line, or `beg' if ADDR is at |
| the beginning of the line, and ADDR is the address in the target |
| program associated with the source which is being displayed. ADDR is |
| 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: In-Process Agent, Prev: Annotations, Up: Top |
| |
| 29 JIT Compilation Interface |
| **************************** |
| |
| This chapter documents GDB's "just-in-time" (JIT) compilation |
| interface. A JIT compiler is a program or library that generates native |
| executable code at runtime and executes it, usually in order to achieve |
| good performance while maintaining platform independence. |
| |
| Programs that use JIT compilation are normally difficult to debug |
| because portions of their code are generated at runtime, instead of |
| being loaded from object files, which is where GDB normally finds the |
| program's symbols and debug information. In order to debug programs |
| that use JIT compilation, GDB has an interface that allows the program |
| to register in-memory symbol files with GDB at runtime. |
| |
| If you are using GDB to debug a program that uses this interface, |
| then it should work transparently so long as you have not stripped the |
| binary. If you are developing a JIT compiler, then the interface is |
| documented in the rest of this chapter. At this time, the only known |
| client of this interface is the LLVM JIT. |
| |
| Broadly speaking, the JIT interface mirrors the dynamic loader |
| interface. The JIT compiler communicates with GDB by writing data into |
| a global variable and calling a fuction at a well-known symbol. When |
| GDB attaches, it reads a linked list of symbol files from the global |
| variable to find existing code, and puts a breakpoint in the function |
| so that it can find out about additional code. |
| |
| * Menu: |
| |
| * Declarations:: Relevant C struct declarations |
| * Registering Code:: Steps to register code |
| * Unregistering Code:: Steps to unregister code |
| * Custom Debug Info:: Emit debug information in a custom format |
| |
| |
| File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface |
| |
| 29.1 JIT Declarations |
| ===================== |
| |
| These are the relevant struct declarations that a C program should |
| include to implement the interface: |
| |
| typedef enum |
| { |
| JIT_NOACTION = 0, |
| JIT_REGISTER_FN, |
| JIT_UNREGISTER_FN |
| } jit_actions_t; |
| |
| struct jit_code_entry |
| { |
| struct jit_code_entry *next_entry; |
| struct jit_code_entry *prev_entry; |
| const char *symfile_addr; |
| uint64_t symfile_size; |
| }; |
| |
| struct jit_descriptor |
| { |
| uint32_t version; |
| /* This type should be jit_actions_t, but we use uint32_t |
| to be explicit about the bitwidth. */ |
| uint32_t action_flag; |
| struct jit_code_entry *relevant_entry; |
| struct jit_code_entry *first_entry; |
| }; |
| |
| /* GDB puts a breakpoint in this function. */ |
| void __attribute__((noinline)) __jit_debug_register_code() { }; |
| |
| /* Make sure to specify the version statically, because the |
| debugger may check the version before we can set it. */ |
| struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 }; |
| |
| If the JIT is multi-threaded, then it is important that the JIT |
| synchronize any modifications to this global data properly, which can |
| easily be done by putting a global mutex around modifications to these |
| structures. |
| |
| |
| File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface |
| |
| 29.2 Registering Code |
| ===================== |
| |
| To register code with GDB, the JIT should follow this protocol: |
| |
| * Generate an object file in memory with symbols and other desired |
| debug information. The file must include the virtual addresses of |
| the sections. |
| |
| * Create a code entry for the file, which gives the start and size |
| of the symbol file. |
| |
| * Add it to the linked list in the JIT descriptor. |
| |
| * Point the relevant_entry field of the descriptor at the entry. |
| |
| * Set `action_flag' to `JIT_REGISTER' and call |
| `__jit_debug_register_code'. |
| |
| When GDB is attached and the breakpoint fires, GDB uses the |
| `relevant_entry' pointer so it doesn't have to walk the list looking for |
| new code. However, the linked list must still be maintained in order |
| to allow GDB to attach to a running process and still find the symbol |
| files. |
| |
| |
| File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface |
| |
| 29.3 Unregistering Code |
| ======================= |
| |
| If code is freed, then the JIT should use the following protocol: |
| |
| * Remove the code entry corresponding to the code from the linked |
| list. |
| |
| * Point the `relevant_entry' field of the descriptor at the code |
| entry. |
| |
| * Set `action_flag' to `JIT_UNREGISTER' and call |
| `__jit_debug_register_code'. |
| |
| If the JIT frees or recompiles code without unregistering it, then |
| GDB and the JIT will leak the memory used for the associated symbol |
| files. |
| |
| |
| File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface |
| |
| 29.4 Custom Debug Info |
| ====================== |
| |
| Generating debug information in platform-native file formats (like ELF |
| or COFF) may be an overkill for JIT compilers; especially if all the |
| debug info is used for is displaying a meaningful backtrace. The issue |
| can be resolved by having the JIT writers decide on a debug info format |
| and also provide a reader that parses the debug info generated by the |
| JIT compiler. This section gives a brief overview on writing such a |
| parser. More specific details can be found in the source file |
| `gdb/jit-reader.in', which is also installed as a header at |
| `INCLUDEDIR/gdb/jit-reader.h' for easy inclusion. |
| |
| The reader is implemented as a shared object (so this functionality |
| is not available on platforms which don't allow loading shared objects |
| at runtime). Two GDB commands, `jit-reader-load' and |
| `jit-reader-unload' are provided, to be used to load and unload the |
| readers from a preconfigured directory. Once loaded, the shared object |
| is used the parse the debug information emitted by the JIT compiler. |
| |
| * Menu: |
| |
| * Using JIT Debug Info Readers:: How to use supplied readers correctly |
| * Writing JIT Debug Info Readers:: Creating a debug-info reader |
| |
| |
| File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info |
| |
| 29.4.1 Using JIT Debug Info Readers |
| ----------------------------------- |
| |
| Readers can be loaded and unloaded using the `jit-reader-load' and |
| `jit-reader-unload' commands. |
| |
| `jit-reader-load READER-NAME' |
| Load the JIT reader named READER-NAME. On a UNIX system, this |
| will usually load `LIBDIR/gdb/READER-NAME', where LIBDIR is the |
| system library directory, usually `/usr/local/lib'. Only one |
| reader can be active at a time; trying to load a second reader |
| when one is already loaded will result in GDB reporting an error. |
| A new JIT reader can be loaded by first unloading the current one |
| using `jit-reader-load' and then invoking `jit-reader-load'. |
| |
| `jit-reader-unload' |
| Unload the currently loaded JIT reader. |
| |
| |
| |
| File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info |
| |
| 29.4.2 Writing JIT Debug Info Readers |
| ------------------------------------- |
| |
| As mentioned, a reader is essentially a shared object conforming to a |
| certain ABI. This ABI is described in `jit-reader.h'. |
| |
| `jit-reader.h' defines the structures, macros and functions required |
| to write a reader. It is installed (along with GDB), in |
| `INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory. |
| |
| Readers need to be released under a GPL compatible license. A reader |
| can be declared as released under such a license by placing the macro |
| `GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file. |
| |
| The entry point for readers is the symbol `gdb_init_reader', which |
| is expected to be a function with the prototype |
| |
| extern struct gdb_reader_funcs *gdb_init_reader (void); |
| |
| `struct gdb_reader_funcs' contains a set of pointers to callback |
| functions. These functions are executed to read the debug info |
| generated by the JIT compiler (`read'), to unwind stack frames |
| (`unwind') and to create canonical frame IDs (`get_Frame_id'). It also |
| has a callback that is called when the reader is being unloaded |
| (`destroy'). The struct looks like this |
| |
| struct gdb_reader_funcs |
| { |
| /* Must be set to GDB_READER_INTERFACE_VERSION. */ |
| int reader_version; |
| |
| /* For use by the reader. */ |
| void *priv_data; |
| |
| gdb_read_debug_info *read; |
| gdb_unwind_frame *unwind; |
| gdb_get_frame_id *get_frame_id; |
| gdb_destroy_reader *destroy; |
| }; |
| |
| The callbacks are provided with another set of callbacks by GDB to |
| do their job. For `read', these callbacks are passed in a `struct |
| gdb_symbol_callbacks' and for `unwind' and `get_frame_id', in a `struct |
| gdb_unwind_callbacks'. `struct gdb_symbol_callbacks' has callbacks to |
| create new object files and new symbol tables inside those object |
| files. `struct gdb_unwind_callbacks' has callbacks to read registers |
| off the current frame and to write out the values of the registers in |
| the previous frame. Both have a callback (`target_read') to read bytes |
| off the target's address space. |
| |
| |
| 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 |
| |
| 31 Reporting Bugs in GDB |
| ************************ |
| |
| Your bug reports play an essential role in making GDB reliable. |
| |
| Reporting a bug may help you by bringing a solution to your problem, |
| or it may not. But in any case the principal function of a bug report |
| is to help the entire community by making the next version of GDB work |
| better. Bug reports are your contribution to the maintenance of GDB. |
| |
| In order for a bug report to serve its purpose, you must include the |
| information that enables us to fix the bug. |
| |
| * Menu: |
| |
| * Bug Criteria:: Have you found a bug? |
| * Bug Reporting:: How to report bugs |
| |
| |
| File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs |
| |
| 31.1 Have You Found a Bug? |
| ========================== |
| |
| If you are not sure whether you have found a bug, here are some |
| guidelines: |
| |
| * If the debugger gets a fatal signal, for any input whatever, that |
| is a GDB bug. Reliable debuggers never crash. |
| |
| * If GDB produces an error message for valid input, that is a bug. |
| (Note that if you're cross debugging, the problem may also be |
| somewhere in the connection to the target.) |
| |
| * If GDB does not produce an error message for invalid input, that |
| is a bug. However, you should note that your idea of "invalid |
| input" might be our idea of "an extension" or "support for |
| traditional practice". |
| |
| * If you are an experienced user of debugging tools, your suggestions |
| for improvement of GDB are welcome in any case. |
| |
| |
| File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs |
| |
| 31.2 How to Report Bugs |
| ======================= |
| |
| A number of companies and individuals offer support for GNU products. |
| If you obtained GDB from a support organization, we recommend you |
| contact that organization first. |
| |
| You can find contact information for many support companies and |
| individuals in the file `etc/SERVICE' in the GNU Emacs distribution. |
| |
| In any event, we also recommend that you submit bug reports for GDB. |
| The preferred method is to submit them directly using GDB's Bugs web |
| page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the |
| e-mail gateway <bug-gdb@gnu.org> can be used. |
| |
| *Do not send bug reports to `info-gdb', or to `help-gdb', or to any |
| newsgroups.* Most users of GDB do not want to receive bug reports. |
| Those that do have arranged to receive `bug-gdb'. |
| |
| The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which |
| serves as a repeater. The mailing list and the newsgroup carry exactly |
| the same messages. Often people think of posting bug reports to the |
| newsgroup instead of mailing them. This appears to work, but it has one |
| problem which can be crucial: a newsgroup posting often lacks a mail |
| path back to the sender. Thus, if we need to ask for more information, |
| we may be unable to reach you. For this reason, it is better to send |
| bug reports to the mailing list. |
| |
| The fundamental principle of reporting bugs usefully is this: |
| *report all the facts*. If you are not sure whether to state a fact or |
| leave it out, state it! |
| |
| Often people omit facts because they think they know what causes the |
| problem and assume that some details do not matter. Thus, you might |
| assume that the name of the variable you use in an example does not |
| matter. Well, probably it does not, but one cannot be sure. Perhaps |
| the bug is a stray memory reference which happens to fetch from the |
| location where that name is stored in memory; perhaps, if the name were |
| different, the contents of that location would fool the debugger into |
| doing the right thing despite the bug. Play it safe and give a |
| specific, complete example. That is the easiest thing for you to do, |
| and the most helpful. |
| |
| Keep in mind that the purpose of a bug report is to enable us to fix |
| the bug. It may be that the bug has been reported previously, but |
| neither you nor we can know that unless your bug report is complete and |
| self-contained. |
| |
| Sometimes people give a few sketchy facts and ask, "Does this ring a |
| bell?" Those bug reports are useless, and we urge everyone to _refuse |
| to respond to them_ except to chide the sender to report bugs properly. |
| |
| To enable us to fix the bug, you should include all these things: |
| |
| * The version of GDB. GDB announces it if you start with no |
| arguments; you can also print it at any time using `show version'. |
| |
| Without this, we will not know whether there is any point in |
| looking for the bug in the current version of GDB. |
| |
| * The type of machine you are using, and the operating system name |
| and version number. |
| |
| * What compiler (and its version) was used to compile GDB--e.g. |
| "gcc-2.8.1". |
| |
| * What compiler (and its version) was used to compile the program |
| you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP |
| C Compiler". For GCC, you can say `gcc --version' to get this |
| information; for other compilers, see the documentation for those |
| compilers. |
| |
| * The command arguments you gave the compiler to compile your |
| example and observe the bug. For example, did you use `-O'? To |
| guarantee you will not omit something important, list them all. A |
| copy of the Makefile (or the output from make) is sufficient. |
| |
| If we were to try to guess the arguments, we would probably guess |
| wrong and then we might not encounter the bug. |
| |
| * A complete input script, and all necessary source files, that will |
| reproduce the bug. |
| |
| * A description of what behavior you observe that you believe is |
| incorrect. For example, "It gets a fatal signal." |
| |
| Of course, if the bug is that GDB gets a fatal signal, then we |
| will certainly notice it. But if the bug is incorrect output, we |
| might not notice unless it is glaringly wrong. You might as well |
| not give us a chance to make a mistake. |
| |
| Even if the problem you experience is a fatal signal, you should |
| still say so explicitly. Suppose something strange is going on, |
| such as, your copy of GDB is out of synch, or you have encountered |
| a bug in the C library on your system. (This has happened!) Your |
| copy might crash and ours would not. If you told us to expect a |
| crash, then when ours fails to crash, we would know that the bug |
| was not happening for us. If you had not told us to expect a |
| crash, then we would not be able to draw any conclusion from our |
| observations. |
| |
| To collect all this information, you can use a session recording |
| program such as `script', which is available on many Unix systems. |
| Just run your GDB session inside `script' and then include the |
| `typescript' file with your bug report. |
| |
| Another way to record a GDB session is to run GDB inside Emacs and |
| then save the entire buffer to a file. |
| |
| * If you wish to suggest changes to the GDB source, send us context |
| diffs. If you even discuss something in the GDB source, refer to |
| it by context, not by line number. |
| |
| The line numbers in our development sources will not match those |
| in your sources. Your line numbers would convey no useful |
| information to us. |
| |
| |
| Here are some things that are not necessary: |
| |
| * A description of the envelope of the bug. |
| |
| Often people who encounter a bug spend a lot of time investigating |
| which changes to the input file will make the bug go away and which |
| changes will not affect it. |
| |
| This is often time consuming and not very useful, because the way |
| we will find the bug is by running a single example under the |
| debugger with breakpoints, not by pure deduction from a series of |
| examples. We recommend that you save your time for something else. |
| |
| Of course, if you can find a simpler example to report _instead_ |
| of the original one, that is a convenience for us. Errors in the |
| output will be easier to spot, running under the debugger will take |
| less time, and so on. |
| |
| However, simplification is not vital; if you do not want to do |
| this, report the bug anyway and send us the entire test case you |
| used. |
| |
| * A patch for the bug. |
| |
| A patch for the bug does help us if it is a good one. But do not |
| omit the necessary information, such as the test case, on the |
| assumption that a patch is all we need. We might see problems |
| with your patch and decide to fix the problem another way, or we |
| might not understand it at all. |
| |
| Sometimes with a program as complicated as GDB it is very hard to |
| construct an example that will make the program follow a certain |
| path through the code. If you do not send us the example, we will |
| not be able to construct one, so we will not be able to verify |
| that the bug is fixed. |
| |
| And if we cannot understand what bug you are trying to fix, or why |
| your patch should be an improvement, we will not install it. A |
| test case will help us to understand. |
| |
| * A guess about what the bug is or what it depends on. |
| |
| Such guesses are usually wrong. Even we cannot guess right about |
| such things without first using the debugger to find the facts. |
| |
| |
| File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top |
| |
| 32 Command Line Editing |
| *********************** |
| |
| This chapter describes the basic features of the GNU command line |
| editing interface. |
| |
| * Menu: |
| |
| * Introduction and Notation:: Notation used in this text. |
| * Readline Interaction:: The minimum set of commands for editing a line. |
| * Readline Init File:: Customizing Readline from a user's view. |
| * Bindable Readline Commands:: A description of most of the Readline commands |
| available for binding |
| * Readline vi Mode:: A short description of how to make Readline |
| behave like the vi editor. |
| |
| |
| File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing |
| |
| 32.1 Introduction to Line Editing |
| ================================= |
| |
| The following paragraphs describe the notation used to represent |
| keystrokes. |
| |
| The text `C-k' is read as `Control-K' and describes the character |
| produced when the <k> key is pressed while the Control key is depressed. |
| |
| The text `M-k' is read as `Meta-K' and describes the character |
| produced when the Meta key (if you have one) is depressed, and the <k> |
| key is pressed. The Meta key is labeled <ALT> on many keyboards. On |
| keyboards with two keys labeled <ALT> (usually to either side of the |
| space bar), the <ALT> on the left side is generally set to work as a |
| Meta key. The <ALT> key on the right may also be configured to work as |
| a Meta key or may be configured as some other modifier, such as a |
| Compose key for typing accented characters. |
| |
| If you do not have a Meta or <ALT> key, or another key working as a |
| Meta key, the identical keystroke can be generated by typing <ESC> |
| _first_, and then typing <k>. Either process is known as "metafying" |
| the <k> key. |
| |
| The text `M-C-k' is read as `Meta-Control-k' and describes the |
| character produced by "metafying" `C-k'. |
| |
| In addition, several keys have their own names. Specifically, |
| <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves |
| when seen in this text, or in an init file (*note Readline Init File::). |
| If your keyboard lacks a <LFD> key, typing <C-j> will produce the |
| desired character. The <RET> key may be labeled <Return> or <Enter> on |
| some keyboards. |
| |
| |
| File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing |
| |
| 32.2 Readline Interaction |
| ========================= |
| |
| Often during an interactive session you type in a long line of text, |
| only to notice that the first word on the line is misspelled. The |
| Readline library gives you a set of commands for manipulating the text |
| as you type it in, allowing you to just fix your typo, and not forcing |
| you to retype the majority of the line. Using these editing commands, |
| you move the cursor to the place that needs correction, and delete or |
| insert the text of the corrections. Then, when you are satisfied with |
| the line, you simply press <RET>. You do not have to be at the end of |
| the line to press <RET>; the entire line is accepted regardless of the |
| location of the cursor within the line. |
| |
| * Menu: |
| |
| * Readline Bare Essentials:: The least you need to know about Readline. |
| * Readline Movement Commands:: Moving about the input line. |
| * Readline Killing Commands:: How to delete text, and how to get it back! |
| * Readline Arguments:: Giving numeric arguments to commands. |
| * Searching:: Searching through previous lines. |
| |
| |
| File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction |
| |
| 32.2.1 Readline Bare Essentials |
| ------------------------------- |
| |
| In order to enter characters into the line, simply type them. The typed |
| character appears where the cursor was, and then the cursor moves one |
| space to the right. If you mistype a character, you can use your erase |
| character to back up and delete the mistyped character. |
| |
| Sometimes you may mistype a character, and not notice the error |
| until you have typed several other characters. In that case, you can |
| type `C-b' to move the cursor to the left, and then correct your |
| mistake. Afterwards, you can move the cursor to the right with `C-f'. |
| |
| When you add text in the middle of a line, you will notice that |
| characters to the right of the cursor are `pushed over' to make room |
| for the text that you have inserted. Likewise, when you delete text |
| behind the cursor, characters to the right of the cursor are `pulled |
| back' to fill in the blank space created by the removal of the text. A |
| list of the bare essentials for editing the text of an input line |
| follows. |
| |
| `C-b' |
| Move back one character. |
| |
| `C-f' |
| Move forward one character. |
| |
| <DEL> or <Backspace> |
| Delete the character to the left of the cursor. |
| |
| `C-d' |
| Delete the character underneath the cursor. |
| |
| Printing characters |
| Insert the character into the line at the cursor. |
| |
| `C-_' or `C-x C-u' |
| Undo the last editing command. You can undo all the way back to an |
| empty line. |
| |
| (Depending on your configuration, the <Backspace> key be set to delete |
| the character to the left of the cursor and the <DEL> key set to delete |
| the character underneath the cursor, like `C-d', rather than the |
| 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 |
| |
| 32.2.2 Readline Movement Commands |
| --------------------------------- |
| |
| The above table describes the most basic keystrokes that you need in |
| order to do editing of the input line. For your convenience, many |
| other commands have been added in addition to `C-b', `C-f', `C-d', and |
| <DEL>. Here are some commands for moving more rapidly about the line. |
| |
| `C-a' |
| Move to the start of the line. |
| |
| `C-e' |
| Move to the end of the line. |
| |
| `M-f' |
| Move forward a word, where a word is composed of letters and |
| digits. |
| |
| `M-b' |
| Move backward a word. |
| |
| `C-l' |
| Clear the screen, reprinting the current line at the top. |
| |
| Notice how `C-f' moves forward a character, while `M-f' moves |
| forward a word. It is a loose convention that control keystrokes |
| 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 |
| |
| 32.2.3 Readline Killing Commands |
| -------------------------------- |
| |
| "Killing" text means to delete the text from the line, but to save it |
| away for later use, usually by "yanking" (re-inserting) it back into |
| the line. (`Cut' and `paste' are more recent jargon for `kill' and |
| `yank'.) |
| |
| If the description for a command says that it `kills' text, then you |
| can be sure that you can get the text back in a different (or the same) |
| place later. |
| |
| When you use a kill command, the text is saved in a "kill-ring". |
| Any number of consecutive kills save all of the killed text together, so |
| that when you yank it back, you get it all. The kill ring is not line |
| specific; the text that you killed on a previously typed line is |
| available to be yanked back later, when you are typing another line. |
| |
| Here is the list of commands for killing text. |
| |
| `C-k' |
| Kill the text from the current cursor position to the end of the |
| line. |
| |
| `M-d' |
| Kill from the cursor to the end of the current word, or, if between |
| words, to the end of the next word. Word boundaries are the same |
| as those used by `M-f'. |
| |
| `M-<DEL>' |
| Kill from the cursor the start of the current word, or, if between |
| words, to the start of the previous word. Word boundaries are the |
| same as those used by `M-b'. |
| |
| `C-w' |
| Kill from the cursor to the previous whitespace. This is |
| different than `M-<DEL>' because the word boundaries differ. |
| |
| |
| Here is how to "yank" the text back into the line. Yanking means to |
| copy the most-recently-killed text from the kill buffer. |
| |
| `C-y' |
| Yank the most recently killed text back into the buffer at the |
| cursor. |
| |
| `M-y' |
| Rotate the kill-ring, and yank the new top. You can only do this |
| if the prior command is `C-y' or `M-y'. |
| |
| |
| File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction |
| |
| 32.2.4 Readline Arguments |
| ------------------------- |
| |
| You can pass numeric arguments to Readline commands. Sometimes the |
| argument acts as a repeat count, other times it is the sign of the |
| argument that is significant. If you pass a negative argument to a |
| command which normally acts in a forward direction, that command will |
| act in a backward direction. For example, to kill text back to the |
| start of the line, you might type `M-- C-k'. |
| |
| The general way to pass numeric arguments to a command is to type |
| meta digits before the command. If the first `digit' typed is a minus |
| sign (`-'), then the sign of the argument will be negative. Once you |
| have typed one meta digit to get the argument started, you can type the |
| remainder of the digits, and then the command. For example, to give |
| the `C-d' command an argument of 10, you could type `M-1 0 C-d', which |
| will delete the next ten characters on the input line. |
| |
| |
| File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction |
| |
| 32.2.5 Searching for Commands in the History |
| -------------------------------------------- |
| |
| Readline provides commands for searching through the command history |
| for lines containing a specified string. There are two search modes: |
| "incremental" and "non-incremental". |
| |
| Incremental searches begin before the user has finished typing the |
| search string. As each character of the search string is typed, |
| Readline displays the next entry from the history matching the string |
| typed so far. An incremental search requires only as many characters |
| as needed to find the desired history entry. To search backward in the |
| history for a particular string, type `C-r'. Typing `C-s' searches |
| forward through the history. The characters present in the value of |
| the `isearch-terminators' variable are used to terminate an incremental |
| search. If that variable has not been assigned a value, the <ESC> and |
| `C-J' characters will terminate an incremental search. `C-g' will |
| abort an incremental search and restore the original line. When the |
| search is terminated, the history entry containing the search string |
| becomes the current line. |
| |
| To find other matching entries in the history list, type `C-r' or |
| `C-s' as appropriate. This will search backward or forward in the |
| history for the next entry matching the search string typed so far. |
| Any other key sequence bound to a Readline command will terminate the |
| search and execute that command. For instance, a <RET> will terminate |
| the search and accept the line, thereby executing the command from the |
| history list. A movement command will terminate the search, make the |
| last line found the current line, and begin editing. |
| |
| Readline remembers the last incremental search string. If two |
| `C-r's are typed without any intervening characters defining a new |
| search string, any remembered search string is used. |
| |
| Non-incremental searches read the entire search string before |
| starting to search for matching history lines. The search string may be |
| 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 |
| |
| 32.3 Readline Init File |
| ======================= |
| |
| Although the Readline library comes with a set of Emacs-like |
| keybindings installed by default, it is possible to use a different set |
| of keybindings. Any user can customize programs that use Readline by |
| putting commands in an "inputrc" file, conventionally in his home |
| directory. The name of this file is taken from the value of the |
| environment variable `INPUTRC'. If that variable is unset, the default |
| is `~/.inputrc'. If that file does not exist or cannot be read, the |
| ultimate default is `/etc/inputrc'. |
| |
| When a program which uses the Readline library starts up, the init |
| file is read, and the key bindings are set. |
| |
| In addition, the `C-x C-r' command re-reads this init file, thus |
| incorporating any changes that you might have made to it. |
| |
| * Menu: |
| |
| * Readline Init File Syntax:: Syntax for the commands in the inputrc file. |
| |
| * Conditional Init Constructs:: Conditional key bindings in the inputrc file. |
| |
| * Sample Init File:: An example inputrc file. |
| |
| |
| File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File |
| |
| 32.3.1 Readline Init File Syntax |
| -------------------------------- |
| |
| There are only a few basic constructs allowed in the Readline init |
| file. Blank lines are ignored. Lines beginning with a `#' are |
| comments. Lines beginning with a `$' indicate conditional constructs |
| (*note Conditional Init Constructs::). Other lines denote variable |
| settings and key bindings. |
| |
| Variable Settings |
| You can modify the run-time behavior of Readline by altering the |
| values of variables in Readline using the `set' command within the |
| init file. The syntax is simple: |
| |
| set VARIABLE VALUE |
| |
| Here, for example, is how to change from the default Emacs-like |
| key binding to use `vi' line editing commands: |
| |
| set editing-mode vi |
| |
| Variable names and values, where appropriate, are recognized |
| without regard to case. Unrecognized variable names are ignored. |
| |
| Boolean variables (those that can be set to on or off) are set to |
| on if the value is null or empty, ON (case-insensitive), or 1. |
| Any other value results in the variable being set to off. |
| |
| A great deal of run-time behavior is changeable with the following |
| variables. |
| |
| `bell-style' |
| Controls what happens when Readline wants to ring the |
| terminal bell. If set to `none', Readline never rings the |
| bell. If set to `visible', Readline uses a visible bell if |
| one is available. If set to `audible' (the default), |
| Readline attempts to ring the terminal's bell. |
| |
| `bind-tty-special-chars' |
| If set to `on', Readline attempts to bind the control |
| characters treated specially by the kernel's terminal driver |
| to their Readline equivalents. |
| |
| `comment-begin' |
| The string to insert at the beginning of the line when the |
| `insert-comment' command is executed. The default value is |
| `"#"'. |
| |
| `completion-display-width' |
| The number of screen columns used to display possible matches |
| when performing completion. The value is ignored if it is |
| less than 0 or greater than the terminal screen width. A |
| value of 0 will cause matches to be displayed one per line. |
| The default value is -1. |
| |
| `completion-ignore-case' |
| If set to `on', Readline performs filename matching and |
| completion in a case-insensitive fashion. The default value |
| is `off'. |
| |
| `completion-map-case' |
| If set to `on', and COMPLETION-IGNORE-CASE is enabled, |
| Readline treats hyphens (`-') and underscores (`_') as |
| equivalent when performing case-insensitive filename matching |
| and completion. |
| |
| `completion-prefix-display-length' |
| The length in characters of the common prefix of a list of |
| possible completions that is displayed without modification. |
| When set to a value greater than zero, common prefixes longer |
| than this value are replaced with an ellipsis when displaying |
| possible completions. |
| |
| `completion-query-items' |
| The number of possible completions that determines when the |
| user is asked whether the list of possibilities should be |
| displayed. If the number of possible completions is greater |
| than this value, Readline will ask the user whether or not he |
| wishes to view them; otherwise, they are simply listed. This |
| variable must be set to an integer value greater than or |
| equal to 0. A negative value means Readline should never ask. |
| The default limit is `100'. |
| |
| `convert-meta' |
| If set to `on', Readline will convert characters with the |
| eighth bit set to an ASCII key sequence by stripping the |
| eighth bit and prefixing an <ESC> character, converting them |
| to a meta-prefixed key sequence. The default value is `on'. |
| |
| `disable-completion' |
| If set to `On', Readline will inhibit word completion. |
| Completion characters will be inserted into the line as if |
| they had been mapped to `self-insert'. The default is `off'. |
| |
| `editing-mode' |
| The `editing-mode' variable controls which default set of key |
| bindings is used. By default, Readline starts up in Emacs |
| editing mode, where the keystrokes are most similar to Emacs. |
| This variable can be set to either `emacs' or `vi'. |
| |
| `echo-control-characters' |
| When set to `on', on operating systems that indicate they |
| support it, readline echoes a character corresponding to a |
| signal generated from the keyboard. The default is `on'. |
| |
| `enable-keypad' |
| When set to `on', Readline will try to enable the application |
| keypad when it is called. Some systems need this to enable |
| the arrow keys. The default is `off'. |
| |
| `enable-meta-key' |
| When set to `on', Readline will try to enable any meta |
| modifier key the terminal claims to support when it is |
| called. On many terminals, the meta key is used to send |
| eight-bit characters. The default is `on'. |
| |
| `expand-tilde' |
| If set to `on', tilde expansion is performed when Readline |
| attempts word completion. The default is `off'. |
| |
| `history-preserve-point' |
| If set to `on', the history code attempts to place the point |
| (the current cursor position) at the same location on each |
| history line retrieved with `previous-history' or |
| `next-history'. The default is `off'. |
| |
| `history-size' |
| Set the maximum number of history entries saved in the |
| history list. If set to zero, the number of entries in the |
| history list is not limited. |
| |
| `horizontal-scroll-mode' |
| This variable can be set to either `on' or `off'. Setting it |
| to `on' means that the text of the lines being edited will |
| scroll horizontally on a single screen line when they are |
| longer than the width of the screen, instead of wrapping onto |
| a new screen line. By default, this variable is set to `off'. |
| |
| `input-meta' |
| If set to `on', Readline will enable eight-bit input (it will |
| not clear the eighth bit in the characters it reads), |
| regardless of what the terminal claims it can support. The |
| default value is `off'. The name `meta-flag' is a synonym |
| for this variable. |
| |
| `isearch-terminators' |
| The string of characters that should terminate an incremental |
| search without subsequently executing the character as a |
| command (*note Searching::). If this variable has not been |
| given a value, the characters <ESC> and `C-J' will terminate |
| an incremental search. |
| |
| `keymap' |
| Sets Readline's idea of the current keymap for key binding |
| commands. Acceptable `keymap' names are `emacs', |
| `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', |
| `vi-command', and `vi-insert'. `vi' is equivalent to |
| `vi-command'; `emacs' is equivalent to `emacs-standard'. The |
| default value is `emacs'. The value of the `editing-mode' |
| variable also affects the default keymap. |
| |
| `mark-directories' |
| If set to `on', completed directory names have a slash |
| appended. The default is `on'. |
| |
| `mark-modified-lines' |
| This variable, when set to `on', causes Readline to display an |
| asterisk (`*') at the start of history lines which have been |
| modified. This variable is `off' by default. |
| |
| `mark-symlinked-directories' |
| If set to `on', completed names which are symbolic links to |
| directories have a slash appended (subject to the value of |
| `mark-directories'). The default is `off'. |
| |
| `match-hidden-files' |
| This variable, when set to `on', causes Readline to match |
| files whose names begin with a `.' (hidden files) when |
| performing filename completion. If set to `off', the leading |
| `.' must be supplied by the user in the filename to be |
| completed. This variable is `on' by default. |
| |
| `menu-complete-display-prefix' |
| If set to `on', menu completion displays the common prefix of |
| the list of possible completions (which may be empty) before |
| cycling through the list. The default is `off'. |
| |
| `output-meta' |
| If set to `on', Readline will display characters with the |
| eighth bit set directly rather than as a meta-prefixed escape |
| sequence. The default is `off'. |
| |
| `page-completions' |
| If set to `on', Readline uses an internal `more'-like pager |
| to display a screenful of possible completions at a time. |
| This variable is `on' by default. |
| |
| `print-completions-horizontally' |
| If set to `on', Readline will display completions with matches |
| sorted horizontally in alphabetical order, rather than down |
| the screen. The default is `off'. |
| |
| `revert-all-at-newline' |
| If set to `on', Readline will undo all changes to history |
| lines before returning when `accept-line' is executed. By |
| default, history lines may be modified and retain individual |
| undo lists across calls to `readline'. The default is `off'. |
| |
| `show-all-if-ambiguous' |
| This alters the default behavior of the completion functions. |
| If set to `on', words which have more than one possible |
| completion cause the matches to be listed immediately instead |
| of ringing the bell. The default value is `off'. |
| |
| `show-all-if-unmodified' |
| This alters the default behavior of the completion functions |
| in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to |
| `on', words which have more than one possible completion |
| without any possible partial completion (the possible |
| completions don't share a common prefix) cause the matches to |
| be listed immediately instead of ringing the bell. The |
| default value is `off'. |
| |
| `skip-completed-text' |
| If set to `on', this alters the default completion behavior |
| when inserting a single match into the line. It's only |
| active when performing completion in the middle of a word. |
| If enabled, readline does not insert characters from the |
| completion that match characters after point in the word |
| being completed, so portions of the word following the cursor |
| are not duplicated. For instance, if this is enabled, |
| attempting completion when the cursor is after the `e' in |
| `Makefile' will result in `Makefile' rather than |
| `Makefilefile', assuming there is a single possible |
| completion. The default value is `off'. |
| |
| `visible-stats' |
| If set to `on', a character denoting a file's type is |
| appended to the filename when listing possible completions. |
| The default is `off'. |
| |
| |
| Key Bindings |
| The syntax for controlling key bindings in the init file is |
| simple. First you need to find the name of the command that you |
| want to change. The following sections contain tables of the |
| command name, the default keybinding, if any, and a short |
| description of what the command does. |
| |
| Once you know the name of the command, simply place on a line in |
| the init file the name of the key you wish to bind the command to, |
| a colon, and then the name of the command. There can be no space |
| between the key name and the colon - that will be interpreted as |
| part of the key name. The name of the key can be expressed in |
| different ways, depending on what you find most comfortable. |
| |
| In addition to command names, readline allows keys to be bound to |
| a string that is inserted when the key is pressed (a MACRO). |
| |
| KEYNAME: FUNCTION-NAME or MACRO |
| KEYNAME is the name of a key spelled out in English. For |
| example: |
| Control-u: universal-argument |
| Meta-Rubout: backward-kill-word |
| Control-o: "> output" |
| |
| In the above example, `C-u' is bound to the function |
| `universal-argument', `M-DEL' is bound to the function |
| `backward-kill-word', and `C-o' is bound to run the macro |
| expressed on the right hand side (that is, to insert the text |
| `> output' into the line). |
| |
| A number of symbolic character names are recognized while |
| processing this key binding syntax: DEL, ESC, ESCAPE, LFD, |
| NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. |
| |
| "KEYSEQ": FUNCTION-NAME or MACRO |
| KEYSEQ differs from KEYNAME above in that strings denoting an |
| entire key sequence can be specified, by placing the key |
| sequence in double quotes. Some GNU Emacs style key escapes |
| can be used, as in the following example, but the special |
| character names are not recognized. |
| |
| "\C-u": universal-argument |
| "\C-x\C-r": re-read-init-file |
| "\e[11~": "Function Key 1" |
| |
| In the above example, `C-u' is again bound to the function |
| `universal-argument' (just as it was in the first example), |
| `C-x C-r' is bound to the function `re-read-init-file', and |
| `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function |
| Key 1'. |
| |
| |
| The following GNU Emacs style escape sequences are available when |
| specifying key sequences: |
| |
| `\C-' |
| control prefix |
| |
| `\M-' |
| meta prefix |
| |
| `\e' |
| an escape character |
| |
| `\\' |
| backslash |
| |
| `\"' |
| <">, a double quotation mark |
| |
| `\'' |
| <'>, a single quote or apostrophe |
| |
| In addition to the GNU Emacs style escape sequences, a second set |
| of backslash escapes is available: |
| |
| `\a' |
| alert (bell) |
| |
| `\b' |
| backspace |
| |
| `\d' |
| delete |
| |
| `\f' |
| form feed |
| |
| `\n' |
| newline |
| |
| `\r' |
| carriage return |
| |
| `\t' |
| horizontal tab |
| |
| `\v' |
| vertical tab |
| |
| `\NNN' |
| the eight-bit character whose value is the octal value NNN |
| (one to three digits) |
| |
| `\xHH' |
| the eight-bit character whose value is the hexadecimal value |
| HH (one or two hex digits) |
| |
| When entering the text of a macro, single or double quotes must be |
| used to indicate a macro definition. Unquoted text is assumed to |
| be a function name. In the macro body, the backslash escapes |
| described above are expanded. Backslash will quote any other |
| character in the macro text, including `"' and `''. For example, |
| the following binding will make `C-x \' insert a single `\' into |
| the line: |
| "\C-x\\": "\\" |
| |
| |
| |
| File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File |
| |
| 32.3.2 Conditional Init Constructs |
| ---------------------------------- |
| |
| Readline implements a facility similar in spirit to the conditional |
| compilation features of the C preprocessor which allows key bindings |
| and variable settings to be performed as the result of tests. There |
| are four parser directives used. |
| |
| `$if' |
| The `$if' construct allows bindings to be made based on the |
| editing mode, the terminal being used, or the application using |
| Readline. The text of the test extends to the end of the line; no |
| characters are required to isolate it. |
| |
| `mode' |
| The `mode=' form of the `$if' directive is used to test |
| whether Readline is in `emacs' or `vi' mode. This may be |
| used in conjunction with the `set keymap' command, for |
| instance, to set bindings in the `emacs-standard' and |
| `emacs-ctlx' keymaps only if Readline is starting out in |
| `emacs' mode. |
| |
| `term' |
| The `term=' form may be used to include terminal-specific key |
| bindings, perhaps to bind the key sequences output by the |
| terminal's function keys. The word on the right side of the |
| `=' is tested against both the full name of the terminal and |
| the portion of the terminal name before the first `-'. This |
| allows `sun' to match both `sun' and `sun-cmd', for instance. |
| |
| `application' |
| The APPLICATION construct is used to include |
| application-specific settings. Each program using the |
| Readline library sets the APPLICATION NAME, and you can test |
| for a particular value. This could be used to bind key |
| sequences to functions useful for a specific program. For |
| instance, the following command adds a key sequence that |
| quotes the current or previous word in Bash: |
| $if Bash |
| # Quote the current or previous word |
| "\C-xq": "\eb\"\ef\"" |
| $endif |
| |
| `$endif' |
| This command, as seen in the previous example, terminates an `$if' |
| command. |
| |
| `$else' |
| Commands in this branch of the `$if' directive are executed if the |
| test fails. |
| |
| `$include' |
| This directive takes a single filename as an argument and reads |
| commands and bindings from that file. For example, the following |
| directive reads from `/etc/inputrc': |
| $include /etc/inputrc |
| |
| |
| File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File |
| |
| 32.3.3 Sample Init File |
| ----------------------- |
| |
| Here is an example of an INPUTRC file. This illustrates key binding, |
| variable assignment, and conditional syntax. |
| |
| |
| # This file controls the behaviour of line input editing for |
| # programs that use the GNU Readline library. Existing |
| # programs include FTP, Bash, and GDB. |
| # |
| # You can re-read the inputrc file with C-x C-r. |
| # Lines beginning with '#' are comments. |
| # |
| # First, include any systemwide bindings and variable |
| # assignments from /etc/Inputrc |
| $include /etc/Inputrc |
| |
| # |
| # Set various bindings for emacs mode. |
| |
| set editing-mode emacs |
| |
| $if mode=emacs |
| |
| Meta-Control-h: backward-kill-word Text after the function name is ignored |
| |
| # |
| # Arrow keys in keypad mode |
| # |
| #"\M-OD": backward-char |
| #"\M-OC": forward-char |
| #"\M-OA": previous-history |
| #"\M-OB": next-history |
| # |
| # Arrow keys in ANSI mode |
| # |
| "\M-[D": backward-char |
| "\M-[C": forward-char |
| "\M-[A": previous-history |
| "\M-[B": next-history |
| # |
| # Arrow keys in 8 bit keypad mode |
| # |
| #"\M-\C-OD": backward-char |
| #"\M-\C-OC": forward-char |
| #"\M-\C-OA": previous-history |
| #"\M-\C-OB": next-history |
| # |
| # Arrow keys in 8 bit ANSI mode |
| # |
| #"\M-\C-[D": backward-char |
| #"\M-\C-[C": forward-char |
| #"\M-\C-[A": previous-history |
| #"\M-\C-[B": next-history |
| |
| C-q: quoted-insert |
| |
| $endif |
| |
| # An old-style binding. This happens to be the default. |
| TAB: complete |
| |
| # Macros that are convenient for shell interaction |
| $if Bash |
| # edit the path |
| "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" |
| # prepare to type a quoted word -- |
| # insert open and close double quotes |
| # and move to just after the open quote |
| "\C-x\"": "\"\"\C-b" |
| # insert a backslash (testing backslash escapes |
| # in sequences and macros) |
| "\C-x\\": "\\" |
| # Quote the current or previous word |
| "\C-xq": "\eb\"\ef\"" |
| # Add a binding to refresh the line, which is unbound |
| "\C-xr": redraw-current-line |
| # Edit variable on current line. |
| "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" |
| $endif |
| |
| # use a visible bell if one is available |
| set bell-style visible |
| |
| # don't strip characters to 7 bits when reading |
| set input-meta on |
| |
| # allow iso-latin1 characters to be inserted rather |
| # than converted to prefix-meta sequences |
| set convert-meta off |
| |
| # display characters with the eighth bit set directly |
| # rather than as meta-prefixed characters |
| set output-meta on |
| |
| # if there are more than 150 possible completions for |
| # a word, ask the user if he wants to see all of them |
| set completion-query-items 150 |
| |
| # For FTP |
| $if Ftp |
| "\C-xg": "get \M-?" |
| "\C-xt": "put \M-?" |
| "\M-.": yank-last-arg |
| $endif |
| |
| |
| File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing |
| |
| 32.4 Bindable Readline Commands |
| =============================== |
| |
| * Menu: |
| |
| * Commands For Moving:: Moving about the line. |
| * Commands For History:: Getting at previous lines. |
| * Commands For Text:: Commands for changing text. |
| * Commands For Killing:: Commands for killing and yanking. |
| * Numeric Arguments:: Specifying numeric arguments, repeat counts. |
| * Commands For Completion:: Getting Readline to do the typing for you. |
| * Keyboard Macros:: Saving and re-executing typed characters |
| * Miscellaneous Commands:: Other miscellaneous commands. |
| |
| This section describes Readline commands that may be bound to key |
| sequences. Command names without an accompanying key sequence are |
| unbound by default. |
| |
| In the following descriptions, "point" refers to the current cursor |
| position, and "mark" refers to a cursor position saved by the |
| `set-mark' command. The text between the point and mark is referred to |
| as the "region". |
| |
| |
| File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands |
| |
| 32.4.1 Commands For Moving |
| -------------------------- |
| |
| `beginning-of-line (C-a)' |
| Move to the start of the current line. |
| |
| `end-of-line (C-e)' |
| Move to the end of the line. |
| |
| `forward-char (C-f)' |
| Move forward a character. |
| |
| `backward-char (C-b)' |
| Move back a character. |
| |
| `forward-word (M-f)' |
| Move forward to the end of the next word. Words are composed of |
| letters and digits. |
| |
| `backward-word (M-b)' |
| Move back to the start of the current or previous word. Words are |
| composed of letters and digits. |
| |
| `clear-screen (C-l)' |
| Clear the screen and redraw the current line, leaving the current |
| line at the top of the screen. |
| |
| `redraw-current-line ()' |
| Refresh the current line. By default, this is unbound. |
| |
| |
| |
| File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands |
| |
| 32.4.2 Commands For Manipulating The History |
| -------------------------------------------- |
| |
| `accept-line (Newline or Return)' |
| Accept the line regardless of where the cursor is. If this line is |
| non-empty, it may be added to the history list for future recall |
| with `add_history()'. If this line is a modified history line, |
| the history line is restored to its original state. |
| |
| `previous-history (C-p)' |
| Move `back' through the history list, fetching the previous |
| command. |
| |
| `next-history (C-n)' |
| Move `forward' through the history list, fetching the next command. |
| |
| `beginning-of-history (M-<)' |
| Move to the first line in the history. |
| |
| `end-of-history (M->)' |
| Move to the end of the input history, i.e., the line currently |
| being entered. |
| |
| `reverse-search-history (C-r)' |
| Search backward starting at the current line and moving `up' |
| through the history as necessary. This is an incremental search. |
| |
| `forward-search-history (C-s)' |
| Search forward starting at the current line and moving `down' |
| through the the history as necessary. This is an incremental |
| search. |
| |
| `non-incremental-reverse-search-history (M-p)' |
| Search backward starting at the current line and moving `up' |
| through the history as necessary using a non-incremental search |
| for a string supplied by the user. |
| |
| `non-incremental-forward-search-history (M-n)' |
| Search forward starting at the current line and moving `down' |
| through the the history as necessary using a non-incremental search |
| for a string supplied by the user. |
| |
| `history-search-forward ()' |
| Search forward through the history for the string of characters |
| between the start of the current line and the point. This is a |
| non-incremental search. By default, this command is unbound. |
| |
| `history-search-backward ()' |
| Search backward through the history for the string of characters |
| between the start of the current line and the point. This is a |
| non-incremental search. By default, this command is unbound. |
| |
| `yank-nth-arg (M-C-y)' |
| Insert the first argument to the previous command (usually the |
| second word on the previous line) at point. With an argument N, |
| insert the Nth word from the previous command (the words in the |
| previous command begin with word 0). A negative argument inserts |
| the Nth word from the end of the previous command. Once the |
| argument N is computed, the argument is extracted as if the `!N' |
| history expansion had been specified. |
| |
| `yank-last-arg (M-. or M-_)' |
| Insert last argument to the previous command (the last word of the |
| previous history entry). With a numeric argument, behave exactly |
| like `yank-nth-arg'. Successive calls to `yank-last-arg' move |
| back through the history list, inserting the last word (or the |
| word specified by the argument to the first call) of each line in |
| turn. Any numeric argument supplied to these successive calls |
| determines the direction to move through the history. A negative |
| argument switches the direction through the history (back or |
| forward). The history expansion facilities are used to extract |
| the last argument, as if the `!$' history expansion had been |
| specified. |
| |
| |
| |
| File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands |
| |
| 32.4.3 Commands For Changing Text |
| --------------------------------- |
| |
| `delete-char (C-d)' |
| Delete the character at point. If point is at the beginning of |
| the line, there are no characters in the line, and the last |
| character typed was not bound to `delete-char', then return EOF. |
| |
| `backward-delete-char (Rubout)' |
| Delete the character behind the cursor. A numeric argument means |
| to kill the characters instead of deleting them. |
| |
| `forward-backward-delete-char ()' |
| Delete the character under the cursor, unless the cursor is at the |
| end of the line, in which case the character behind the cursor is |
| deleted. By default, this is not bound to a key. |
| |
| `quoted-insert (C-q or C-v)' |
| Add the next character typed to the line verbatim. This is how to |
| insert key sequences like `C-q', for example. |
| |
| `tab-insert (M-<TAB>)' |
| Insert a tab character. |
| |
| `self-insert (a, b, A, 1, !, ...)' |
| Insert yourself. |
| |
| `transpose-chars (C-t)' |
| Drag the character before the cursor forward over the character at |
| the cursor, moving the cursor forward as well. If the insertion |
| point is at the end of the line, then this transposes the last two |
| characters of the line. Negative arguments have no effect. |
| |
| `transpose-words (M-t)' |
| Drag the word before point past the word after point, moving point |
| past that word as well. If the insertion point is at the end of |
| the line, this transposes the last two words on the line. |
| |
| `upcase-word (M-u)' |
| Uppercase the current (or following) word. With a negative |
| argument, uppercase the previous word, but do not move the cursor. |
| |
| `downcase-word (M-l)' |
| Lowercase the current (or following) word. With a negative |
| argument, lowercase the previous word, but do not move the cursor. |
| |
| `capitalize-word (M-c)' |
| Capitalize the current (or following) word. With a negative |
| argument, capitalize the previous word, but do not move the cursor. |
| |
| `overwrite-mode ()' |
| Toggle overwrite mode. With an explicit positive numeric argument, |
| switches to overwrite mode. With an explicit non-positive numeric |
| argument, switches to insert mode. This command affects only |
| `emacs' mode; `vi' mode does overwrite differently. Each call to |
| `readline()' starts in insert mode. |
| |
| In overwrite mode, characters bound to `self-insert' replace the |
| text at point rather than pushing the text to the right. |
| Characters bound to `backward-delete-char' replace the character |
| before point with a space. |
| |
| By default, this command is unbound. |
| |
| |
| |
| File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands |
| |
| 32.4.4 Killing And Yanking |
| -------------------------- |
| |
| `kill-line (C-k)' |
| Kill the text from point to the end of the line. |
| |
| `backward-kill-line (C-x Rubout)' |
| Kill backward to the beginning of the line. |
| |
| `unix-line-discard (C-u)' |
| Kill backward from the cursor to the beginning of the current line. |
| |
| `kill-whole-line ()' |
| Kill all characters on the current line, no matter where point is. |
| By default, this is unbound. |
| |
| `kill-word (M-d)' |
| Kill from point to the end of the current word, or if between |
| words, to the end of the next word. Word boundaries are the same |
| as `forward-word'. |
| |
| `backward-kill-word (M-<DEL>)' |
| Kill the word behind point. Word boundaries are the same as |
| `backward-word'. |
| |
| `unix-word-rubout (C-w)' |
| Kill the word behind point, using white space as a word boundary. |
| The killed text is saved on the kill-ring. |
| |
| `unix-filename-rubout ()' |
| Kill the word behind point, using white space and the slash |
| character as the word boundaries. The killed text is saved on the |
| kill-ring. |
| |
| `delete-horizontal-space ()' |
| Delete all spaces and tabs around point. By default, this is |
| unbound. |
| |
| `kill-region ()' |
| Kill the text in the current region. By default, this command is |
| unbound. |
| |
| `copy-region-as-kill ()' |
| Copy the text in the region to the kill buffer, so it can be yanked |
| right away. By default, this command is unbound. |
| |
| `copy-backward-word ()' |
| Copy the word before point to the kill buffer. The word |
| boundaries are the same as `backward-word'. By default, this |
| command is unbound. |
| |
| `copy-forward-word ()' |
| Copy the word following point to the kill buffer. The word |
| boundaries are the same as `forward-word'. By default, this |
| command is unbound. |
| |
| `yank (C-y)' |
| Yank the top of the kill ring into the buffer at point. |
| |
| `yank-pop (M-y)' |
| Rotate the kill-ring, and yank the new top. You can only do this |
| if the prior command is `yank' or `yank-pop'. |
| |
| |
| File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands |
| |
| 32.4.5 Specifying Numeric Arguments |
| ----------------------------------- |
| |
| `digit-argument (M-0, M-1, ... M--)' |
| Add this digit to the argument already accumulating, or start a new |
| argument. `M--' starts a negative argument. |
| |
| `universal-argument ()' |
| This is another way to specify an argument. If this command is |
| followed by one or more digits, optionally with a leading minus |
| sign, those digits define the argument. If the command is |
| followed by digits, executing `universal-argument' again ends the |
| numeric argument, but is otherwise ignored. As a special case, if |
| this command is immediately followed by a character that is |
| neither a digit or minus sign, the argument count for the next |
| command is multiplied by four. The argument count is initially |
| one, so executing this function the first time makes the argument |
| count four, a second time makes the argument count sixteen, and so |
| on. By default, this is not bound to a key. |
| |
| |
| File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands |
| |
| 32.4.6 Letting Readline Type For You |
| ------------------------------------ |
| |
| `complete (<TAB>)' |
| Attempt to perform completion on the text before point. The |
| actual completion performed is application-specific. The default |
| is filename completion. |
| |
| `possible-completions (M-?)' |
| List the possible completions of the text before point. When |
| displaying completions, Readline sets the number of columns used |
| for display to the value of `completion-display-width', the value |
| of the environment variable `COLUMNS', or the screen width, in |
| that order. |
| |
| `insert-completions (M-*)' |
| Insert all completions of the text before point that would have |
| been generated by `possible-completions'. |
| |
| `menu-complete ()' |
| Similar to `complete', but replaces the word to be completed with |
| a single match from the list of possible completions. Repeated |
| execution of `menu-complete' steps through the list of possible |
| completions, inserting each match in turn. At the end of the list |
| of completions, the bell is rung (subject to the setting of |
| `bell-style') and the original text is restored. An argument of N |
| moves N positions forward in the list of matches; a negative |
| argument may be used to move backward through the list. This |
| command is intended to be bound to <TAB>, but is unbound by |
| default. |
| |
| `menu-complete-backward ()' |
| Identical to `menu-complete', but moves backward through the list |
| of possible completions, as if `menu-complete' had been given a |
| negative argument. |
| |
| `delete-char-or-list ()' |
| Deletes the character under the cursor if not at the beginning or |
| end of the line (like `delete-char'). If at the end of the line, |
| behaves identically to `possible-completions'. This command is |
| unbound by default. |
| |
| |
| |
| File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands |
| |
| 32.4.7 Keyboard Macros |
| ---------------------- |
| |
| `start-kbd-macro (C-x ()' |
| Begin saving the characters typed into the current keyboard macro. |
| |
| `end-kbd-macro (C-x ))' |
| Stop saving the characters typed into the current keyboard macro |
| and save the definition. |
| |
| `call-last-kbd-macro (C-x e)' |
| Re-execute the last keyboard macro defined, by making the |
| characters in the macro appear as if typed at the keyboard. |
| |
| |
| |
| File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands |
| |
| 32.4.8 Some Miscellaneous Commands |
| ---------------------------------- |
| |
| `re-read-init-file (C-x C-r)' |
| Read in the contents of the INPUTRC file, and incorporate any |
| bindings or variable assignments found there. |
| |
| `abort (C-g)' |
| Abort the current editing command and ring the terminal's bell |
| (subject to the setting of `bell-style'). |
| |
| `do-uppercase-version (M-a, M-b, M-X, ...)' |
| If the metafied character X is lowercase, run the command that is |
| bound to the corresponding uppercase character. |
| |
| `prefix-meta (<ESC>)' |
| Metafy the next character typed. This is for keyboards without a |
| meta key. Typing `<ESC> f' is equivalent to typing `M-f'. |
| |
| `undo (C-_ or C-x C-u)' |
| Incremental undo, separately remembered for each line. |
| |
| `revert-line (M-r)' |
| Undo all changes made to this line. This is like executing the |
| `undo' command enough times to get back to the beginning. |
| |
| `tilde-expand (M-~)' |
| Perform tilde expansion on the current word. |
| |
| `set-mark (C-@)' |
| Set the mark to the point. If a numeric argument is supplied, the |
| mark is set to that position. |
| |
| `exchange-point-and-mark (C-x C-x)' |
| Swap the point with the mark. The current cursor position is set |
| to the saved position, and the old cursor position is saved as the |
| mark. |
| |
| `character-search (C-])' |
| A character is read and point is moved to the next occurrence of |
| that character. A negative count searches for previous |
| occurrences. |
| |
| `character-search-backward (M-C-])' |
| A character is read and point is moved to the previous occurrence |
| of that character. A negative count searches for subsequent |
| occurrences. |
| |
| `skip-csi-sequence ()' |
| Read enough characters to consume a multi-key sequence such as |
| those defined for keys like Home and End. Such sequences begin |
| with a Control Sequence Indicator (CSI), usually ESC-[. If this |
| sequence is bound to "\e[", keys producing such sequences will |
| have no effect unless explicitly bound to a readline command, |
| instead of inserting stray characters into the editing buffer. |
| This is unbound by default, but usually bound to ESC-[. |
| |
| `insert-comment (M-#)' |
| Without a numeric argument, the value of the `comment-begin' |
| variable is inserted at the beginning of the current line. If a |
| numeric argument is supplied, this command acts as a toggle: if |
| the characters at the beginning of the line do not match the value |
| of `comment-begin', the value is inserted, otherwise the |
| characters in `comment-begin' are deleted from the beginning of |
| the line. In either case, the line is accepted as if a newline |
| had been typed. |
| |
| `dump-functions ()' |
| Print all of the functions and their key bindings to the Readline |
| output stream. If a numeric argument is supplied, the output is |
| formatted in such a way that it can be made part of an INPUTRC |
| file. This command is unbound by default. |
| |
| `dump-variables ()' |
| Print all of the settable variables and their values to the |
| Readline output stream. If a numeric argument is supplied, the |
| output is formatted in such a way that it can be made part of an |
| INPUTRC file. This command is unbound by default. |
| |
| `dump-macros ()' |
| Print all of the Readline key sequences bound to macros and the |
| strings they output. If a numeric argument is supplied, the |
| output is formatted in such a way that it can be made part of an |
| INPUTRC file. This command is unbound by default. |
| |
| `emacs-editing-mode (C-e)' |
| When in `vi' command mode, this causes a switch to `emacs' editing |
| mode. |
| |
| `vi-editing-mode (M-C-j)' |
| When in `emacs' editing mode, this causes a switch to `vi' editing |
| mode. |
| |
| |
| |
| File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing |
| |
| 32.5 Readline vi Mode |
| ===================== |
| |
| While the Readline library does not have a full set of `vi' editing |
| functions, it does contain enough to allow simple editing of the line. |
| The Readline `vi' mode behaves as specified in the POSIX standard. |
| |
| In order to switch interactively between `emacs' and `vi' editing |
| modes, use the command `M-C-j' (bound to emacs-editing-mode when in |
| `vi' mode and to vi-editing-mode in `emacs' mode). The Readline |
| default is `emacs' mode. |
| |
| When you enter a line in `vi' mode, you are already placed in |
| `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches |
| you into `command' mode, where you can edit the text of the line with |
| the standard `vi' movement keys, move to previous history lines with |
| `k' and subsequent lines with `j', and so forth. |
| |
| |
| File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top |
| |
| 33 Using History Interactively |
| ****************************** |
| |
| This chapter describes how to use the GNU History Library interactively, |
| from a user's standpoint. It should be considered a user's guide. For |
| information on using the GNU History Library in your own programs, |
| *note Programming with GNU History: (history)Programming with GNU |
| History. |
| |
| * Menu: |
| |
| * History Interaction:: What it feels like using History as a user. |
| |
| |
| File: gdb.info, Node: History Interaction, Up: Using History Interactively |
| |
| 33.1 History Expansion |
| ====================== |
| |
| The History library provides a history expansion feature that is similar |
| to the history expansion provided by `csh'. This section describes the |
| syntax used to manipulate the history information. |
| |
| History expansions introduce words from the history list into the |
| input stream, making it easy to repeat commands, insert the arguments |
| to a previous command into the current input line, or fix errors in |
| previous commands quickly. |
| |
| History expansion takes place in two parts. The first is to |
| determine which line from the history list should be used during |
| substitution. The second is to select portions of that line for |
| inclusion into the current one. The line selected from the history is |
| called the "event", and the portions of that line that are acted upon |
| are called "words". Various "modifiers" are available to manipulate |
| the selected words. The line is broken into words in the same fashion |
| that Bash does, so that several words surrounded by quotes are |
| considered one word. History expansions are introduced by the |
| appearance of the history expansion character, which is `!' by default. |
| |
| * Menu: |
| |
| * Event Designators:: How to specify which history line to use. |
| * Word Designators:: Specifying which words are of interest. |
| * Modifiers:: Modifying the results of substitution. |
| |
| |
| File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction |
| |
| 33.1.1 Event Designators |
| ------------------------ |
| |
| An event designator is a reference to a command line entry in the |
| history list. Unless the reference is absolute, events are relative to |
| the current position in the history list. |
| |
| `!' |
| Start a history substitution, except when followed by a space, tab, |
| the end of the line, or `='. |
| |
| `!N' |
| Refer to command line N. |
| |
| `!-N' |
| Refer to the command N lines back. |
| |
| `!!' |
| Refer to the previous command. This is a synonym for `!-1'. |
| |
| `!STRING' |
| Refer to the most recent command preceding the current position in |
| the history list starting with STRING. |
| |
| `!?STRING[?]' |
| Refer to the most recent command preceding the current position in |
| the history list containing STRING. The trailing `?' may be |
| omitted if the STRING is followed immediately by a newline. |
| |
| `^STRING1^STRING2^' |
| Quick Substitution. Repeat the last command, replacing STRING1 |
| with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. |
| |
| `!#' |
| The entire command line typed so far. |
| |
| |
| |
| File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction |
| |
| 33.1.2 Word Designators |
| ----------------------- |
| |
| Word designators are used to select desired words from the event. A |
| `:' separates the event specification from the word designator. It may |
| be omitted if the word designator begins with a `^', `$', `*', `-', or |
| `%'. Words are numbered from the beginning of the line, with the first |
| word being denoted by 0 (zero). Words are inserted into the current |
| line separated by single spaces. |
| |
| For example, |
| |
| `!!' |
| designates the preceding command. When you type this, the |
| preceding command is repeated in toto. |
| |
| `!!:$' |
| designates the last argument of the preceding command. This may be |
| shortened to `!$'. |
| |
| `!fi:2' |
| designates the second argument of the most recent command starting |
| with the letters `fi'. |
| |
| Here are the word designators: |
| |
| `0 (zero)' |
| The `0'th word. For many applications, this is the command word. |
| |
| `N' |
| The Nth word. |
| |
| `^' |
| The first argument; that is, word 1. |
| |
| `$' |
| The last argument. |
| |
| `%' |
| The word matched by the most recent `?STRING?' search. |
| |
| `X-Y' |
| A range of words; `-Y' abbreviates `0-Y'. |
| |
| `*' |
| All of the words, except the `0'th. This is a synonym for `1-$'. |
| It is not an error to use `*' if there is just one word in the |
| event; the empty string is returned in that case. |
| |
| `X*' |
| Abbreviates `X-$' |
| |
| `X-' |
| Abbreviates `X-$' like `X*', but omits the last word. |
| |
| |
| If a word designator is supplied without an event specification, the |
| previous command is used as the event. |
| |
| |
| File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction |
| |
| 33.1.3 Modifiers |
| ---------------- |
| |
| After the optional word designator, you can add a sequence of one or |
| more of the following modifiers, each preceded by a `:'. |
| |
| `h' |
| Remove a trailing pathname component, leaving only the head. |
| |
| `t' |
| Remove all leading pathname components, leaving the tail. |
| |
| `r' |
| Remove a trailing suffix of the form `.SUFFIX', leaving the |
| basename. |
| |
| `e' |
| Remove all but the trailing suffix. |
| |
| `p' |
| Print the new command but do not execute it. |
| |
| `s/OLD/NEW/' |
| Substitute NEW for the first occurrence of OLD in the event line. |
| Any delimiter may be used in place of `/'. The delimiter may be |
| quoted in OLD and NEW with a single backslash. If `&' appears in |
| NEW, it is replaced by OLD. A single backslash will quote the |
| `&'. The final delimiter is optional if it is the last character |
| on the input line. |
| |
| `&' |
| Repeat the previous substitution. |
| |
| `g' |
| `a' |
| Cause changes to be applied over the entire event line. Used in |
| conjunction with `s', as in `gs/OLD/NEW/', or with `&'. |
| |
| `G' |
| Apply the following `s' modifier once to each word in the event. |
| |
| |
| |
| File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top |
| |
| Appendix A In Memoriam |
| ********************** |
| |
| The GDB project mourns the loss of the following long-time contributors: |
| |
| `Fred Fish' |
| Fred was a long-standing contributor to GDB (1991-2006), and to |
| Free Software in general. Outside of GDB, he was known in the |
| Amiga world for his series of Fish Disks, and the GeekGadget |
| project. |
| |
| `Michael Snyder' |
| Michael was one of the Global Maintainers of the GDB project, with |
| contributions recorded as early as 1996, until 2011. In addition |
| to his day to day participation, he was a large driving force |
| behind adding Reverse Debugging to GDB. |
| |
| Beyond their technical contributions to the project, they were also |
| enjoyable members of the Free Software Community. We will miss them. |
| |
| |
| File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top |
| |
| Appendix B Formatting Documentation |
| *********************************** |
| |
| The GDB 4 release includes an already-formatted reference card, ready |
| for printing with PostScript or Ghostscript, in the `gdb' subdirectory |
| of the main source directory(1). If you can use PostScript or |
| Ghostscript with your printer, you can print the reference card |
| immediately with `refcard.ps'. |
| |
| The release also includes the source for the reference card. You |
| can format it, using TeX, by typing: |
| |
| make refcard.dvi |
| |
| The GDB reference card is designed to print in "landscape" mode on |
| US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches |
| high. You will need to specify this form of printing as an option to |
| your DVI output program. |
| |
| All the documentation for GDB comes as part of the machine-readable |
| distribution. The documentation is written in Texinfo format, which is |
| a documentation system that uses a single source file to produce both |
| on-line information and a printed manual. You can use one of the Info |
| formatting commands to create the on-line version of the documentation |
| 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.5/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' |
| program, available as part of the GNU Texinfo distribution. |
| |
| If you want to format these Info files yourself, you need one of the |
| 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.5', in the case of version 7.5), you can make |
| the Info file by typing: |
| |
| cd gdb |
| make gdb.info |
| |
| If you want to typeset and print copies of this manual, you need TeX, |
| a program to print its DVI output files, and `texinfo.tex', the Texinfo |
| definitions file. |
| |
| TeX is a typesetting program; it does not print files directly, but |
| produces output files called DVI files. To print a typeset document, |
| you need a program to print DVI files. If your system has TeX |
| installed, chances are it has such a program. The precise command to |
| use depends on your system; `lpr -d' is common; another (for PostScript |
| devices) is `dvips'. The DVI print command may require a file name |
| without any extension or a `.dvi' extension. |
| |
| TeX also requires a macro definitions file called `texinfo.tex'. |
| This file tells TeX how to typeset a document written in Texinfo |
| format. On its own, TeX cannot either read or typeset a Texinfo file. |
| `texinfo.tex' is distributed with GDB and is located in the |
| `gdb-VERSION-NUMBER/texinfo' directory. |
| |
| 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.5/gdb') and type: |
| |
| make gdb.dvi |
| |
| Then give `gdb.dvi' to your DVI printing program. |
| |
| ---------- Footnotes ---------- |
| |
| (1) In `gdb-7.5/gdb/refcard.ps' of the version 7.5 release. |
| |
| |
| File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top |
| |
| Appendix C Installing GDB |
| ************************* |
| |
| * Menu: |
| |
| * Requirements:: Requirements for building GDB |
| * Running Configure:: Invoking the GDB `configure' script |
| * Separate Objdir:: Compiling GDB in another directory |
| * Config Names:: Specifying names for hosts and targets |
| * Configure Options:: Summary of options for configure |
| * System-wide configuration:: Having a system-wide init file |
| |
| |
| File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB |
| |
| C.1 Requirements for Building GDB |
| ================================= |
| |
| Building GDB requires various tools and packages to be available. |
| Other packages will be used only if they are found. |
| |
| Tools/Packages Necessary for Building GDB |
| ========================================= |
| |
| ISO C90 compiler |
| GDB is written in ISO C90. It should be buildable with any |
| working C90 compiler, e.g. GCC. |
| |
| |
| Tools/Packages Optional for Building GDB |
| ======================================== |
| |
| Expat |
| GDB can use the Expat XML parsing library. This library may be |
| included with your operating system distribution; if it is not, you |
| can get the latest version from `http://expat.sourceforge.net'. |
| The `configure' script will search for this library in several |
| standard locations; if it is installed in an unusual path, you can |
| use the `--with-libexpat-prefix' option to specify its location. |
| |
| Expat is used for: |
| |
| * Remote protocol memory maps (*note Memory Map Format::) |
| |
| * Target descriptions (*note Target Descriptions::) |
| |
| * Remote shared library lists (*Note Library List Format::, or |
| alternatively *note Library List Format for SVR4 Targets::) |
| |
| * MS-Windows shared libraries (*note Shared Libraries::) |
| |
| * Traceframe info (*note Traceframe Info Format::) |
| |
| zlib |
| GDB will use the `zlib' library, if available, to read compressed |
| debug sections. Some linkers, such as GNU gold, are capable of |
| producing binaries with compressed debug sections. If GDB is |
| compiled with `zlib', it will be able to read the debug |
| information in such binaries. |
| |
| The `zlib' library is likely included with your operating system |
| distribution; if it is not, you can get the latest version from |
| `http://zlib.net'. |
| |
| iconv |
| GDB's features related to character sets (*note Character Sets::) |
| require a functioning `iconv' implementation. If you are on a GNU |
| system, then this is provided by the GNU C Library. Some other |
| systems also provide a working `iconv'. |
| |
| If GDB is using the `iconv' program which is installed in a |
| non-standard place, you will need to tell GDB where to find it. |
| This is done with `--with-iconv-bin' which specifies the directory |
| that contains the `iconv' program. |
| |
| On systems without `iconv', you can install GNU Libiconv. If you |
| have previously installed Libiconv, you can use the |
| `--with-libiconv-prefix' option to configure. |
| |
| GDB's top-level `configure' and `Makefile' will arrange to build |
| Libiconv if a directory named `libiconv' appears in the top-most |
| source directory. If Libiconv is built this way, and if the |
| operating system does not provide a suitable `iconv' |
| implementation, then the just-built library will automatically be |
| used by GDB. One easy way to set this up is to download GNU |
| Libiconv, unpack it, and then rename the directory holding the |
| Libiconv source code to `libiconv'. |
| |