OLD | NEW |
1 This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo. | 1 This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo. |
2 | 2 |
3 INFO-DIR-SECTION Software development | 3 INFO-DIR-SECTION Software development |
4 START-INFO-DIR-ENTRY | 4 START-INFO-DIR-ENTRY |
5 * Gdb: (gdb). The GNU debugger. | 5 * Gdb: (gdb). The GNU debugger. |
6 END-INFO-DIR-ENTRY | 6 END-INFO-DIR-ENTRY |
7 | 7 |
8 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, | 8 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
9 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, | 9 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
10 2010 Free Software Foundation, Inc. | 10 2010 2011, 2012 Free Software Foundation, Inc. |
11 | 11 |
12 Permission is granted to copy, distribute and/or modify this document | 12 Permission is granted to copy, distribute and/or modify this document |
13 under the terms of the GNU Free Documentation License, Version 1.3 or | 13 under the terms of the GNU Free Documentation License, Version 1.3 or |
14 any later version published by the Free Software Foundation; with the | 14 any later version published by the Free Software Foundation; with the |
15 Invariant Sections being "Free Software" and "Free Software Needs Free | 15 Invariant Sections being "Free Software" and "Free Software Needs Free |
16 Documentation", with the Front-Cover Texts being "A GNU Manual," and | 16 Documentation", with the Front-Cover Texts being "A GNU Manual," and |
17 with the Back-Cover Texts as in (a) below. | 17 with the Back-Cover Texts as in (a) below. |
18 | 18 |
19 (a) The FSF's Back-Cover Text is: "You are free to copy and modify | 19 (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
20 this GNU Manual. Buying copies from GNU Press supports the FSF in | 20 this GNU Manual. Buying copies from GNU Press supports the FSF in |
21 developing GNU and promoting software freedom." | 21 developing GNU and promoting software freedom." |
22 | 22 |
23 This file documents the GNU debugger GDB. | 23 This file documents the GNU debugger GDB. |
24 | 24 |
25 This is the Tenth Edition, of `Debugging with GDB: the GNU | 25 This is the Tenth Edition, of `Debugging with GDB: the GNU |
26 Source-Level Debugger' for GDB (GDB) Version 7.4.1. | 26 Source-Level Debugger' for GDB (GDB) Version 7.5.1. |
27 | 27 |
28 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, | 28 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
29 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, | 29 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
30 2010 Free Software Foundation, Inc. | 30 2010 2011, 2012 Free Software Foundation, Inc. |
31 | 31 |
32 Permission is granted to copy, distribute and/or modify this document | 32 Permission is granted to copy, distribute and/or modify this document |
33 under the terms of the GNU Free Documentation License, Version 1.3 or | 33 under the terms of the GNU Free Documentation License, Version 1.3 or |
34 any later version published by the Free Software Foundation; with the | 34 any later version published by the Free Software Foundation; with the |
35 Invariant Sections being "Free Software" and "Free Software Needs Free | 35 Invariant Sections being "Free Software" and "Free Software Needs Free |
36 Documentation", with the Front-Cover Texts being "A GNU Manual," and | 36 Documentation", with the Front-Cover Texts being "A GNU Manual," and |
37 with the Back-Cover Texts as in (a) below. | 37 with the Back-Cover Texts as in (a) below. |
38 | 38 |
39 (a) The FSF's Back-Cover Text is: "You are free to copy and modify | 39 (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
40 this GNU Manual. Buying copies from GNU Press supports the FSF in | 40 this GNU Manual. Buying copies from GNU Press supports the FSF in |
41 developing GNU and promoting software freedom." | 41 developing GNU and promoting software freedom." |
42 | 42 |
43 | 43 |
| 44 File: gdb.info, Node: objfile-gdb.py file, Next: dotdebug_gdb_scripts section,
Up: Python Auto-loading |
| 45 |
| 46 23.2.3.1 The `OBJFILE-gdb.py' file |
| 47 .................................. |
| 48 |
| 49 When a new object file is read, GDB looks for a file named |
| 50 `OBJFILE-gdb.py' (we call it SCRIPT-NAME below), where OBJFILE is the |
| 51 object file's real name, formed by ensuring that the file name is |
| 52 absolute, following all symlinks, and resolving `.' and `..' |
| 53 components. If this file exists and is readable, GDB will evaluate it |
| 54 as a Python script. |
| 55 |
| 56 If this file does not exist, then GDB will look for SCRIPT-NAME file |
| 57 in all of the directories as specified below. |
| 58 |
| 59 Note that loading of this script file also requires accordingly |
| 60 configured `auto-load safe-path' (*note Auto-loading safe path::). |
| 61 |
| 62 For object files using `.exe' suffix GDB tries to load first the |
| 63 scripts normally according to its `.exe' filename. But if no scripts |
| 64 are found GDB also tries script filenames matching the object file |
| 65 without its `.exe' suffix. This `.exe' stripping is case insensitive |
| 66 and it is attempted on any platform. This makes the script filenames |
| 67 compatible between Unix and MS-Windows hosts. |
| 68 |
| 69 `set auto-load scripts-directory [DIRECTORIES]' |
| 70 Control GDB auto-loaded scripts location. Multiple directory |
| 71 entries may be delimited by the host platform path separator in use |
| 72 (`:' on Unix, `;' on MS-Windows and MS-DOS). |
| 73 |
| 74 Each entry here needs to be covered also by the security setting |
| 75 `set auto-load safe-path' (*note set auto-load safe-path::). |
| 76 |
| 77 This variable defaults to `$debugdir:$datadir/auto-load'. The |
| 78 default `set auto-load safe-path' value can be also overriden by |
| 79 GDB configuration option `--with-auto-load-dir'. |
| 80 |
| 81 Any reference to `$debugdir' will get replaced by |
| 82 DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any |
| 83 reference to `$datadir' will get replaced by DATA-DIRECTORY which |
| 84 is determined at GDB startup (*note Data Files::). `$debugdir' and |
| 85 `$datadir' must be placed as a directory component -- either alone |
| 86 or delimited by `/' or `\' directory separators, depending on the |
| 87 host platform. |
| 88 |
| 89 The list of directories uses path separator (`:' on GNU and Unix |
| 90 systems, `;' on MS-Windows and MS-DOS) to separate directories, |
| 91 similarly to the `PATH' environment variable. |
| 92 |
| 93 `show auto-load scripts-directory' |
| 94 Show GDB auto-loaded scripts location. |
| 95 |
| 96 GDB does not track which files it has already auto-loaded this way. |
| 97 GDB will load the associated script every time the corresponding |
| 98 OBJFILE is opened. So your `-gdb.py' file should be careful to avoid |
| 99 errors if it is evaluated more than once. |
| 100 |
| 101 |
| 102 File: gdb.info, Node: dotdebug_gdb_scripts section, Next: Which flavor to choo
se?, Prev: objfile-gdb.py file, Up: Python Auto-loading |
| 103 |
| 104 23.2.3.2 The `.debug_gdb_scripts' section |
| 105 ......................................... |
| 106 |
| 107 For systems using file formats like ELF and COFF, when GDB loads a new |
| 108 object file it will look for a special section named |
| 109 `.debug_gdb_scripts'. If this section exists, its contents is a list |
| 110 of names of scripts to load. |
| 111 |
| 112 GDB will look for each specified script file first in the current |
| 113 directory and then along the source search path (*note Specifying |
| 114 Source Directories: Source Path.), except that `$cdir' is not searched, |
| 115 since the compilation directory is not relevant to scripts. |
| 116 |
| 117 Entries can be placed in section `.debug_gdb_scripts' with, for |
| 118 example, this GCC macro: |
| 119 |
| 120 /* Note: The "MS" section flags are to remove duplicates. */ |
| 121 #define DEFINE_GDB_SCRIPT(script_name) \ |
| 122 asm("\ |
| 123 .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ |
| 124 .byte 1\n\ |
| 125 .asciz \"" script_name "\"\n\ |
| 126 .popsection \n\ |
| 127 "); |
| 128 |
| 129 Then one can reference the macro in a header or source file like this: |
| 130 |
| 131 DEFINE_GDB_SCRIPT ("my-app-scripts.py") |
| 132 |
| 133 The script name may include directories if desired. |
| 134 |
| 135 Note that loading of this script file also requires accordingly |
| 136 configured `auto-load safe-path' (*note Auto-loading safe path::). |
| 137 |
| 138 If the macro is put in a header, any application or library using |
| 139 this header will get a reference to the specified script. |
| 140 |
| 141 |
| 142 File: gdb.info, Node: Which flavor to choose?, Prev: dotdebug_gdb_scripts sect
ion, Up: Python Auto-loading |
| 143 |
| 144 23.2.3.3 Which flavor to choose? |
| 145 ................................ |
| 146 |
| 147 Given the multiple ways of auto-loading Python scripts, it might not |
| 148 always be clear which one to choose. This section provides some |
| 149 guidance. |
| 150 |
| 151 Benefits of the `-gdb.py' way: |
| 152 |
| 153 * Can be used with file formats that don't support multiple sections. |
| 154 |
| 155 * Ease of finding scripts for public libraries. |
| 156 |
| 157 Scripts specified in the `.debug_gdb_scripts' section are searched |
| 158 for in the source search path. For publicly installed libraries, |
| 159 e.g., `libstdc++', there typically isn't a source directory in |
| 160 which to find the script. |
| 161 |
| 162 * Doesn't require source code additions. |
| 163 |
| 164 Benefits of the `.debug_gdb_scripts' way: |
| 165 |
| 166 * Works with static linking. |
| 167 |
| 168 Scripts for libraries done the `-gdb.py' way require an objfile to |
| 169 trigger their loading. When an application is statically linked |
| 170 the only objfile available is the executable, and it is cumbersome |
| 171 to attach all the scripts from all the input libraries to the |
| 172 executable's `-gdb.py' script. |
| 173 |
| 174 * Works with classes that are entirely inlined. |
| 175 |
| 176 Some classes can be entirely inlined, and thus there may not be an |
| 177 associated shared library to attach a `-gdb.py' script to. |
| 178 |
| 179 * Scripts needn't be copied out of the source tree. |
| 180 |
| 181 In some circumstances, apps can be built out of large collections |
| 182 of internal libraries, and the build infrastructure necessary to |
| 183 install the `-gdb.py' scripts in a place where GDB can find them is |
| 184 cumbersome. It may be easier to specify the scripts in the |
| 185 `.debug_gdb_scripts' section as relative paths, and add a path to |
| 186 the top of the source tree to the source search path. |
| 187 |
| 188 |
| 189 File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python |
| 190 |
| 191 23.2.4 Python modules |
| 192 --------------------- |
| 193 |
| 194 GDB comes with several modules to assist writing Python code. |
| 195 |
| 196 * Menu: |
| 197 |
| 198 * gdb.printing:: Building and registering pretty-printers. |
| 199 * gdb.types:: Utilities for working with types. |
| 200 * gdb.prompt:: Utilities for prompt value substitution. |
| 201 |
| 202 |
| 203 File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules |
| 204 |
| 205 23.2.4.1 gdb.printing |
| 206 ..................... |
| 207 |
| 208 This module provides a collection of utilities for working with |
| 209 pretty-printers. |
| 210 |
| 211 `PrettyPrinter (NAME, SUBPRINTERS=None)' |
| 212 This class specifies the API that makes `info pretty-printer', |
| 213 `enable pretty-printer' and `disable pretty-printer' work. |
| 214 Pretty-printers should generally inherit from this class. |
| 215 |
| 216 `SubPrettyPrinter (NAME)' |
| 217 For printers that handle multiple types, this class specifies the |
| 218 corresponding API for the subprinters. |
| 219 |
| 220 `RegexpCollectionPrettyPrinter (NAME)' |
| 221 Utility class for handling multiple printers, all recognized via |
| 222 regular expressions. *Note Writing a Pretty-Printer::, for an |
| 223 example. |
| 224 |
| 225 `FlagEnumerationPrinter (NAME)' |
| 226 A pretty-printer which handles printing of `enum' values. Unlike |
| 227 GDB's built-in `enum' printing, this printer attempts to work |
| 228 properly when there is some overlap between the enumeration |
| 229 constants. NAME is the name of the printer and also the name of |
| 230 the `enum' type to look up. |
| 231 |
| 232 `register_pretty_printer (OBJ, PRINTER, REPLACE=False)' |
| 233 Register PRINTER with the pretty-printer list of OBJ. If REPLACE |
| 234 is `True' then any existing copy of the printer is replaced. |
| 235 Otherwise a `RuntimeError' exception is raised if a printer with |
| 236 the same name already exists. |
| 237 |
| 238 |
| 239 File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: P
ython modules |
| 240 |
| 241 23.2.4.2 gdb.types |
| 242 .................. |
| 243 |
| 244 This module provides a collection of utilities for working with |
| 245 `gdb.Types' objects. |
| 246 |
| 247 `get_basic_type (TYPE)' |
| 248 Return TYPE with const and volatile qualifiers stripped, and with |
| 249 typedefs and C++ references converted to the underlying type. |
| 250 |
| 251 C++ example: |
| 252 |
| 253 typedef const int const_int; |
| 254 const_int foo (3); |
| 255 const_int& foo_ref (foo); |
| 256 int main () { return 0; } |
| 257 |
| 258 Then in gdb: |
| 259 |
| 260 (gdb) start |
| 261 (gdb) python import gdb.types |
| 262 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref") |
| 263 (gdb) python print gdb.types.get_basic_type(foo_ref.type) |
| 264 int |
| 265 |
| 266 `has_field (TYPE, FIELD)' |
| 267 Return `True' if TYPE, assumed to be a type with fields (e.g., a |
| 268 structure or union), has field FIELD. |
| 269 |
| 270 `make_enum_dict (ENUM_TYPE)' |
| 271 Return a Python `dictionary' type produced from ENUM_TYPE. |
| 272 |
| 273 `deep_items (TYPE)' |
| 274 Returns a Python iterator similar to the standard |
| 275 `gdb.Type.iteritems' method, except that the iterator returned by |
| 276 `deep_items' will recursively traverse anonymous struct or union |
| 277 fields. For example: |
| 278 |
| 279 struct A |
| 280 { |
| 281 int a; |
| 282 union { |
| 283 int b0; |
| 284 int b1; |
| 285 }; |
| 286 }; |
| 287 |
| 288 Then in GDB: |
| 289 (gdb) python import gdb.types |
| 290 (gdb) python struct_a = gdb.lookup_type("struct A") |
| 291 (gdb) python print struct_a.keys () |
| 292 {['a', '']} |
| 293 (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)] |
| 294 {['a', 'b0', 'b1']} |
| 295 |
| 296 |
| 297 |
| 298 File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules |
| 299 |
| 300 23.2.4.3 gdb.prompt |
| 301 ................... |
| 302 |
| 303 This module provides a method for prompt value-substitution. |
| 304 |
| 305 `substitute_prompt (STRING)' |
| 306 Return STRING with escape sequences substituted by values. Some |
| 307 escape sequences take arguments. You can specify arguments inside |
| 308 "{}" immediately following the escape sequence. |
| 309 |
| 310 The escape sequences you can pass to this function are: |
| 311 |
| 312 `\\' |
| 313 Substitute a backslash. |
| 314 |
| 315 `\e' |
| 316 Substitute an ESC character. |
| 317 |
| 318 `\f' |
| 319 Substitute the selected frame; an argument names a frame |
| 320 parameter. |
| 321 |
| 322 `\n' |
| 323 Substitute a newline. |
| 324 |
| 325 `\p' |
| 326 Substitute a parameter's value; the argument names the |
| 327 parameter. |
| 328 |
| 329 `\r' |
| 330 Substitute a carriage return. |
| 331 |
| 332 `\t' |
| 333 Substitute the selected thread; an argument names a thread |
| 334 parameter. |
| 335 |
| 336 `\v' |
| 337 Substitute the version of GDB. |
| 338 |
| 339 `\w' |
| 340 Substitute the current working directory. |
| 341 |
| 342 `\[' |
| 343 Begin a sequence of non-printing characters. These sequences |
| 344 are typically used with the ESC character, and are not |
| 345 counted in the string length. Example: |
| 346 "\[\e[0;34m\](gdb)\[\e[0m\]" will return a blue-colored |
| 347 "(gdb)" prompt where the length is five. |
| 348 |
| 349 `\]' |
| 350 End a sequence of non-printing characters. |
| 351 |
| 352 For example: |
| 353 |
| 354 substitute_prompt (``frame: \f, |
| 355 print arguments: \p{print frame-arguments}'') |
| 356 |
| 357 will return the string: |
| 358 |
| 359 |
| 360 "frame: main, print arguments: scalars" |
| 361 |
| 362 |
| 363 File: gdb.info, Node: Aliases, Prev: Python, Up: Extending GDB |
| 364 |
| 365 23.3 Creating new spellings of existing commands |
| 366 ================================================ |
| 367 |
| 368 It is often useful to define alternate spellings of existing commands. |
| 369 For example, if a new GDB command defined in Python has a long name to |
| 370 type, it is handy to have an abbreviated version of it that involves |
| 371 less typing. |
| 372 |
| 373 GDB itself uses aliases. For example `s' is an alias of the `step' |
| 374 command even though it is otherwise an ambiguous abbreviation of other |
| 375 commands like `set' and `show'. |
| 376 |
| 377 Aliases are also used to provide shortened or more common versions |
| 378 of multi-word commands. For example, GDB provides the `tty' alias of |
| 379 the `set inferior-tty' command. |
| 380 |
| 381 You can define a new alias with the `alias' command. |
| 382 |
| 383 `alias [-a] [--] ALIAS = COMMAND' |
| 384 |
| 385 ALIAS specifies the name of the new alias. Each word of ALIAS must |
| 386 consist of letters, numbers, dashes and underscores. |
| 387 |
| 388 COMMAND specifies the name of an existing command that is being |
| 389 aliased. |
| 390 |
| 391 The `-a' option specifies that the new alias is an abbreviation of |
| 392 the command. Abbreviations are not shown in command lists displayed by |
| 393 the `help' command. |
| 394 |
| 395 The `--' option specifies the end of options, and is useful when |
| 396 ALIAS begins with a dash. |
| 397 |
| 398 Here is a simple example showing how to make an abbreviation of a |
| 399 command so that there is less to type. Suppose you were tired of |
| 400 typing `disas', the current shortest unambiguous abbreviation of the |
| 401 `disassemble' command and you wanted an even shorter version named `di'. |
| 402 The following will accomplish this. |
| 403 |
| 404 (gdb) alias -a di = disas |
| 405 |
| 406 Note that aliases are different from user-defined commands. With a |
| 407 user-defined command, you also need to write documentation for it with |
| 408 the `document' command. An alias automatically picks up the |
| 409 documentation of the existing command. |
| 410 |
| 411 Here is an example where we make `elms' an abbreviation of |
| 412 `elements' in the `set print elements' command. This is to show that |
| 413 you can make an abbreviation of any part of a command. |
| 414 |
| 415 (gdb) alias -a set print elms = set print elements |
| 416 (gdb) alias -a show print elms = show print elements |
| 417 (gdb) set p elms 20 |
| 418 (gdb) show p elms |
| 419 Limit on string chars or array elements to print is 200. |
| 420 |
| 421 Note that if you are defining an alias of a `set' command, and you |
| 422 want to have an alias for the corresponding `show' command, then you |
| 423 need to define the latter separately. |
| 424 |
| 425 Unambiguously abbreviated commands are allowed in COMMAND and ALIAS, |
| 426 just as they are normally. |
| 427 |
| 428 (gdb) alias -a set pr elms = set p ele |
| 429 |
| 430 Finally, here is an example showing the creation of a one word alias |
| 431 for a more complex command. This creates alias `spe' of the command |
| 432 `set print elements'. |
| 433 |
| 434 (gdb) alias spe = set print elements |
| 435 (gdb) spe 20 |
| 436 |
| 437 |
| 438 File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top |
| 439 |
| 440 24 Command Interpreters |
| 441 *********************** |
| 442 |
| 443 GDB supports multiple command interpreters, and some command |
| 444 infrastructure to allow users or user interface writers to switch |
| 445 between interpreters or run commands in other interpreters. |
| 446 |
| 447 GDB currently supports two command interpreters, the console |
| 448 interpreter (sometimes called the command-line interpreter or CLI) and |
| 449 the machine interface interpreter (or GDB/MI). This manual describes |
| 450 both of these interfaces in great detail. |
| 451 |
| 452 By default, GDB will start with the console interpreter. However, |
| 453 the user may choose to start GDB with another interpreter by specifying |
| 454 the `-i' or `--interpreter' startup options. Defined interpreters |
| 455 include: |
| 456 |
| 457 `console' |
| 458 The traditional console or command-line interpreter. This is the |
| 459 most often used interpreter with GDB. With no interpreter |
| 460 specified at runtime, GDB will use this interpreter. |
| 461 |
| 462 `mi' |
| 463 The newest GDB/MI interface (currently `mi2'). Used primarily by |
| 464 programs wishing to use GDB as a backend for a debugger GUI or an |
| 465 IDE. For more information, see *Note The GDB/MI Interface: GDB/MI. |
| 466 |
| 467 `mi2' |
| 468 The current GDB/MI interface. |
| 469 |
| 470 `mi1' |
| 471 The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. |
| 472 |
| 473 |
| 474 The interpreter being used by GDB may not be dynamically switched at |
| 475 runtime. Although possible, this could lead to a very precarious |
| 476 situation. Consider an IDE using GDB/MI. If a user enters the command |
| 477 "interpreter-set console" in a console view, GDB would switch to using |
| 478 the console interpreter, rendering the IDE inoperable! |
| 479 |
| 480 Although you may only choose a single interpreter at startup, you |
| 481 may execute commands in any interpreter from the current interpreter |
| 482 using the appropriate command. If you are running the console |
| 483 interpreter, simply use the `interpreter-exec' command: |
| 484 |
| 485 interpreter-exec mi "-data-list-register-names" |
| 486 |
| 487 GDB/MI has a similar command, although it is only available in |
| 488 versions of GDB which support GDB/MI version 2 (or greater). |
| 489 |
| 490 |
| 491 File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top |
| 492 |
| 493 25 GDB Text User Interface |
| 494 ************************** |
| 495 |
| 496 * Menu: |
| 497 |
| 498 * TUI Overview:: TUI overview |
| 499 * TUI Keys:: TUI key bindings |
| 500 * TUI Single Key Mode:: TUI single key mode |
| 501 * TUI Commands:: TUI-specific commands |
| 502 * TUI Configuration:: TUI configuration variables |
| 503 |
| 504 The GDB Text User Interface (TUI) is a terminal interface which uses |
| 505 the `curses' library to show the source file, the assembly output, the |
| 506 program registers and GDB commands in separate text windows. The TUI |
| 507 mode is supported only on platforms where a suitable version of the |
| 508 `curses' library is available. |
| 509 |
| 510 The TUI mode is enabled by default when you invoke GDB as `gdb -tui'. |
| 511 You can also switch in and out of TUI mode while GDB runs by using |
| 512 various TUI commands and key bindings, such as `C-x C-a'. *Note TUI |
| 513 Key Bindings: TUI Keys. |
| 514 |
| 515 |
| 516 File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI |
| 517 |
| 518 25.1 TUI Overview |
| 519 ================= |
| 520 |
| 521 In TUI mode, GDB can display several text windows: |
| 522 |
| 523 _command_ |
| 524 This window is the GDB command window with the GDB prompt and the |
| 525 GDB output. The GDB input is still managed using readline. |
| 526 |
| 527 _source_ |
| 528 The source window shows the source file of the program. The |
| 529 current line and active breakpoints are displayed in this window. |
| 530 |
| 531 _assembly_ |
| 532 The assembly window shows the disassembly output of the program. |
| 533 |
| 534 _register_ |
| 535 This window shows the processor registers. Registers are |
| 536 highlighted when their values change. |
| 537 |
| 538 The source and assembly windows show the current program position by |
| 539 highlighting the current line and marking it with a `>' marker. |
| 540 Breakpoints are indicated with two markers. The first marker indicates |
| 541 the breakpoint type: |
| 542 |
| 543 `B' |
| 544 Breakpoint which was hit at least once. |
| 545 |
| 546 `b' |
| 547 Breakpoint which was never hit. |
| 548 |
| 549 `H' |
| 550 Hardware breakpoint which was hit at least once. |
| 551 |
| 552 `h' |
| 553 Hardware breakpoint which was never hit. |
| 554 |
| 555 The second marker indicates whether the breakpoint is enabled or not: |
| 556 |
| 557 `+' |
| 558 Breakpoint is enabled. |
| 559 |
| 560 `-' |
| 561 Breakpoint is disabled. |
| 562 |
| 563 The source, assembly and register windows are updated when the |
| 564 current thread changes, when the frame changes, or when the program |
| 565 counter changes. |
| 566 |
| 567 These windows are not all visible at the same time. The command |
| 568 window is always visible. The others can be arranged in several |
| 569 layouts: |
| 570 |
| 571 * source only, |
| 572 |
| 573 * assembly only, |
| 574 |
| 575 * source and assembly, |
| 576 |
| 577 * source and registers, or |
| 578 |
| 579 * assembly and registers. |
| 580 |
| 581 A status line above the command window shows the following |
| 582 information: |
| 583 |
| 584 _target_ |
| 585 Indicates the current GDB target. (*note Specifying a Debugging |
| 586 Target: Targets.). |
| 587 |
| 588 _process_ |
| 589 Gives the current process or thread number. When no process is |
| 590 being debugged, this field is set to `No process'. |
| 591 |
| 592 _function_ |
| 593 Gives the current function name for the selected frame. The name |
| 594 is demangled if demangling is turned on (*note Print Settings::). |
| 595 When there is no symbol corresponding to the current program |
| 596 counter, the string `??' is displayed. |
| 597 |
| 598 _line_ |
| 599 Indicates the current line number for the selected frame. When |
| 600 the current line number is not known, the string `??' is displayed. |
| 601 |
| 602 _pc_ |
| 603 Indicates the current program counter address. |
| 604 |
| 605 |
| 606 File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview
, Up: TUI |
| 607 |
| 608 25.2 TUI Key Bindings |
| 609 ===================== |
| 610 |
| 611 The TUI installs several key bindings in the readline keymaps (*note |
| 612 Command Line Editing::). The following key bindings are installed for |
| 613 both TUI mode and the GDB standard mode. |
| 614 |
| 615 `C-x C-a' |
| 616 `C-x a' |
| 617 `C-x A' |
| 618 Enter or leave the TUI mode. When leaving the TUI mode, the |
| 619 curses window management stops and GDB operates using its standard |
| 620 mode, writing on the terminal directly. When reentering the TUI |
| 621 mode, control is given back to the curses windows. The screen is |
| 622 then refreshed. |
| 623 |
| 624 `C-x 1' |
| 625 Use a TUI layout with only one window. The layout will either be |
| 626 `source' or `assembly'. When the TUI mode is not active, it will |
| 627 switch to the TUI mode. |
| 628 |
| 629 Think of this key binding as the Emacs `C-x 1' binding. |
| 630 |
| 631 `C-x 2' |
| 632 Use a TUI layout with at least two windows. When the current |
| 633 layout already has two windows, the next layout with two windows |
| 634 is used. When a new layout is chosen, one window will always be |
| 635 common to the previous layout and the new one. |
| 636 |
| 637 Think of it as the Emacs `C-x 2' binding. |
| 638 |
| 639 `C-x o' |
| 640 Change the active window. The TUI associates several key bindings |
| 641 (like scrolling and arrow keys) with the active window. This |
| 642 command gives the focus to the next TUI window. |
| 643 |
| 644 Think of it as the Emacs `C-x o' binding. |
| 645 |
| 646 `C-x s' |
| 647 Switch in and out of the TUI SingleKey mode that binds single keys |
| 648 to GDB commands (*note TUI Single Key Mode::). |
| 649 |
| 650 The following key bindings only work in the TUI mode: |
| 651 |
| 652 <PgUp> |
| 653 Scroll the active window one page up. |
| 654 |
| 655 <PgDn> |
| 656 Scroll the active window one page down. |
| 657 |
| 658 <Up> |
| 659 Scroll the active window one line up. |
| 660 |
| 661 <Down> |
| 662 Scroll the active window one line down. |
| 663 |
| 664 <Left> |
| 665 Scroll the active window one column left. |
| 666 |
| 667 <Right> |
| 668 Scroll the active window one column right. |
| 669 |
| 670 `C-L' |
| 671 Refresh the screen. |
| 672 |
| 673 Because the arrow keys scroll the active window in the TUI mode, they |
| 674 are not available for their normal use by readline unless the command |
| 675 window has the focus. When another window is active, you must use |
| 676 other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to |
| 677 control the command window. |
| 678 |
| 679 |
| 680 File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys
, Up: TUI |
| 681 |
| 682 25.3 TUI Single Key Mode |
| 683 ======================== |
| 684 |
| 685 The TUI also provides a "SingleKey" mode, which binds several |
| 686 frequently used GDB commands to single keys. Type `C-x s' to switch |
| 687 into this mode, where the following key bindings are used: |
| 688 |
| 689 `c' |
| 690 continue |
| 691 |
| 692 `d' |
| 693 down |
| 694 |
| 695 `f' |
| 696 finish |
| 697 |
| 698 `n' |
| 699 next |
| 700 |
| 701 `q' |
| 702 exit the SingleKey mode. |
| 703 |
| 704 `r' |
| 705 run |
| 706 |
| 707 `s' |
| 708 step |
| 709 |
| 710 `u' |
| 711 up |
| 712 |
| 713 `v' |
| 714 info locals |
| 715 |
| 716 `w' |
| 717 where |
| 718 |
| 719 Other keys temporarily switch to the GDB command prompt. The key |
| 720 that was pressed is inserted in the editing buffer so that it is |
| 721 possible to type most GDB commands without interaction with the TUI |
| 722 SingleKey mode. Once the command is entered the TUI SingleKey mode is |
| 723 restored. The only way to permanently leave this mode is by typing `q' |
| 724 or `C-x s'. |
| 725 |
| 726 |
| 727 File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single
Key Mode, Up: TUI |
| 728 |
| 729 25.4 TUI-specific Commands |
| 730 ========================== |
| 731 |
| 732 The TUI has specific commands to control the text windows. These |
| 733 commands are always available, even when GDB is not in the TUI mode. |
| 734 When GDB is in the standard mode, most of these commands will |
| 735 automatically switch to the TUI mode. |
| 736 |
| 737 Note that if GDB's `stdout' is not connected to a terminal, or GDB |
| 738 has been started with the machine interface interpreter (*note The |
| 739 GDB/MI Interface: GDB/MI.), most of these commands will fail with an |
| 740 error, because it would not be possible or desirable to enable curses |
| 741 window management. |
| 742 |
| 743 `info win' |
| 744 List and give the size of all displayed windows. |
| 745 |
| 746 `layout next' |
| 747 Display the next layout. |
| 748 |
| 749 `layout prev' |
| 750 Display the previous layout. |
| 751 |
| 752 `layout src' |
| 753 Display the source window only. |
| 754 |
| 755 `layout asm' |
| 756 Display the assembly window only. |
| 757 |
| 758 `layout split' |
| 759 Display the source and assembly window. |
| 760 |
| 761 `layout regs' |
| 762 Display the register window together with the source or assembly |
| 763 window. |
| 764 |
| 765 `focus next' |
| 766 Make the next window active for scrolling. |
| 767 |
| 768 `focus prev' |
| 769 Make the previous window active for scrolling. |
| 770 |
| 771 `focus src' |
| 772 Make the source window active for scrolling. |
| 773 |
| 774 `focus asm' |
| 775 Make the assembly window active for scrolling. |
| 776 |
| 777 `focus regs' |
| 778 Make the register window active for scrolling. |
| 779 |
| 780 `focus cmd' |
| 781 Make the command window active for scrolling. |
| 782 |
| 783 `refresh' |
| 784 Refresh the screen. This is similar to typing `C-L'. |
| 785 |
| 786 `tui reg float' |
| 787 Show the floating point registers in the register window. |
| 788 |
| 789 `tui reg general' |
| 790 Show the general registers in the register window. |
| 791 |
| 792 `tui reg next' |
| 793 Show the next register group. The list of register groups as well |
| 794 as their order is target specific. The predefined register groups |
| 795 are the following: `general', `float', `system', `vector', `all', |
| 796 `save', `restore'. |
| 797 |
| 798 `tui reg system' |
| 799 Show the system registers in the register window. |
| 800 |
| 801 `update' |
| 802 Update the source window and the current execution point. |
| 803 |
| 804 `winheight NAME +COUNT' |
| 805 `winheight NAME -COUNT' |
| 806 Change the height of the window NAME by COUNT lines. Positive |
| 807 counts increase the height, while negative counts decrease it. |
| 808 |
| 809 `tabset NCHARS' |
| 810 Set the width of tab stops to be NCHARS characters. |
| 811 |
| 812 |
| 813 File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI |
| 814 |
| 815 25.5 TUI Configuration Variables |
| 816 ================================ |
| 817 |
| 818 Several configuration variables control the appearance of TUI windows. |
| 819 |
| 820 `set tui border-kind KIND' |
| 821 Select the border appearance for the source, assembly and register |
| 822 windows. The possible values are the following: |
| 823 `space' |
| 824 Use a space character to draw the border. |
| 825 |
| 826 `ascii' |
| 827 Use ASCII characters `+', `-' and `|' to draw the border. |
| 828 |
| 829 `acs' |
| 830 Use the Alternate Character Set to draw the border. The |
| 831 border is drawn using character line graphics if the terminal |
| 832 supports them. |
| 833 |
| 834 `set tui border-mode MODE' |
| 835 `set tui active-border-mode MODE' |
| 836 Select the display attributes for the borders of the inactive |
| 837 windows or the active window. The MODE can be one of the |
| 838 following: |
| 839 `normal' |
| 840 Use normal attributes to display the border. |
| 841 |
| 842 `standout' |
| 843 Use standout mode. |
| 844 |
| 845 `reverse' |
| 846 Use reverse video mode. |
| 847 |
| 848 `half' |
| 849 Use half bright mode. |
| 850 |
| 851 `half-standout' |
| 852 Use half bright and standout mode. |
| 853 |
| 854 `bold' |
| 855 Use extra bright or bold mode. |
| 856 |
| 857 `bold-standout' |
| 858 Use extra bright or bold and standout mode. |
| 859 |
| 860 |
| 861 File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top |
| 862 |
| 863 26 Using GDB under GNU Emacs |
| 864 **************************** |
| 865 |
| 866 A special interface allows you to use GNU Emacs to view (and edit) the |
| 867 source files for the program you are debugging with GDB. |
| 868 |
| 869 To use this interface, use the command `M-x gdb' in Emacs. Give the |
| 870 executable file you want to debug as an argument. This command starts |
| 871 GDB as a subprocess of Emacs, with input and output through a newly |
| 872 created Emacs buffer. |
| 873 |
| 874 Running GDB under Emacs can be just like running GDB normally except |
| 875 for two things: |
| 876 |
| 877 * All "terminal" input and output goes through an Emacs buffer, |
| 878 called the GUD buffer. |
| 879 |
| 880 This applies both to GDB commands and their output, and to the |
| 881 input and output done by the program you are debugging. |
| 882 |
| 883 This is useful because it means that you can copy the text of |
| 884 previous commands and input them again; you can even use parts of |
| 885 the output in this way. |
| 886 |
| 887 All the facilities of Emacs' Shell mode are available for |
| 888 interacting with your program. In particular, you can send |
| 889 signals the usual way--for example, `C-c C-c' for an interrupt, |
| 890 `C-c C-z' for a stop. |
| 891 |
| 892 * GDB displays source code through Emacs. |
| 893 |
| 894 Each time GDB displays a stack frame, Emacs automatically finds the |
| 895 source file for that frame and puts an arrow (`=>') at the left |
| 896 margin of the current line. Emacs uses a separate buffer for |
| 897 source display, and splits the screen to show both your GDB session |
| 898 and the source. |
| 899 |
| 900 Explicit GDB `list' or search commands still produce output as |
| 901 usual, but you probably have no reason to use them from Emacs. |
| 902 |
| 903 We call this "text command mode". Emacs 22.1, and later, also uses |
| 904 a graphical mode, enabled by default, which provides further buffers |
| 905 that can control the execution and describe the state of your program. |
| 906 *Note GDB Graphical Interface: (Emacs)GDB Graphical Interface. |
| 907 |
| 908 If you specify an absolute file name when prompted for the `M-x gdb' |
| 909 argument, then Emacs sets your current working directory to where your |
| 910 program resides. If you only specify the file name, then Emacs sets |
| 911 your current working directory to the directory associated with the |
| 912 previous buffer. In this case, GDB may find your program by searching |
| 913 your environment's `PATH' variable, but on some operating systems it |
| 914 might not find the source. So, although the GDB input and output |
| 915 session proceeds normally, the auxiliary buffer does not display the |
| 916 current source and line of execution. |
| 917 |
| 918 The initial working directory of GDB is printed on the top line of |
| 919 the GUD buffer and this serves as a default for the commands that |
| 920 specify files for GDB to operate on. *Note Commands to Specify Files: |
| 921 Files. |
| 922 |
| 923 By default, `M-x gdb' calls the program called `gdb'. If you need |
| 924 to call GDB by a different name (for example, if you keep several |
| 925 configurations around, with different names) you can customize the |
| 926 Emacs variable `gud-gdb-command-name' to run the one you want. |
| 927 |
| 928 In the GUD buffer, you can use these special Emacs commands in |
| 929 addition to the standard Shell mode commands: |
| 930 |
| 931 `C-h m' |
| 932 Describe the features of Emacs' GUD Mode. |
| 933 |
| 934 `C-c C-s' |
| 935 Execute to another source line, like the GDB `step' command; also |
| 936 update the display window to show the current file and location. |
| 937 |
| 938 `C-c C-n' |
| 939 Execute to next source line in this function, skipping all function |
| 940 calls, like the GDB `next' command. Then update the display window |
| 941 to show the current file and location. |
| 942 |
| 943 `C-c C-i' |
| 944 Execute one instruction, like the GDB `stepi' command; update |
| 945 display window accordingly. |
| 946 |
| 947 `C-c C-f' |
| 948 Execute until exit from the selected stack frame, like the GDB |
| 949 `finish' command. |
| 950 |
| 951 `C-c C-r' |
| 952 Continue execution of your program, like the GDB `continue' |
| 953 command. |
| 954 |
| 955 `C-c <' |
| 956 Go up the number of frames indicated by the numeric argument |
| 957 (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' |
| 958 command. |
| 959 |
| 960 `C-c >' |
| 961 Go down the number of frames indicated by the numeric argument, |
| 962 like the GDB `down' command. |
| 963 |
| 964 In any source file, the Emacs command `C-x <SPC>' (`gud-break') |
| 965 tells GDB to set a breakpoint on the source line point is on. |
| 966 |
| 967 In text command mode, if you type `M-x speedbar', Emacs displays a |
| 968 separate frame which shows a backtrace when the GUD buffer is current. |
| 969 Move point to any frame in the stack and type <RET> to make it become |
| 970 the current frame and display the associated source in the source |
| 971 buffer. Alternatively, click `Mouse-2' to make the selected frame |
| 972 become the current one. In graphical mode, the speedbar displays watch |
| 973 expressions. |
| 974 |
| 975 If you accidentally delete the source-display buffer, an easy way to |
| 976 get it back is to type the command `f' in the GDB buffer, to request a |
| 977 frame display; when you run under Emacs, this recreates the source |
| 978 buffer if necessary to show you the context of the current frame. |
| 979 |
| 980 The source files displayed in Emacs are in ordinary Emacs buffers |
| 981 which are visiting the source files in the usual way. You can edit the |
| 982 files with these buffers if you wish; but keep in mind that GDB |
| 983 communicates with Emacs in terms of line numbers. If you add or delete |
| 984 lines from the text, the line numbers that GDB knows cease to |
| 985 correspond properly with the code. |
| 986 |
| 987 A more detailed description of Emacs' interaction with GDB is given |
| 988 in the Emacs manual (*note Debuggers: (Emacs)Debuggers.). |
| 989 |
| 990 |
| 991 File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top |
| 992 |
| 993 27 The GDB/MI Interface |
| 994 *********************** |
| 995 |
| 996 Function and Purpose |
| 997 ==================== |
| 998 |
| 999 GDB/MI is a line based machine oriented text interface to GDB and is |
| 1000 activated by specifying using the `--interpreter' command line option |
| 1001 (*note Mode Options::). It is specifically intended to support the |
| 1002 development of systems which use the debugger as just one small |
| 1003 component of a larger system. |
| 1004 |
| 1005 This chapter is a specification of the GDB/MI interface. It is |
| 1006 written in the form of a reference manual. |
| 1007 |
| 1008 Note that GDB/MI is still under construction, so some of the |
| 1009 features described below are incomplete and subject to change (*note |
| 1010 GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.). |
| 1011 |
| 1012 Notation and Terminology |
| 1013 ======================== |
| 1014 |
| 1015 This chapter uses the following notation: |
| 1016 |
| 1017 * `|' separates two alternatives. |
| 1018 |
| 1019 * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or |
| 1020 may not be given. |
| 1021 |
| 1022 * `( GROUP )*' means that GROUP inside the parentheses may repeat |
| 1023 zero or more times. |
| 1024 |
| 1025 * `( GROUP )+' means that GROUP inside the parentheses may repeat |
| 1026 one or more times. |
| 1027 |
| 1028 * `"STRING"' means a literal STRING. |
| 1029 |
| 1030 * Menu: |
| 1031 |
| 1032 * GDB/MI General Design:: |
| 1033 * GDB/MI Command Syntax:: |
| 1034 * GDB/MI Compatibility with CLI:: |
| 1035 * GDB/MI Development and Front Ends:: |
| 1036 * GDB/MI Output Records:: |
| 1037 * GDB/MI Simple Examples:: |
| 1038 * GDB/MI Command Description Format:: |
| 1039 * GDB/MI Breakpoint Commands:: |
| 1040 * GDB/MI Program Context:: |
| 1041 * GDB/MI Thread Commands:: |
| 1042 * GDB/MI Ada Tasking Commands:: |
| 1043 * GDB/MI Program Execution:: |
| 1044 * GDB/MI Stack Manipulation:: |
| 1045 * GDB/MI Variable Objects:: |
| 1046 * GDB/MI Data Manipulation:: |
| 1047 * GDB/MI Tracepoint Commands:: |
| 1048 * GDB/MI Symbol Query:: |
| 1049 * GDB/MI File Commands:: |
| 1050 * GDB/MI Target Manipulation:: |
| 1051 * GDB/MI File Transfer Commands:: |
| 1052 * GDB/MI Miscellaneous Commands:: |
| 1053 |
| 1054 |
| 1055 File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up:
GDB/MI |
| 1056 |
| 1057 27.1 GDB/MI General Design |
| 1058 ========================== |
| 1059 |
| 1060 Interaction of a GDB/MI frontend with GDB involves three |
| 1061 parts--commands sent to GDB, responses to those commands and |
| 1062 notifications. Each command results in exactly one response, |
| 1063 indicating either successful completion of the command, or an error. |
| 1064 For the commands that do not resume the target, the response contains |
| 1065 the requested information. For the commands that resume the target, the |
| 1066 response only indicates whether the target was successfully resumed. |
| 1067 Notifications is the mechanism for reporting changes in the state of the |
| 1068 target, or in GDB state, that cannot conveniently be associated with a |
| 1069 command and reported as part of that command response. |
| 1070 |
| 1071 The important examples of notifications are: |
| 1072 * Exec notifications. These are used to report changes in target |
| 1073 state--when a target is resumed, or stopped. It would not be |
| 1074 feasible to include this information in response of resuming |
| 1075 commands, because one resume commands can result in multiple |
| 1076 events in different threads. Also, quite some time may pass |
| 1077 before any event happens in the target, while a frontend needs to |
| 1078 know whether the resuming command itself was successfully executed. |
| 1079 |
| 1080 * Console output, and status notifications. Console output |
| 1081 notifications are used to report output of CLI commands, as well as |
| 1082 diagnostics for other commands. Status notifications are used to |
| 1083 report the progress of a long-running operation. Naturally, |
| 1084 including this information in command response would mean no |
| 1085 output is produced until the command is finished, which is |
| 1086 undesirable. |
| 1087 |
| 1088 * General notifications. Commands may have various side effects on |
| 1089 the GDB or target state beyond their official purpose. For |
| 1090 example, a command may change the selected thread. Although such |
| 1091 changes can be included in command response, using notification |
| 1092 allows for more orthogonal frontend design. |
| 1093 |
| 1094 |
| 1095 There's no guarantee that whenever an MI command reports an error, |
| 1096 GDB or the target are in any specific state, and especially, the state |
| 1097 is not reverted to the state before the MI command was processed. |
| 1098 Therefore, whenever an MI command results in an error, we recommend |
| 1099 that the frontend refreshes all the information shown in the user |
| 1100 interface. |
| 1101 |
| 1102 * Menu: |
| 1103 |
| 1104 * Context management:: |
| 1105 * Asynchronous and non-stop modes:: |
| 1106 * Thread groups:: |
| 1107 |
| 1108 |
| 1109 File: gdb.info, Node: Context management, Next: Asynchronous and non-stop mode
s, Up: GDB/MI General Design |
| 1110 |
| 1111 27.1.1 Context management |
| 1112 ------------------------- |
| 1113 |
| 1114 In most cases when GDB accesses the target, this access is done in |
| 1115 context of a specific thread and frame (*note Frames::). Often, even |
| 1116 when accessing global data, the target requires that a thread be |
| 1117 specified. The CLI interface maintains the selected thread and frame, |
| 1118 and supplies them to target on each command. This is convenient, |
| 1119 because a command line user would not want to specify that information |
| 1120 explicitly on each command, and because user interacts with GDB via a |
| 1121 single terminal, so no confusion is possible as to what thread and |
| 1122 frame are the current ones. |
| 1123 |
| 1124 In the case of MI, the concept of selected thread and frame is less |
| 1125 useful. First, a frontend can easily remember this information itself. |
| 1126 Second, a graphical frontend can have more than one window, each one |
| 1127 used for debugging a different thread, and the frontend might want to |
| 1128 access additional threads for internal purposes. This increases the |
| 1129 risk that by relying on implicitly selected thread, the frontend may be |
| 1130 operating on a wrong one. Therefore, each MI command should explicitly |
| 1131 specify which thread and frame to operate on. To make it possible, |
| 1132 each MI command accepts the `--thread' and `--frame' options, the value |
| 1133 to each is GDB identifier for thread and frame to operate on. |
| 1134 |
| 1135 Usually, each top-level window in a frontend allows the user to |
| 1136 select a thread and a frame, and remembers the user selection for |
| 1137 further operations. However, in some cases GDB may suggest that the |
| 1138 current thread be changed. For example, when stopping on a breakpoint |
| 1139 it is reasonable to switch to the thread where breakpoint is hit. For |
| 1140 another example, if the user issues the CLI `thread' command via the |
| 1141 frontend, it is desirable to change the frontend's selected thread to |
| 1142 the one specified by user. GDB communicates the suggestion to change |
| 1143 current thread using the `=thread-selected' notification. No such |
| 1144 notification is available for the selected frame at the moment. |
| 1145 |
| 1146 Note that historically, MI shares the selected thread with CLI, so |
| 1147 frontends used the `-thread-select' to execute commands in the right |
| 1148 context. However, getting this to work right is cumbersome. The |
| 1149 simplest way is for frontend to emit `-thread-select' command before |
| 1150 every command. This doubles the number of commands that need to be |
| 1151 sent. The alternative approach is to suppress `-thread-select' if the |
| 1152 selected thread in GDB is supposed to be identical to the thread the |
| 1153 frontend wants to operate on. However, getting this optimization right |
| 1154 can be tricky. In particular, if the frontend sends several commands |
| 1155 to GDB, and one of the commands changes the selected thread, then the |
| 1156 behaviour of subsequent commands will change. So, a frontend should |
| 1157 either wait for response from such problematic commands, or explicitly |
| 1158 add `-thread-select' for all subsequent commands. No frontend is known |
| 1159 to do this exactly right, so it is suggested to just always pass the |
| 1160 `--thread' and `--frame' options. |
| 1161 |
| 1162 |
| 1163 File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, P
rev: Context management, Up: GDB/MI General Design |
| 1164 |
| 1165 27.1.2 Asynchronous command execution and non-stop mode |
| 1166 ------------------------------------------------------- |
| 1167 |
| 1168 On some targets, GDB is capable of processing MI commands even while |
| 1169 the target is running. This is called "asynchronous command execution" |
| 1170 (*note Background Execution::). The frontend may specify a preferrence |
| 1171 for asynchronous execution using the `-gdb-set target-async 1' command, |
| 1172 which should be emitted before either running the executable or |
| 1173 attaching to the target. After the frontend has started the executable |
| 1174 or attached to the target, it can find if asynchronous execution is |
| 1175 enabled using the `-list-target-features' command. |
| 1176 |
| 1177 Even if GDB can accept a command while target is running, many |
| 1178 commands that access the target do not work when the target is running. |
| 1179 Therefore, asynchronous command execution is most useful when combined |
| 1180 with non-stop mode (*note Non-Stop Mode::). Then, it is possible to |
| 1181 examine the state of one thread, while other threads are running. |
| 1182 |
| 1183 When a given thread is running, MI commands that try to access the |
| 1184 target in the context of that thread may not work, or may work only on |
| 1185 some targets. In particular, commands that try to operate on thread's |
| 1186 stack will not work, on any target. Commands that read memory, or |
| 1187 modify breakpoints, may work or not work, depending on the target. Note |
| 1188 that even commands that operate on global state, such as `print', |
| 1189 `set', and breakpoint commands, still access the target in the context |
| 1190 of a specific thread, so frontend should try to find a stopped thread |
| 1191 and perform the operation on that thread (using the `--thread' option). |
| 1192 |
| 1193 Which commands will work in the context of a running thread is |
| 1194 highly target dependent. However, the two commands `-exec-interrupt', |
| 1195 to stop a thread, and `-thread-info', to find the state of a thread, |
| 1196 will always work. |
| 1197 |
| 1198 |
| 1199 File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, U
p: GDB/MI General Design |
| 1200 |
| 1201 27.1.3 Thread groups |
| 1202 -------------------- |
| 1203 |
| 1204 GDB may be used to debug several processes at the same time. On some |
| 1205 platfroms, GDB may support debugging of several hardware systems, each |
| 1206 one having several cores with several different processes running on |
| 1207 each core. This section describes the MI mechanism to support such |
| 1208 debugging scenarios. |
| 1209 |
| 1210 The key observation is that regardless of the structure of the |
| 1211 target, MI can have a global list of threads, because most commands that |
| 1212 accept the `--thread' option do not need to know what process that |
| 1213 thread belongs to. Therefore, it is not necessary to introduce neither |
| 1214 additional `--process' option, nor an notion of the current process in |
| 1215 the MI interface. The only strictly new feature that is required is |
| 1216 the ability to find how the threads are grouped into processes. |
| 1217 |
| 1218 To allow the user to discover such grouping, and to support arbitrary |
| 1219 hierarchy of machines/cores/processes, MI introduces the concept of a |
| 1220 "thread group". Thread group is a collection of threads and other |
| 1221 thread groups. A thread group always has a string identifier, a type, |
| 1222 and may have additional attributes specific to the type. A new |
| 1223 command, `-list-thread-groups', returns the list of top-level thread |
| 1224 groups, which correspond to processes that GDB is debugging at the |
| 1225 moment. By passing an identifier of a thread group to the |
| 1226 `-list-thread-groups' command, it is possible to obtain the members of |
| 1227 specific thread group. |
| 1228 |
| 1229 To allow the user to easily discover processes, and other objects, he |
| 1230 wishes to debug, a concept of "available thread group" is introduced. |
| 1231 Available thread group is an thread group that GDB is not debugging, |
| 1232 but that can be attached to, using the `-target-attach' command. The |
| 1233 list of available top-level thread groups can be obtained using |
| 1234 `-list-thread-groups --available'. In general, the content of a thread |
| 1235 group may be only retrieved only after attaching to that thread group. |
| 1236 |
| 1237 Thread groups are related to inferiors (*note Inferiors and |
| 1238 Programs::). Each inferior corresponds to a thread group of a special |
| 1239 type `process', and some additional operations are permitted on such |
| 1240 thread groups. |
| 1241 |
| 1242 |
| 1243 File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with C
LI, Prev: GDB/MI General Design, Up: GDB/MI |
| 1244 |
| 1245 27.2 GDB/MI Command Syntax |
| 1246 ========================== |
| 1247 |
| 1248 * Menu: |
| 1249 |
| 1250 * GDB/MI Input Syntax:: |
| 1251 * GDB/MI Output Syntax:: |
| 1252 |
| 1253 |
| 1254 File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GD
B/MI Command Syntax |
| 1255 |
| 1256 27.2.1 GDB/MI Input Syntax |
| 1257 -------------------------- |
| 1258 |
| 1259 `COMMAND ==>' |
| 1260 `CLI-COMMAND | MI-COMMAND' |
| 1261 |
| 1262 `CLI-COMMAND ==>' |
| 1263 `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB |
| 1264 CLI command. |
| 1265 |
| 1266 `MI-COMMAND ==>' |
| 1267 `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " |
| 1268 PARAMETER )* NL' |
| 1269 |
| 1270 `TOKEN ==>' |
| 1271 "any sequence of digits" |
| 1272 |
| 1273 `OPTION ==>' |
| 1274 `"-" PARAMETER [ " " PARAMETER ]' |
| 1275 |
| 1276 `PARAMETER ==>' |
| 1277 `NON-BLANK-SEQUENCE | C-STRING' |
| 1278 |
| 1279 `OPERATION ==>' |
| 1280 _any of the operations described in this chapter_ |
| 1281 |
| 1282 `NON-BLANK-SEQUENCE ==>' |
| 1283 _anything, provided it doesn't contain special characters such as |
| 1284 "-", NL, """ and of course " "_ |
| 1285 |
| 1286 `C-STRING ==>' |
| 1287 `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' |
| 1288 |
| 1289 `NL ==>' |
| 1290 `CR | CR-LF' |
| 1291 |
| 1292 Notes: |
| 1293 |
| 1294 * The CLI commands are still handled by the MI interpreter; their |
| 1295 output is described below. |
| 1296 |
| 1297 * The `TOKEN', when present, is passed back when the command |
| 1298 finishes. |
| 1299 |
| 1300 * Some MI commands accept optional arguments as part of the parameter |
| 1301 list. Each option is identified by a leading `-' (dash) and may be |
| 1302 followed by an optional argument parameter. Options occur first |
| 1303 in the parameter list and can be delimited from normal parameters |
| 1304 using `--' (this is useful when some parameters begin with a dash). |
| 1305 |
| 1306 Pragmatics: |
| 1307 |
| 1308 * We want easy access to the existing CLI syntax (for debugging). |
| 1309 |
| 1310 * We want it to be easy to spot a MI operation. |
| 1311 |
| 1312 |
44 File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GD
B/MI Command Syntax | 1313 File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GD
B/MI Command Syntax |
45 | 1314 |
46 27.2.2 GDB/MI Output Syntax | 1315 27.2.2 GDB/MI Output Syntax |
47 --------------------------- | 1316 --------------------------- |
48 | 1317 |
49 The output from GDB/MI consists of zero or more out-of-band records | 1318 The output from GDB/MI consists of zero or more out-of-band records |
50 followed, optionally, by a single result record. This result record is | 1319 followed, optionally, by a single result record. This result record is |
51 for the most recent command. The sequence of output records is | 1320 for the most recent command. The sequence of output records is |
52 terminated by `(gdb)'. | 1321 terminated by `(gdb)'. |
53 | 1322 |
(...skipping 302 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
356 The inferior exited. | 1625 The inferior exited. |
357 | 1626 |
358 `exited-normally' | 1627 `exited-normally' |
359 The inferior exited normally. | 1628 The inferior exited normally. |
360 | 1629 |
361 `signal-received' | 1630 `signal-received' |
362 A signal was received by the inferior. | 1631 A signal was received by the inferior. |
363 | 1632 |
364 `solib-event' | 1633 `solib-event' |
365 The inferior has stopped due to a library being loaded or | 1634 The inferior has stopped due to a library being loaded or |
366 unloaded. This can only happen when `stop-on-solib-events' | 1635 unloaded. This can happen when `stop-on-solib-events' (*note |
367 (*note Files::) is set. | 1636 Files::) is set or when a `catch load' or `catch unload' |
| 1637 catchpoint is in use (*note Set Catchpoints::). |
368 | 1638 |
369 `fork' | 1639 `fork' |
370 The inferior has forked. This is reported when `catch fork' | 1640 The inferior has forked. This is reported when `catch fork' |
371 (*note Set Catchpoints::) has been used. | 1641 (*note Set Catchpoints::) has been used. |
372 | 1642 |
373 `vfork' | 1643 `vfork' |
374 The inferior has vforked. This is reported in when `catch | 1644 The inferior has vforked. This is reported in when `catch |
375 vfork' (*note Set Catchpoints::) has been used. | 1645 vfork' (*note Set Catchpoints::) has been used. |
376 | 1646 |
377 `syscall-entry' | 1647 `syscall-entry' |
(...skipping 536 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
914 N.A. | 2184 N.A. |
915 | 2185 |
916 The `-break-insert' Command | 2186 The `-break-insert' Command |
917 --------------------------- | 2187 --------------------------- |
918 | 2188 |
919 Synopsis | 2189 Synopsis |
920 ........ | 2190 ........ |
921 | 2191 |
922 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] | 2192 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] |
923 [ -c CONDITION ] [ -i IGNORE-COUNT ] | 2193 [ -c CONDITION ] [ -i IGNORE-COUNT ] |
924 [ -p THREAD ] [ LOCATION ] | 2194 [ -p THREAD-ID ] [ LOCATION ] |
925 | 2195 |
926 If specified, LOCATION, can be one of: | 2196 If specified, LOCATION, can be one of: |
927 | 2197 |
928 * function | 2198 * function |
929 | 2199 |
930 * filename:linenum | 2200 * filename:linenum |
931 | 2201 |
932 * filename:function | 2202 * filename:function |
933 | 2203 |
934 * *address | 2204 * *address |
935 | 2205 |
936 The possible optional parameters of this command are: | 2206 The possible optional parameters of this command are: |
937 | 2207 |
938 `-t' | 2208 `-t' |
939 Insert a temporary breakpoint. | 2209 Insert a temporary breakpoint. |
940 | 2210 |
941 `-h' | 2211 `-h' |
942 Insert a hardware breakpoint. | 2212 Insert a hardware breakpoint. |
943 | 2213 |
944 `-c CONDITION' | |
945 Make the breakpoint conditional on CONDITION. | |
946 | |
947 `-i IGNORE-COUNT' | |
948 Initialize the IGNORE-COUNT. | |
949 | |
950 `-f' | 2214 `-f' |
951 If LOCATION cannot be parsed (for example if it refers to unknown | 2215 If LOCATION cannot be parsed (for example if it refers to unknown |
952 files or functions), create a pending breakpoint. Without this | 2216 files or functions), create a pending breakpoint. Without this |
953 flag, GDB will report an error, and won't create a breakpoint, if | 2217 flag, GDB will report an error, and won't create a breakpoint, if |
954 LOCATION cannot be parsed. | 2218 LOCATION cannot be parsed. |
955 | 2219 |
956 `-d' | 2220 `-d' |
957 Create a disabled breakpoint. | 2221 Create a disabled breakpoint. |
958 | 2222 |
959 `-a' | 2223 `-a' |
960 Create a tracepoint. *Note Tracepoints::. When this parameter is | 2224 Create a tracepoint. *Note Tracepoints::. When this parameter is |
961 used together with `-h', a fast tracepoint is created. | 2225 used together with `-h', a fast tracepoint is created. |
962 | 2226 |
| 2227 `-c CONDITION' |
| 2228 Make the breakpoint conditional on CONDITION. |
| 2229 |
| 2230 `-i IGNORE-COUNT' |
| 2231 Initialize the IGNORE-COUNT. |
| 2232 |
| 2233 `-p THREAD-ID' |
| 2234 Restrict the breakpoint to the specified THREAD-ID. |
| 2235 |
963 Result | 2236 Result |
964 ...... | 2237 ...... |
965 | 2238 |
966 The result is in the form: | 2239 The result is in the form: |
967 | 2240 |
968 ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep", | 2241 ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep", |
969 enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME", | 2242 enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME", |
970 fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,] | 2243 fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,] |
971 times="TIMES"} | 2244 times="TIMES"} |
972 | 2245 |
973 where NUMBER is the GDB number for this breakpoint, FUNCNAME is the | 2246 where NUMBER is the GDB number for this breakpoint, FUNCNAME is the |
974 name of the function where the breakpoint was inserted, FILENAME is the | 2247 name of the function where the breakpoint was inserted, FILENAME is the |
975 name of the source file which contains this function, LINENO is the | 2248 name of the source file which contains this function, LINENO is the |
976 source line number within that file and TIMES the number of times that | 2249 source line number within that file and TIMES the number of times that |
977 the breakpoint has been hit (always 0 for -break-insert but may be | 2250 the breakpoint has been hit (always 0 for -break-insert but may be |
978 greater for -break-info or -break-list which use the same output). | 2251 greater for -break-info or -break-list which use the same output). |
979 | 2252 |
980 Note: this format is open to change. | 2253 Note: this format is open to change. |
981 | 2254 |
982 GDB Command | 2255 GDB Command |
983 ........... | 2256 ........... |
984 | 2257 |
985 The corresponding GDB commands are `break', `tbreak', `hbreak', | 2258 The corresponding GDB commands are `break', `tbreak', `hbreak', and |
986 `thbreak', and `rbreak'. | 2259 `thbreak'. |
987 | 2260 |
988 Example | 2261 Example |
989 ....... | 2262 ....... |
990 | 2263 |
991 (gdb) | 2264 (gdb) |
992 -break-insert main | 2265 -break-insert main |
993 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", | 2266 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", |
994 fullname="/home/foo/recursive2.c,line="4",times="0"} | 2267 fullname="/home/foo/recursive2.c,line="4",times="0"} |
995 (gdb) | 2268 (gdb) |
996 -break-insert -t foo | 2269 -break-insert -t foo |
997 ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", | 2270 ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", |
998 fullname="/home/foo/recursive2.c,line="11",times="0"} | 2271 fullname="/home/foo/recursive2.c,line="11",times="0"} |
999 (gdb) | 2272 (gdb) |
1000 -break-list | 2273 -break-list |
1001 ^done,BreakpointTable={nr_rows="2",nr_cols="6", | 2274 ^done,BreakpointTable={nr_rows="2",nr_cols="6", |
1002 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, | 2275 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, |
1003 {width="14",alignment="-1",col_name="type",colhdr="Type"}, | 2276 {width="14",alignment="-1",col_name="type",colhdr="Type"}, |
1004 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, | 2277 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, |
1005 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, | 2278 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, |
1006 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, | 2279 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, |
1007 {width="40",alignment="2",col_name="what",colhdr="What"}], | 2280 {width="40",alignment="2",col_name="what",colhdr="What"}], |
1008 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", | 2281 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", |
1009 addr="0x0001072c", func="main",file="recursive2.c", | 2282 addr="0x0001072c", func="main",file="recursive2.c", |
1010 fullname="/home/foo/recursive2.c,"line="4",times="0"}, | 2283 fullname="/home/foo/recursive2.c,"line="4",times="0"}, |
1011 bkpt={number="2",type="breakpoint",disp="del",enabled="y", | 2284 bkpt={number="2",type="breakpoint",disp="del",enabled="y", |
1012 addr="0x00010774",func="foo",file="recursive2.c", | 2285 addr="0x00010774",func="foo",file="recursive2.c", |
1013 fullname="/home/foo/recursive2.c",line="11",times="0"}]} | 2286 fullname="/home/foo/recursive2.c",line="11",times="0"}]} |
1014 (gdb) | 2287 (gdb) |
1015 -break-insert -r foo.* | |
1016 ~int foo(int, int); | |
1017 ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c, | |
1018 "fullname="/home/foo/recursive2.c",line="11",times="0"} | |
1019 (gdb) | |
1020 | 2288 |
1021 The `-break-list' Command | 2289 The `-break-list' Command |
1022 ------------------------- | 2290 ------------------------- |
1023 | 2291 |
1024 Synopsis | 2292 Synopsis |
1025 ........ | 2293 ........ |
1026 | 2294 |
1027 -break-list | 2295 -break-list |
1028 | 2296 |
1029 Displays the list of inserted breakpoints, showing the following | 2297 Displays the list of inserted breakpoints, showing the following |
(...skipping 1606 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2636 necessarily reliable for a dynamic varobj. Instead, you must | 3904 necessarily reliable for a dynamic varobj. Instead, you must |
2637 examine the `has_more' attribute. | 3905 examine the `has_more' attribute. |
2638 | 3906 |
2639 `value' | 3907 `value' |
2640 The varobj's scalar value. For a varobj whose type is some sort of | 3908 The varobj's scalar value. For a varobj whose type is some sort of |
2641 aggregate (e.g., a `struct'), or for a dynamic varobj, this value | 3909 aggregate (e.g., a `struct'), or for a dynamic varobj, this value |
2642 will not be interesting. | 3910 will not be interesting. |
2643 | 3911 |
2644 `type' | 3912 `type' |
2645 The varobj's type. This is a string representation of the type, as | 3913 The varobj's type. This is a string representation of the type, as |
2646 would be printed by the GDB CLI. | 3914 would be printed by the GDB CLI. If `print object' (*note set |
| 3915 print object: Print Settings.) is set to `on', the _actual_ |
| 3916 (derived) type of the object is shown rather than the _declared_ |
| 3917 one. |
2647 | 3918 |
2648 `thread-id' | 3919 `thread-id' |
2649 If a variable object is bound to a specific thread, then this is | 3920 If a variable object is bound to a specific thread, then this is |
2650 the thread's identifier. | 3921 the thread's identifier. |
2651 | 3922 |
2652 `has_more' | 3923 `has_more' |
2653 For a dynamic varobj, this indicates whether there appear to be any | 3924 For a dynamic varobj, this indicates whether there appear to be any |
2654 children available. For a non-dynamic varobj, this will be 0. | 3925 children available. For a non-dynamic varobj, this will be 0. |
2655 | 3926 |
2656 `dynamic' | 3927 `dynamic' |
(...skipping 127 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2784 | 4055 |
2785 A dynamic varobj will not report the access qualifying | 4056 A dynamic varobj will not report the access qualifying |
2786 pseudo-children, regardless of the language. This information is | 4057 pseudo-children, regardless of the language. This information is |
2787 not available at all with a dynamic varobj. | 4058 not available at all with a dynamic varobj. |
2788 | 4059 |
2789 NUMCHILD | 4060 NUMCHILD |
2790 Number of children this child has. For a dynamic varobj, this | 4061 Number of children this child has. For a dynamic varobj, this |
2791 will be 0. | 4062 will be 0. |
2792 | 4063 |
2793 TYPE | 4064 TYPE |
2794 The type of the child. | 4065 The type of the child. If `print object' (*note set print object: |
| 4066 Print Settings.) is set to `on', the _actual_ (derived) type of |
| 4067 the object is shown rather than the _declared_ one. |
2795 | 4068 |
2796 VALUE | 4069 VALUE |
2797 If values were requested, this is the value. | 4070 If values were requested, this is the value. |
2798 | 4071 |
2799 THREAD-ID | 4072 THREAD-ID |
2800 If this variable object is associated with a thread, this is the | 4073 If this variable object is associated with a thread, this is the |
2801 thread id. Otherwise this result is not present. | 4074 thread id. Otherwise this result is not present. |
2802 | 4075 |
2803 FROZEN | 4076 FROZEN |
2804 If the variable object is frozen, this variable will be present | 4077 If the variable object is frozen, this variable will be present |
(...skipping 201 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3006 | 4279 |
3007 In the future new values may be added to this list so the front | 4280 In the future new values may be added to this list so the front |
3008 should be prepared for this possibility. *Note GDB/MI Development | 4281 should be prepared for this possibility. *Note GDB/MI Development |
3009 and Front Ends: GDB/MI Development and Front Ends. | 4282 and Front Ends: GDB/MI Development and Front Ends. |
3010 | 4283 |
3011 `type_changed' | 4284 `type_changed' |
3012 This is only present if the varobj is still valid. If the type | 4285 This is only present if the varobj is still valid. If the type |
3013 changed, then this will be the string `true'; otherwise it will be | 4286 changed, then this will be the string `true'; otherwise it will be |
3014 `false'. | 4287 `false'. |
3015 | 4288 |
| 4289 When a varobj's type changes, its children are also likely to have |
| 4290 become incorrect. Therefore, the varobj's children are |
| 4291 automatically deleted when this attribute is `true'. Also, the |
| 4292 varobj's update range, when set using the `-var-set-update-range' |
| 4293 command, is unset. |
| 4294 |
3016 `new_type' | 4295 `new_type' |
3017 If the varobj's type changed, then this field will be present and | 4296 If the varobj's type changed, then this field will be present and |
3018 will hold the new type. | 4297 will hold the new type. |
3019 | 4298 |
3020 `new_num_children' | 4299 `new_num_children' |
3021 For a dynamic varobj, if the number of children changed, or if the | 4300 For a dynamic varobj, if the number of children changed, or if the |
3022 type changed, this will be the new number of children. | 4301 type changed, this will be the new number of children. |
3023 | 4302 |
3024 The `numchild' field in other varobj responses is generally not | 4303 The `numchild' field in other varobj responses is generally not |
3025 valid for a dynamic varobj - it will show the number of children | 4304 valid for a dynamic varobj - it will show the number of children |
(...skipping 1718 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4744 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2
]}] | 6023 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2
]}] |
4745 -list-thread-groups --available --recurse 1 | 6024 -list-thread-groups --available --recurse 1 |
4746 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[
1,2], | 6025 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[
1,2], |
4747 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, | 6026 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, |
4748 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]}
,..] | 6027 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]}
,..] |
4749 -list-thread-groups --available --recurse 1 17 18 | 6028 -list-thread-groups --available --recurse 1 17 18 |
4750 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1
,2], | 6029 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1
,2], |
4751 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, | 6030 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, |
4752 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},
...] | 6031 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},
...] |
4753 | 6032 |
| 6033 The `-info-os' Command |
| 6034 ---------------------- |
| 6035 |
| 6036 Synopsis |
| 6037 ........ |
| 6038 |
| 6039 -info-os [ TYPE ] |
| 6040 |
| 6041 If no argument is supplied, the command returns a table of available |
| 6042 operating-system-specific information types. If one of these types is |
| 6043 supplied as an argument TYPE, then the command returns a table of data |
| 6044 of that type. |
| 6045 |
| 6046 The types of information available depend on the target operating |
| 6047 system. |
| 6048 |
| 6049 GDB Command |
| 6050 ........... |
| 6051 |
| 6052 The corresponding GDB command is `info os'. |
| 6053 |
| 6054 Example |
| 6055 ....... |
| 6056 |
| 6057 When run on a GNU/Linux system, the output will look something like |
| 6058 this: |
| 6059 |
| 6060 gdb |
| 6061 -info-os |
| 6062 ^done,OSDataTable={nr_rows="9",nr_cols="3", |
| 6063 hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"}, |
| 6064 {width="10",alignment="-1",col_name="col1",colhdr="Description"}, |
| 6065 {width="10",alignment="-1",col_name="col2",colhdr="Title"}], |
| 6066 body=[item={col0="processes",col1="Listing of all processes", |
| 6067 col2="Processes"}, |
| 6068 item={col0="procgroups",col1="Listing of all process groups", |
| 6069 col2="Process groups"}, |
| 6070 item={col0="threads",col1="Listing of all threads", |
| 6071 col2="Threads"}, |
| 6072 item={col0="files",col1="Listing of all file descriptors", |
| 6073 col2="File descriptors"}, |
| 6074 item={col0="sockets",col1="Listing of all internet-domain sockets", |
| 6075 col2="Sockets"}, |
| 6076 item={col0="shm",col1="Listing of all shared-memory regions", |
| 6077 col2="Shared-memory regions"}, |
| 6078 item={col0="semaphores",col1="Listing of all semaphores", |
| 6079 col2="Semaphores"}, |
| 6080 item={col0="msg",col1="Listing of all message queues", |
| 6081 col2="Message queues"}, |
| 6082 item={col0="modules",col1="Listing of all loaded kernel modules", |
| 6083 col2="Kernel modules"}]} |
| 6084 gdb |
| 6085 -info-os processes |
| 6086 ^done,OSDataTable={nr_rows="190",nr_cols="4", |
| 6087 hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"}, |
| 6088 {width="10",alignment="-1",col_name="col1",colhdr="user"}, |
| 6089 {width="10",alignment="-1",col_name="col2",colhdr="command"}, |
| 6090 {width="10",alignment="-1",col_name="col3",colhdr="cores"}], |
| 6091 body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"}, |
| 6092 item={col0="2",col1="root",col2="[kthreadd]",col3="1"}, |
| 6093 item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"}, |
| 6094 ... |
| 6095 item={col0="26446",col1="stan",col2="bash",col3="0"}, |
| 6096 item={col0="28152",col1="stan",col2="bash",col3="1"}]} |
| 6097 (gdb) |
| 6098 |
| 6099 (Note that the MI output here includes a `"Title"' column that does |
| 6100 not appear in command-line `info os'; this column is useful for MI |
| 6101 clients that want to enumerate the types of data, such as in a popup |
| 6102 menu, but is needless clutter on the command line, and `info os' omits |
| 6103 it.) |
| 6104 |
4754 The `-add-inferior' Command | 6105 The `-add-inferior' Command |
4755 --------------------------- | 6106 --------------------------- |
4756 | 6107 |
4757 Synopsis | 6108 Synopsis |
4758 -------- | 6109 -------- |
4759 | 6110 |
4760 -add-inferior | 6111 -add-inferior |
4761 | 6112 |
4762 Creates a new inferior (*note Inferiors and Programs::). The created | 6113 Creates a new inferior (*note Inferiors and Programs::). The created |
4763 inferior is not associated with any executable. Such association may | 6114 inferior is not associated with any executable. Such association may |
(...skipping 395 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5159 line in the file), CHARACTER is the character position within the file | 6510 line in the file), CHARACTER is the character position within the file |
5160 (where 0 is the first character in the file) (for most debug formats | 6511 (where 0 is the first character in the file) (for most debug formats |
5161 this will necessarily point to the beginning of a line), MIDDLE is | 6512 this will necessarily point to the beginning of a line), MIDDLE is |
5162 `middle' if ADDR is in the middle of the line, or `beg' if ADDR is at | 6513 `middle' if ADDR is in the middle of the line, or `beg' if ADDR is at |
5163 the beginning of the line, and ADDR is the address in the target | 6514 the beginning of the line, and ADDR is the address in the target |
5164 program associated with the source which is being displayed. ADDR is | 6515 program associated with the source which is being displayed. ADDR is |
5165 in the form `0x' followed by one or more lowercase hex digits (note | 6516 in the form `0x' followed by one or more lowercase hex digits (note |
5166 that this does not depend on the language). | 6517 that this does not depend on the language). |
5167 | 6518 |
5168 | 6519 |
5169 File: gdb.info, Node: JIT Interface, Next: GDB Bugs, Prev: Annotations, Up:
Top | 6520 File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotation
s, Up: Top |
5170 | 6521 |
5171 29 JIT Compilation Interface | 6522 29 JIT Compilation Interface |
5172 **************************** | 6523 **************************** |
5173 | 6524 |
5174 This chapter documents GDB's "just-in-time" (JIT) compilation | 6525 This chapter documents GDB's "just-in-time" (JIT) compilation |
5175 interface. A JIT compiler is a program or library that generates native | 6526 interface. A JIT compiler is a program or library that generates native |
5176 executable code at runtime and executes it, usually in order to achieve | 6527 executable code at runtime and executes it, usually in order to achieve |
5177 good performance while maintaining platform independence. | 6528 good performance while maintaining platform independence. |
5178 | 6529 |
5179 Programs that use JIT compilation are normally difficult to debug | 6530 Programs that use JIT compilation are normally difficult to debug |
(...skipping 215 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5395 do their job. For `read', these callbacks are passed in a `struct | 6746 do their job. For `read', these callbacks are passed in a `struct |
5396 gdb_symbol_callbacks' and for `unwind' and `get_frame_id', in a `struct | 6747 gdb_symbol_callbacks' and for `unwind' and `get_frame_id', in a `struct |
5397 gdb_unwind_callbacks'. `struct gdb_symbol_callbacks' has callbacks to | 6748 gdb_unwind_callbacks'. `struct gdb_symbol_callbacks' has callbacks to |
5398 create new object files and new symbol tables inside those object | 6749 create new object files and new symbol tables inside those object |
5399 files. `struct gdb_unwind_callbacks' has callbacks to read registers | 6750 files. `struct gdb_unwind_callbacks' has callbacks to read registers |
5400 off the current frame and to write out the values of the registers in | 6751 off the current frame and to write out the values of the registers in |
5401 the previous frame. Both have a callback (`target_read') to read bytes | 6752 the previous frame. Both have a callback (`target_read') to read bytes |
5402 off the target's address space. | 6753 off the target's address space. |
5403 | 6754 |
5404 | 6755 |
5405 File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: JIT Interfa
ce, Up: Top | 6756 File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface,
Up: Top |
5406 | 6757 |
5407 30 Reporting Bugs in GDB | 6758 30 In-Process Agent |
| 6759 ******************* |
| 6760 |
| 6761 The traditional debugging model is conceptually low-speed, but works |
| 6762 fine, because most bugs can be reproduced in debugging-mode execution. |
| 6763 However, as multi-core or many-core processors are becoming mainstream, |
| 6764 and multi-threaded programs become more and more popular, there should |
| 6765 be more and more bugs that only manifest themselves at normal-mode |
| 6766 execution, for example, thread races, because debugger's interference |
| 6767 with the program's timing may conceal the bugs. On the other hand, in |
| 6768 some applications, it is not feasible for the debugger to interrupt the |
| 6769 program's execution long enough for the developer to learn anything |
| 6770 helpful about its behavior. If the program's correctness depends on |
| 6771 its real-time behavior, delays introduced by a debugger might cause the |
| 6772 program to fail, even when the code itself is correct. It is useful to |
| 6773 be able to observe the program's behavior without interrupting it. |
| 6774 |
| 6775 Therefore, traditional debugging model is too intrusive to reproduce |
| 6776 some bugs. In order to reduce the interference with the program, we can |
| 6777 reduce the number of operations performed by debugger. The "In-Process |
| 6778 Agent", a shared library, is running within the same process with |
| 6779 inferior, and is able to perform some debugging operations itself. As |
| 6780 a result, debugger is only involved when necessary, and performance of |
| 6781 debugging can be improved accordingly. Note that interference with |
| 6782 program can be reduced but can't be removed completely, because the |
| 6783 in-process agent will still stop or slow down the program. |
| 6784 |
| 6785 The in-process agent can interpret and execute Agent Expressions |
| 6786 (*note Agent Expressions::) during performing debugging operations. The |
| 6787 agent expressions can be used for different purposes, such as collecting |
| 6788 data in tracepoints, and condition evaluation in breakpoints. |
| 6789 |
| 6790 You can control whether the in-process agent is used as an aid for |
| 6791 debugging with the following commands: |
| 6792 |
| 6793 `set agent on' |
| 6794 Causes the in-process agent to perform some operations on behalf |
| 6795 of the debugger. Just which operations requested by the user will |
| 6796 be done by the in-process agent depends on the its capabilities. |
| 6797 For example, if you request to evaluate breakpoint conditions in |
| 6798 the in-process agent, and the in-process agent has such capability |
| 6799 as well, then breakpoint conditions will be evaluated in the |
| 6800 in-process agent. |
| 6801 |
| 6802 `set agent off' |
| 6803 Disables execution of debugging operations by the in-process |
| 6804 agent. All of the operations will be performed by GDB. |
| 6805 |
| 6806 `show agent' |
| 6807 Display the current setting of execution of debugging operations by |
| 6808 the in-process agent. |
| 6809 |
| 6810 * Menu: |
| 6811 |
| 6812 * In-Process Agent Protocol:: |
| 6813 |
| 6814 |
| 6815 File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent |
| 6816 |
| 6817 30.1 In-Process Agent Protocol |
| 6818 ============================== |
| 6819 |
| 6820 The in-process agent is able to communicate with both GDB and GDBserver |
| 6821 (*note In-Process Agent::). This section documents the protocol used |
| 6822 for communications between GDB or GDBserver and the IPA. In general, |
| 6823 GDB or GDBserver sends commands (*note IPA Protocol Commands::) and |
| 6824 data to in-process agent, and then in-process agent replies back with |
| 6825 the return result of the command, or some other information. The data |
| 6826 sent to in-process agent is composed of primitive data types, such as |
| 6827 4-byte or 8-byte type, and composite types, which are called objects |
| 6828 (*note IPA Protocol Objects::). |
| 6829 |
| 6830 * Menu: |
| 6831 |
| 6832 * IPA Protocol Objects:: |
| 6833 * IPA Protocol Commands:: |
| 6834 |
| 6835 |
| 6836 File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up:
In-Process Agent Protocol |
| 6837 |
| 6838 30.1.1 IPA Protocol Objects |
| 6839 --------------------------- |
| 6840 |
| 6841 The commands sent to and results received from agent may contain some |
| 6842 complex data types called "objects". |
| 6843 |
| 6844 The in-process agent is running on the same machine with GDB or |
| 6845 GDBserver, so it doesn't have to handle as much differences between two |
| 6846 ends as remote protocol (*note Remote Protocol::) tries to handle. |
| 6847 However, there are still some differences of two ends in two processes: |
| 6848 |
| 6849 1. word size. On some 64-bit machines, GDB or GDBserver can be |
| 6850 compiled as a 64-bit executable, while in-process agent is a |
| 6851 32-bit one. |
| 6852 |
| 6853 2. ABI. Some machines may have multiple types of ABI, GDB or |
| 6854 GDBserver is compiled with one, and in-process agent is compiled |
| 6855 with the other one. |
| 6856 |
| 6857 Here are the IPA Protocol Objects: |
| 6858 |
| 6859 1. agent expression object. It represents an agent expression (*note |
| 6860 Agent Expressions::). |
| 6861 |
| 6862 2. tracepoint action object. It represents a tracepoint action |
| 6863 (*note Tracepoint Action Lists: Tracepoint Actions.) to collect |
| 6864 registers, memory, static trace data and to evaluate expression. |
| 6865 |
| 6866 3. tracepoint object. It represents a tracepoint (*note |
| 6867 Tracepoints::). |
| 6868 |
| 6869 |
| 6870 The following table describes important attributes of each IPA |
| 6871 protocol object: |
| 6872 |
| 6873 Name Size Description |
| 6874 --------------------------------------------------------------------------- |
| 6875 _agent expression |
| 6876 object_ |
| 6877 length 4 length of bytes code |
| 6878 byte code LENGTH contents of byte code |
| 6879 _tracepoint action |
| 6880 for collecting |
| 6881 memory_ |
| 6882 'M' 1 type of tracepoint action |
| 6883 addr 8 if BASEREG is `-1', ADDR is the |
| 6884 address of the lowest byte to |
| 6885 collect, otherwise ADDR is the |
| 6886 offset of BASEREG for memory |
| 6887 collecting. |
| 6888 len 8 length of memory for collecting |
| 6889 basereg 4 the register number containing the |
| 6890 starting memory address for |
| 6891 collecting. |
| 6892 _tracepoint action |
| 6893 for collecting |
| 6894 registers_ |
| 6895 'R' 1 type of tracepoint action |
| 6896 _tracepoint action |
| 6897 for collecting static |
| 6898 trace data_ |
| 6899 'L' 1 type of tracepoint action |
| 6900 _tracepoint action |
| 6901 for expression |
| 6902 evaluation_ |
| 6903 'X' 1 type of tracepoint action |
| 6904 agent expression length of *Note agent expression object:: |
| 6905 _tracepoint object_ |
| 6906 number 4 number of tracepoint |
| 6907 address 8 address of tracepoint inserted on |
| 6908 type 4 type of tracepoint |
| 6909 enabled 1 enable or disable of tracepoint |
| 6910 step_count 8 step |
| 6911 pass_count 8 pass |
| 6912 numactions 4 number of tracepoint actions |
| 6913 hit count 8 hit count |
| 6914 trace frame usage 8 trace frame usage |
| 6915 compiled_cond 8 compiled condition |
| 6916 orig_size 8 orig size |
| 6917 condition 4 if zero if condition is NULL, |
| 6918 condition is otherwise is *Note agent expression |
| 6919 NULL object:: |
| 6920 otherwise |
| 6921 length of |
| 6922 *Note agent |
| 6923 expression |
| 6924 object:: |
| 6925 actions variable numactions number of *Note |
| 6926 tracepoint action object:: |
| 6927 |
| 6928 |
| 6929 File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up:
In-Process Agent Protocol |
| 6930 |
| 6931 30.1.2 IPA Protocol Commands |
| 6932 ---------------------------- |
| 6933 |
| 6934 The spaces in each command are delimiters to ease reading this commands |
| 6935 specification. They don't exist in real commands. |
| 6936 |
| 6937 `FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD' |
| 6938 Installs a new fast tracepoint described by TRACEPOINT_OBJECT |
| 6939 (*note tracepoint object::). GDB_JUMP_PAD_HEAD, 8-byte long, is |
| 6940 the head of "jumppad", which is used to jump to data collection |
| 6941 routine in IPA finally. |
| 6942 |
| 6943 Replies: |
| 6944 `OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP' |
| 6945 TARGET_ADDRESS is address of tracepoint in the inferior. |
| 6946 GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of |
| 6947 TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. FJUMP |
| 6948 contains a sequence of instructions jump to jumppad entry. |
| 6949 FJUMP_SIZE, 4-byte long, is the size of FJUMP. |
| 6950 |
| 6951 `E NN' |
| 6952 for an error |
| 6953 |
| 6954 |
| 6955 `qTfSTM' |
| 6956 *Note qTfSTM::. |
| 6957 |
| 6958 `qTsSTM' |
| 6959 *Note qTsSTM::. |
| 6960 |
| 6961 `qTSTMat' |
| 6962 *Note qTSTMat::. |
| 6963 |
| 6964 `probe_marker_at:ADDRESS' |
| 6965 Asks in-process agent to probe the marker at ADDRESS. |
| 6966 |
| 6967 Replies: |
| 6968 `E NN' |
| 6969 for an error |
| 6970 |
| 6971 `unprobe_marker_at:ADDRESS' |
| 6972 Asks in-process agent to unprobe the marker at ADDRESS. |
| 6973 |
| 6974 |
| 6975 File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process
Agent, Up: Top |
| 6976 |
| 6977 31 Reporting Bugs in GDB |
5408 ************************ | 6978 ************************ |
5409 | 6979 |
5410 Your bug reports play an essential role in making GDB reliable. | 6980 Your bug reports play an essential role in making GDB reliable. |
5411 | 6981 |
5412 Reporting a bug may help you by bringing a solution to your problem, | 6982 Reporting a bug may help you by bringing a solution to your problem, |
5413 or it may not. But in any case the principal function of a bug report | 6983 or it may not. But in any case the principal function of a bug report |
5414 is to help the entire community by making the next version of GDB work | 6984 is to help the entire community by making the next version of GDB work |
5415 better. Bug reports are your contribution to the maintenance of GDB. | 6985 better. Bug reports are your contribution to the maintenance of GDB. |
5416 | 6986 |
5417 In order for a bug report to serve its purpose, you must include the | 6987 In order for a bug report to serve its purpose, you must include the |
5418 information that enables us to fix the bug. | 6988 information that enables us to fix the bug. |
5419 | 6989 |
5420 * Menu: | 6990 * Menu: |
5421 | 6991 |
5422 * Bug Criteria:: Have you found a bug? | 6992 * Bug Criteria:: Have you found a bug? |
5423 * Bug Reporting:: How to report bugs | 6993 * Bug Reporting:: How to report bugs |
5424 | 6994 |
5425 | 6995 |
5426 File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs | 6996 File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs |
5427 | 6997 |
5428 30.1 Have You Found a Bug? | 6998 31.1 Have You Found a Bug? |
5429 ========================== | 6999 ========================== |
5430 | 7000 |
5431 If you are not sure whether you have found a bug, here are some | 7001 If you are not sure whether you have found a bug, here are some |
5432 guidelines: | 7002 guidelines: |
5433 | 7003 |
5434 * If the debugger gets a fatal signal, for any input whatever, that | 7004 * If the debugger gets a fatal signal, for any input whatever, that |
5435 is a GDB bug. Reliable debuggers never crash. | 7005 is a GDB bug. Reliable debuggers never crash. |
5436 | 7006 |
5437 * If GDB produces an error message for valid input, that is a bug. | 7007 * If GDB produces an error message for valid input, that is a bug. |
5438 (Note that if you're cross debugging, the problem may also be | 7008 (Note that if you're cross debugging, the problem may also be |
5439 somewhere in the connection to the target.) | 7009 somewhere in the connection to the target.) |
5440 | 7010 |
5441 * If GDB does not produce an error message for invalid input, that | 7011 * If GDB does not produce an error message for invalid input, that |
5442 is a bug. However, you should note that your idea of "invalid | 7012 is a bug. However, you should note that your idea of "invalid |
5443 input" might be our idea of "an extension" or "support for | 7013 input" might be our idea of "an extension" or "support for |
5444 traditional practice". | 7014 traditional practice". |
5445 | 7015 |
5446 * If you are an experienced user of debugging tools, your suggestions | 7016 * If you are an experienced user of debugging tools, your suggestions |
5447 for improvement of GDB are welcome in any case. | 7017 for improvement of GDB are welcome in any case. |
5448 | 7018 |
5449 | 7019 |
5450 File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs | 7020 File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs |
5451 | 7021 |
5452 30.2 How to Report Bugs | 7022 31.2 How to Report Bugs |
5453 ======================= | 7023 ======================= |
5454 | 7024 |
5455 A number of companies and individuals offer support for GNU products. | 7025 A number of companies and individuals offer support for GNU products. |
5456 If you obtained GDB from a support organization, we recommend you | 7026 If you obtained GDB from a support organization, we recommend you |
5457 contact that organization first. | 7027 contact that organization first. |
5458 | 7028 |
5459 You can find contact information for many support companies and | 7029 You can find contact information for many support companies and |
5460 individuals in the file `etc/SERVICE' in the GNU Emacs distribution. | 7030 individuals in the file `etc/SERVICE' in the GNU Emacs distribution. |
5461 | 7031 |
5462 In any event, we also recommend that you submit bug reports for GDB. | 7032 In any event, we also recommend that you submit bug reports for GDB. |
(...skipping 145 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5608 test case will help us to understand. | 7178 test case will help us to understand. |
5609 | 7179 |
5610 * A guess about what the bug is or what it depends on. | 7180 * A guess about what the bug is or what it depends on. |
5611 | 7181 |
5612 Such guesses are usually wrong. Even we cannot guess right about | 7182 Such guesses are usually wrong. Even we cannot guess right about |
5613 such things without first using the debugger to find the facts. | 7183 such things without first using the debugger to find the facts. |
5614 | 7184 |
5615 | 7185 |
5616 File: gdb.info, Node: Command Line Editing, Next: Using History Interactively,
Prev: GDB Bugs, Up: Top | 7186 File: gdb.info, Node: Command Line Editing, Next: Using History Interactively,
Prev: GDB Bugs, Up: Top |
5617 | 7187 |
5618 31 Command Line Editing | 7188 32 Command Line Editing |
5619 *********************** | 7189 *********************** |
5620 | 7190 |
5621 This chapter describes the basic features of the GNU command line | 7191 This chapter describes the basic features of the GNU command line |
5622 editing interface. | 7192 editing interface. |
5623 | 7193 |
5624 * Menu: | 7194 * Menu: |
5625 | 7195 |
5626 * Introduction and Notation:: Notation used in this text. | 7196 * Introduction and Notation:: Notation used in this text. |
5627 * Readline Interaction:: The minimum set of commands for editing a line. | 7197 * Readline Interaction:: The minimum set of commands for editing a line. |
5628 * Readline Init File:: Customizing Readline from a user's view. | 7198 * Readline Init File:: Customizing Readline from a user's view. |
5629 * Bindable Readline Commands:: A description of most of the Readline commands | 7199 * Bindable Readline Commands:: A description of most of the Readline commands |
5630 available for binding | 7200 available for binding |
5631 * Readline vi Mode:: A short description of how to make Readline | 7201 * Readline vi Mode:: A short description of how to make Readline |
5632 behave like the vi editor. | 7202 behave like the vi editor. |
5633 | 7203 |
5634 | 7204 |
5635 File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction,
Up: Command Line Editing | 7205 File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction,
Up: Command Line Editing |
5636 | 7206 |
5637 31.1 Introduction to Line Editing | 7207 32.1 Introduction to Line Editing |
5638 ================================= | 7208 ================================= |
5639 | 7209 |
5640 The following paragraphs describe the notation used to represent | 7210 The following paragraphs describe the notation used to represent |
5641 keystrokes. | 7211 keystrokes. |
5642 | 7212 |
5643 The text `C-k' is read as `Control-K' and describes the character | 7213 The text `C-k' is read as `Control-K' and describes the character |
5644 produced when the <k> key is pressed while the Control key is depressed. | 7214 produced when the <k> key is pressed while the Control key is depressed. |
5645 | 7215 |
5646 The text `M-k' is read as `Meta-K' and describes the character | 7216 The text `M-k' is read as `Meta-K' and describes the character |
5647 produced when the Meta key (if you have one) is depressed, and the <k> | 7217 produced when the Meta key (if you have one) is depressed, and the <k> |
(...skipping 15 matching lines...) Expand all Loading... |
5663 In addition, several keys have their own names. Specifically, | 7233 In addition, several keys have their own names. Specifically, |
5664 <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves | 7234 <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves |
5665 when seen in this text, or in an init file (*note Readline Init File::). | 7235 when seen in this text, or in an init file (*note Readline Init File::). |
5666 If your keyboard lacks a <LFD> key, typing <C-j> will produce the | 7236 If your keyboard lacks a <LFD> key, typing <C-j> will produce the |
5667 desired character. The <RET> key may be labeled <Return> or <Enter> on | 7237 desired character. The <RET> key may be labeled <Return> or <Enter> on |
5668 some keyboards. | 7238 some keyboards. |
5669 | 7239 |
5670 | 7240 |
5671 File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: I
ntroduction and Notation, Up: Command Line Editing | 7241 File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: I
ntroduction and Notation, Up: Command Line Editing |
5672 | 7242 |
5673 31.2 Readline Interaction | 7243 32.2 Readline Interaction |
5674 ========================= | 7244 ========================= |
5675 | 7245 |
5676 Often during an interactive session you type in a long line of text, | 7246 Often during an interactive session you type in a long line of text, |
5677 only to notice that the first word on the line is misspelled. The | 7247 only to notice that the first word on the line is misspelled. The |
5678 Readline library gives you a set of commands for manipulating the text | 7248 Readline library gives you a set of commands for manipulating the text |
5679 as you type it in, allowing you to just fix your typo, and not forcing | 7249 as you type it in, allowing you to just fix your typo, and not forcing |
5680 you to retype the majority of the line. Using these editing commands, | 7250 you to retype the majority of the line. Using these editing commands, |
5681 you move the cursor to the place that needs correction, and delete or | 7251 you move the cursor to the place that needs correction, and delete or |
5682 insert the text of the corrections. Then, when you are satisfied with | 7252 insert the text of the corrections. Then, when you are satisfied with |
5683 the line, you simply press <RET>. You do not have to be at the end of | 7253 the line, you simply press <RET>. You do not have to be at the end of |
5684 the line to press <RET>; the entire line is accepted regardless of the | 7254 the line to press <RET>; the entire line is accepted regardless of the |
5685 location of the cursor within the line. | 7255 location of the cursor within the line. |
5686 | 7256 |
5687 * Menu: | 7257 * Menu: |
5688 | 7258 |
5689 * Readline Bare Essentials:: The least you need to know about Readline. | 7259 * Readline Bare Essentials:: The least you need to know about Readline. |
5690 * Readline Movement Commands:: Moving about the input line. | 7260 * Readline Movement Commands:: Moving about the input line. |
5691 * Readline Killing Commands:: How to delete text, and how to get it back! | 7261 * Readline Killing Commands:: How to delete text, and how to get it back! |
5692 * Readline Arguments:: Giving numeric arguments to commands. | 7262 * Readline Arguments:: Giving numeric arguments to commands. |
5693 * Searching:: Searching through previous lines. | 7263 * Searching:: Searching through previous lines. |
5694 | 7264 |
5695 | 7265 |
5696 File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Comman
ds, Up: Readline Interaction | 7266 File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Comman
ds, Up: Readline Interaction |
5697 | 7267 |
5698 31.2.1 Readline Bare Essentials | 7268 32.2.1 Readline Bare Essentials |
5699 ------------------------------- | 7269 ------------------------------- |
5700 | 7270 |
5701 In order to enter characters into the line, simply type them. The typed | 7271 In order to enter characters into the line, simply type them. The typed |
5702 character appears where the cursor was, and then the cursor moves one | 7272 character appears where the cursor was, and then the cursor moves one |
5703 space to the right. If you mistype a character, you can use your erase | 7273 space to the right. If you mistype a character, you can use your erase |
5704 character to back up and delete the mistyped character. | 7274 character to back up and delete the mistyped character. |
5705 | 7275 |
5706 Sometimes you may mistype a character, and not notice the error | 7276 Sometimes you may mistype a character, and not notice the error |
5707 until you have typed several other characters. In that case, you can | 7277 until you have typed several other characters. In that case, you can |
5708 type `C-b' to move the cursor to the left, and then correct your | 7278 type `C-b' to move the cursor to the left, and then correct your |
(...skipping 27 matching lines...) Expand all Loading... |
5736 empty line. | 7306 empty line. |
5737 | 7307 |
5738 (Depending on your configuration, the <Backspace> key be set to delete | 7308 (Depending on your configuration, the <Backspace> key be set to delete |
5739 the character to the left of the cursor and the <DEL> key set to delete | 7309 the character to the left of the cursor and the <DEL> key set to delete |
5740 the character underneath the cursor, like `C-d', rather than the | 7310 the character underneath the cursor, like `C-d', rather than the |
5741 character to the left of the cursor.) | 7311 character to the left of the cursor.) |
5742 | 7312 |
5743 | 7313 |
5744 File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Comma
nds, Prev: Readline Bare Essentials, Up: Readline Interaction | 7314 File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Comma
nds, Prev: Readline Bare Essentials, Up: Readline Interaction |
5745 | 7315 |
5746 31.2.2 Readline Movement Commands | 7316 32.2.2 Readline Movement Commands |
5747 --------------------------------- | 7317 --------------------------------- |
5748 | 7318 |
5749 The above table describes the most basic keystrokes that you need in | 7319 The above table describes the most basic keystrokes that you need in |
5750 order to do editing of the input line. For your convenience, many | 7320 order to do editing of the input line. For your convenience, many |
5751 other commands have been added in addition to `C-b', `C-f', `C-d', and | 7321 other commands have been added in addition to `C-b', `C-f', `C-d', and |
5752 <DEL>. Here are some commands for moving more rapidly about the line. | 7322 <DEL>. Here are some commands for moving more rapidly about the line. |
5753 | 7323 |
5754 `C-a' | 7324 `C-a' |
5755 Move to the start of the line. | 7325 Move to the start of the line. |
5756 | 7326 |
(...skipping 10 matching lines...) Expand all Loading... |
5767 `C-l' | 7337 `C-l' |
5768 Clear the screen, reprinting the current line at the top. | 7338 Clear the screen, reprinting the current line at the top. |
5769 | 7339 |
5770 Notice how `C-f' moves forward a character, while `M-f' moves | 7340 Notice how `C-f' moves forward a character, while `M-f' moves |
5771 forward a word. It is a loose convention that control keystrokes | 7341 forward a word. It is a loose convention that control keystrokes |
5772 operate on characters while meta keystrokes operate on words. | 7342 operate on characters while meta keystrokes operate on words. |
5773 | 7343 |
5774 | 7344 |
5775 File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Pr
ev: Readline Movement Commands, Up: Readline Interaction | 7345 File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Pr
ev: Readline Movement Commands, Up: Readline Interaction |
5776 | 7346 |
5777 31.2.3 Readline Killing Commands | 7347 32.2.3 Readline Killing Commands |
5778 -------------------------------- | 7348 -------------------------------- |
5779 | 7349 |
5780 "Killing" text means to delete the text from the line, but to save it | 7350 "Killing" text means to delete the text from the line, but to save it |
5781 away for later use, usually by "yanking" (re-inserting) it back into | 7351 away for later use, usually by "yanking" (re-inserting) it back into |
5782 the line. (`Cut' and `paste' are more recent jargon for `kill' and | 7352 the line. (`Cut' and `paste' are more recent jargon for `kill' and |
5783 `yank'.) | 7353 `yank'.) |
5784 | 7354 |
5785 If the description for a command says that it `kills' text, then you | 7355 If the description for a command says that it `kills' text, then you |
5786 can be sure that you can get the text back in a different (or the same) | 7356 can be sure that you can get the text back in a different (or the same) |
5787 place later. | 7357 place later. |
(...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5820 Yank the most recently killed text back into the buffer at the | 7390 Yank the most recently killed text back into the buffer at the |
5821 cursor. | 7391 cursor. |
5822 | 7392 |
5823 `M-y' | 7393 `M-y' |
5824 Rotate the kill-ring, and yank the new top. You can only do this | 7394 Rotate the kill-ring, and yank the new top. You can only do this |
5825 if the prior command is `C-y' or `M-y'. | 7395 if the prior command is `C-y' or `M-y'. |
5826 | 7396 |
5827 | 7397 |
5828 File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Kil
ling Commands, Up: Readline Interaction | 7398 File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Kil
ling Commands, Up: Readline Interaction |
5829 | 7399 |
5830 31.2.4 Readline Arguments | 7400 32.2.4 Readline Arguments |
5831 ------------------------- | 7401 ------------------------- |
5832 | 7402 |
5833 You can pass numeric arguments to Readline commands. Sometimes the | 7403 You can pass numeric arguments to Readline commands. Sometimes the |
5834 argument acts as a repeat count, other times it is the sign of the | 7404 argument acts as a repeat count, other times it is the sign of the |
5835 argument that is significant. If you pass a negative argument to a | 7405 argument that is significant. If you pass a negative argument to a |
5836 command which normally acts in a forward direction, that command will | 7406 command which normally acts in a forward direction, that command will |
5837 act in a backward direction. For example, to kill text back to the | 7407 act in a backward direction. For example, to kill text back to the |
5838 start of the line, you might type `M-- C-k'. | 7408 start of the line, you might type `M-- C-k'. |
5839 | 7409 |
5840 The general way to pass numeric arguments to a command is to type | 7410 The general way to pass numeric arguments to a command is to type |
5841 meta digits before the command. If the first `digit' typed is a minus | 7411 meta digits before the command. If the first `digit' typed is a minus |
5842 sign (`-'), then the sign of the argument will be negative. Once you | 7412 sign (`-'), then the sign of the argument will be negative. Once you |
5843 have typed one meta digit to get the argument started, you can type the | 7413 have typed one meta digit to get the argument started, you can type the |
5844 remainder of the digits, and then the command. For example, to give | 7414 remainder of the digits, and then the command. For example, to give |
5845 the `C-d' command an argument of 10, you could type `M-1 0 C-d', which | 7415 the `C-d' command an argument of 10, you could type `M-1 0 C-d', which |
5846 will delete the next ten characters on the input line. | 7416 will delete the next ten characters on the input line. |
5847 | 7417 |
5848 | 7418 |
5849 File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Inter
action | 7419 File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Inter
action |
5850 | 7420 |
5851 31.2.5 Searching for Commands in the History | 7421 32.2.5 Searching for Commands in the History |
5852 -------------------------------------------- | 7422 -------------------------------------------- |
5853 | 7423 |
5854 Readline provides commands for searching through the command history | 7424 Readline provides commands for searching through the command history |
5855 for lines containing a specified string. There are two search modes: | 7425 for lines containing a specified string. There are two search modes: |
5856 "incremental" and "non-incremental". | 7426 "incremental" and "non-incremental". |
5857 | 7427 |
5858 Incremental searches begin before the user has finished typing the | 7428 Incremental searches begin before the user has finished typing the |
5859 search string. As each character of the search string is typed, | 7429 search string. As each character of the search string is typed, |
5860 Readline displays the next entry from the history matching the string | 7430 Readline displays the next entry from the history matching the string |
5861 typed so far. An incremental search requires only as many characters | 7431 typed so far. An incremental search requires only as many characters |
(...skipping 20 matching lines...) Expand all Loading... |
5882 `C-r's are typed without any intervening characters defining a new | 7452 `C-r's are typed without any intervening characters defining a new |
5883 search string, any remembered search string is used. | 7453 search string, any remembered search string is used. |
5884 | 7454 |
5885 Non-incremental searches read the entire search string before | 7455 Non-incremental searches read the entire search string before |
5886 starting to search for matching history lines. The search string may be | 7456 starting to search for matching history lines. The search string may be |
5887 typed by the user or be part of the contents of the current line. | 7457 typed by the user or be part of the contents of the current line. |
5888 | 7458 |
5889 | 7459 |
5890 File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, P
rev: Readline Interaction, Up: Command Line Editing | 7460 File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, P
rev: Readline Interaction, Up: Command Line Editing |
5891 | 7461 |
5892 31.3 Readline Init File | 7462 32.3 Readline Init File |
5893 ======================= | 7463 ======================= |
5894 | 7464 |
5895 Although the Readline library comes with a set of Emacs-like | 7465 Although the Readline library comes with a set of Emacs-like |
5896 keybindings installed by default, it is possible to use a different set | 7466 keybindings installed by default, it is possible to use a different set |
5897 of keybindings. Any user can customize programs that use Readline by | 7467 of keybindings. Any user can customize programs that use Readline by |
5898 putting commands in an "inputrc" file, conventionally in his home | 7468 putting commands in an "inputrc" file, conventionally in his home |
5899 directory. The name of this file is taken from the value of the | 7469 directory. The name of this file is taken from the value of the |
5900 environment variable `INPUTRC'. If that variable is unset, the default | 7470 environment variable `INPUTRC'. If that variable is unset, the default |
5901 is `~/.inputrc'. If that file does not exist or cannot be read, the | 7471 is `~/.inputrc'. If that file does not exist or cannot be read, the |
5902 ultimate default is `/etc/inputrc'. | 7472 ultimate default is `/etc/inputrc'. |
5903 | 7473 |
5904 When a program which uses the Readline library starts up, the init | 7474 When a program which uses the Readline library starts up, the init |
5905 file is read, and the key bindings are set. | 7475 file is read, and the key bindings are set. |
5906 | 7476 |
5907 In addition, the `C-x C-r' command re-reads this init file, thus | 7477 In addition, the `C-x C-r' command re-reads this init file, thus |
5908 incorporating any changes that you might have made to it. | 7478 incorporating any changes that you might have made to it. |
5909 | 7479 |
5910 * Menu: | 7480 * Menu: |
5911 | 7481 |
5912 * Readline Init File Syntax:: Syntax for the commands in the inputrc file. | 7482 * Readline Init File Syntax:: Syntax for the commands in the inputrc file. |
5913 | 7483 |
5914 * Conditional Init Constructs:: Conditional key bindings in the inputrc file. | 7484 * Conditional Init Constructs:: Conditional key bindings in the inputrc file. |
5915 | 7485 |
5916 * Sample Init File:: An example inputrc file. | 7486 * Sample Init File:: An example inputrc file. |
5917 | 7487 |
5918 | 7488 |
5919 File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constr
ucts, Up: Readline Init File | 7489 File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constr
ucts, Up: Readline Init File |
5920 | 7490 |
5921 31.3.1 Readline Init File Syntax | 7491 32.3.1 Readline Init File Syntax |
5922 -------------------------------- | 7492 -------------------------------- |
5923 | 7493 |
5924 There are only a few basic constructs allowed in the Readline init | 7494 There are only a few basic constructs allowed in the Readline init |
5925 file. Blank lines are ignored. Lines beginning with a `#' are | 7495 file. Blank lines are ignored. Lines beginning with a `#' are |
5926 comments. Lines beginning with a `$' indicate conditional constructs | 7496 comments. Lines beginning with a `$' indicate conditional constructs |
5927 (*note Conditional Init Constructs::). Other lines denote variable | 7497 (*note Conditional Init Constructs::). Other lines denote variable |
5928 settings and key bindings. | 7498 settings and key bindings. |
5929 | 7499 |
5930 Variable Settings | 7500 Variable Settings |
5931 You can modify the run-time behavior of Readline by altering the | 7501 You can modify the run-time behavior of Readline by altering the |
(...skipping 342 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6274 described above are expanded. Backslash will quote any other | 7844 described above are expanded. Backslash will quote any other |
6275 character in the macro text, including `"' and `''. For example, | 7845 character in the macro text, including `"' and `''. For example, |
6276 the following binding will make `C-x \' insert a single `\' into | 7846 the following binding will make `C-x \' insert a single `\' into |
6277 the line: | 7847 the line: |
6278 "\C-x\\": "\\" | 7848 "\C-x\\": "\\" |
6279 | 7849 |
6280 | 7850 |
6281 | 7851 |
6282 File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Pr
ev: Readline Init File Syntax, Up: Readline Init File | 7852 File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Pr
ev: Readline Init File Syntax, Up: Readline Init File |
6283 | 7853 |
6284 31.3.2 Conditional Init Constructs | 7854 32.3.2 Conditional Init Constructs |
6285 ---------------------------------- | 7855 ---------------------------------- |
6286 | 7856 |
6287 Readline implements a facility similar in spirit to the conditional | 7857 Readline implements a facility similar in spirit to the conditional |
6288 compilation features of the C preprocessor which allows key bindings | 7858 compilation features of the C preprocessor which allows key bindings |
6289 and variable settings to be performed as the result of tests. There | 7859 and variable settings to be performed as the result of tests. There |
6290 are four parser directives used. | 7860 are four parser directives used. |
6291 | 7861 |
6292 `$if' | 7862 `$if' |
6293 The `$if' construct allows bindings to be made based on the | 7863 The `$if' construct allows bindings to be made based on the |
6294 editing mode, the terminal being used, or the application using | 7864 editing mode, the terminal being used, or the application using |
(...skipping 39 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6334 | 7904 |
6335 `$include' | 7905 `$include' |
6336 This directive takes a single filename as an argument and reads | 7906 This directive takes a single filename as an argument and reads |
6337 commands and bindings from that file. For example, the following | 7907 commands and bindings from that file. For example, the following |
6338 directive reads from `/etc/inputrc': | 7908 directive reads from `/etc/inputrc': |
6339 $include /etc/inputrc | 7909 $include /etc/inputrc |
6340 | 7910 |
6341 | 7911 |
6342 File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up
: Readline Init File | 7912 File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up
: Readline Init File |
6343 | 7913 |
6344 31.3.3 Sample Init File | 7914 32.3.3 Sample Init File |
6345 ----------------------- | 7915 ----------------------- |
6346 | 7916 |
6347 Here is an example of an INPUTRC file. This illustrates key binding, | 7917 Here is an example of an INPUTRC file. This illustrates key binding, |
6348 variable assignment, and conditional syntax. | 7918 variable assignment, and conditional syntax. |
6349 | 7919 |
6350 | 7920 |
6351 # This file controls the behaviour of line input editing for | 7921 # This file controls the behaviour of line input editing for |
6352 # programs that use the GNU Readline library. Existing | 7922 # programs that use the GNU Readline library. Existing |
6353 # programs include FTP, Bash, and GDB. | 7923 # programs include FTP, Bash, and GDB. |
6354 # | 7924 # |
(...skipping 89 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6444 # For FTP | 8014 # For FTP |
6445 $if Ftp | 8015 $if Ftp |
6446 "\C-xg": "get \M-?" | 8016 "\C-xg": "get \M-?" |
6447 "\C-xt": "put \M-?" | 8017 "\C-xt": "put \M-?" |
6448 "\M-.": yank-last-arg | 8018 "\M-.": yank-last-arg |
6449 $endif | 8019 $endif |
6450 | 8020 |
6451 | 8021 |
6452 File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Pre
v: Readline Init File, Up: Command Line Editing | 8022 File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Pre
v: Readline Init File, Up: Command Line Editing |
6453 | 8023 |
6454 31.4 Bindable Readline Commands | 8024 32.4 Bindable Readline Commands |
6455 =============================== | 8025 =============================== |
6456 | 8026 |
6457 * Menu: | 8027 * Menu: |
6458 | 8028 |
6459 * Commands For Moving:: Moving about the line. | 8029 * Commands For Moving:: Moving about the line. |
6460 * Commands For History:: Getting at previous lines. | 8030 * Commands For History:: Getting at previous lines. |
6461 * Commands For Text:: Commands for changing text. | 8031 * Commands For Text:: Commands for changing text. |
6462 * Commands For Killing:: Commands for killing and yanking. | 8032 * Commands For Killing:: Commands for killing and yanking. |
6463 * Numeric Arguments:: Specifying numeric arguments, repeat counts. | 8033 * Numeric Arguments:: Specifying numeric arguments, repeat counts. |
6464 * Commands For Completion:: Getting Readline to do the typing for you. | 8034 * Commands For Completion:: Getting Readline to do the typing for you. |
6465 * Keyboard Macros:: Saving and re-executing typed characters | 8035 * Keyboard Macros:: Saving and re-executing typed characters |
6466 * Miscellaneous Commands:: Other miscellaneous commands. | 8036 * Miscellaneous Commands:: Other miscellaneous commands. |
6467 | 8037 |
6468 This section describes Readline commands that may be bound to key | 8038 This section describes Readline commands that may be bound to key |
6469 sequences. Command names without an accompanying key sequence are | 8039 sequences. Command names without an accompanying key sequence are |
6470 unbound by default. | 8040 unbound by default. |
6471 | 8041 |
6472 In the following descriptions, "point" refers to the current cursor | 8042 In the following descriptions, "point" refers to the current cursor |
6473 position, and "mark" refers to a cursor position saved by the | 8043 position, and "mark" refers to a cursor position saved by the |
6474 `set-mark' command. The text between the point and mark is referred to | 8044 `set-mark' command. The text between the point and mark is referred to |
6475 as the "region". | 8045 as the "region". |
6476 | 8046 |
6477 | 8047 |
6478 File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bi
ndable Readline Commands | 8048 File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bi
ndable Readline Commands |
6479 | 8049 |
6480 31.4.1 Commands For Moving | 8050 32.4.1 Commands For Moving |
6481 -------------------------- | 8051 -------------------------- |
6482 | 8052 |
6483 `beginning-of-line (C-a)' | 8053 `beginning-of-line (C-a)' |
6484 Move to the start of the current line. | 8054 Move to the start of the current line. |
6485 | 8055 |
6486 `end-of-line (C-e)' | 8056 `end-of-line (C-e)' |
6487 Move to the end of the line. | 8057 Move to the end of the line. |
6488 | 8058 |
6489 `forward-char (C-f)' | 8059 `forward-char (C-f)' |
6490 Move forward a character. | 8060 Move forward a character. |
(...skipping 13 matching lines...) Expand all Loading... |
6504 Clear the screen and redraw the current line, leaving the current | 8074 Clear the screen and redraw the current line, leaving the current |
6505 line at the top of the screen. | 8075 line at the top of the screen. |
6506 | 8076 |
6507 `redraw-current-line ()' | 8077 `redraw-current-line ()' |
6508 Refresh the current line. By default, this is unbound. | 8078 Refresh the current line. By default, this is unbound. |
6509 | 8079 |
6510 | 8080 |
6511 | 8081 |
6512 File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Co
mmands For Moving, Up: Bindable Readline Commands | 8082 File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Co
mmands For Moving, Up: Bindable Readline Commands |
6513 | 8083 |
6514 31.4.2 Commands For Manipulating The History | 8084 32.4.2 Commands For Manipulating The History |
6515 -------------------------------------------- | 8085 -------------------------------------------- |
6516 | 8086 |
6517 `accept-line (Newline or Return)' | 8087 `accept-line (Newline or Return)' |
6518 Accept the line regardless of where the cursor is. If this line is | 8088 Accept the line regardless of where the cursor is. If this line is |
6519 non-empty, it may be added to the history list for future recall | 8089 non-empty, it may be added to the history list for future recall |
6520 with `add_history()'. If this line is a modified history line, | 8090 with `add_history()'. If this line is a modified history line, |
6521 the history line is restored to its original state. | 8091 the history line is restored to its original state. |
6522 | 8092 |
6523 `previous-history (C-p)' | 8093 `previous-history (C-p)' |
6524 Move `back' through the history list, fetching the previous | 8094 Move `back' through the history list, fetching the previous |
(...skipping 57 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6582 determines the direction to move through the history. A negative | 8152 determines the direction to move through the history. A negative |
6583 argument switches the direction through the history (back or | 8153 argument switches the direction through the history (back or |
6584 forward). The history expansion facilities are used to extract | 8154 forward). The history expansion facilities are used to extract |
6585 the last argument, as if the `!$' history expansion had been | 8155 the last argument, as if the `!$' history expansion had been |
6586 specified. | 8156 specified. |
6587 | 8157 |
6588 | 8158 |
6589 | 8159 |
6590 File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Co
mmands For History, Up: Bindable Readline Commands | 8160 File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Co
mmands For History, Up: Bindable Readline Commands |
6591 | 8161 |
6592 31.4.3 Commands For Changing Text | 8162 32.4.3 Commands For Changing Text |
6593 --------------------------------- | 8163 --------------------------------- |
6594 | 8164 |
6595 `delete-char (C-d)' | 8165 `delete-char (C-d)' |
6596 Delete the character at point. If point is at the beginning of | 8166 Delete the character at point. If point is at the beginning of |
6597 the line, there are no characters in the line, and the last | 8167 the line, there are no characters in the line, and the last |
6598 character typed was not bound to `delete-char', then return EOF. | 8168 character typed was not bound to `delete-char', then return EOF. |
6599 | 8169 |
6600 `backward-delete-char (Rubout)' | 8170 `backward-delete-char (Rubout)' |
6601 Delete the character behind the cursor. A numeric argument means | 8171 Delete the character behind the cursor. A numeric argument means |
6602 to kill the characters instead of deleting them. | 8172 to kill the characters instead of deleting them. |
(...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6650 text at point rather than pushing the text to the right. | 8220 text at point rather than pushing the text to the right. |
6651 Characters bound to `backward-delete-char' replace the character | 8221 Characters bound to `backward-delete-char' replace the character |
6652 before point with a space. | 8222 before point with a space. |
6653 | 8223 |
6654 By default, this command is unbound. | 8224 By default, this command is unbound. |
6655 | 8225 |
6656 | 8226 |
6657 | 8227 |
6658 File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Co
mmands For Text, Up: Bindable Readline Commands | 8228 File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Co
mmands For Text, Up: Bindable Readline Commands |
6659 | 8229 |
6660 31.4.4 Killing And Yanking | 8230 32.4.4 Killing And Yanking |
6661 -------------------------- | 8231 -------------------------- |
6662 | 8232 |
6663 `kill-line (C-k)' | 8233 `kill-line (C-k)' |
6664 Kill the text from point to the end of the line. | 8234 Kill the text from point to the end of the line. |
6665 | 8235 |
6666 `backward-kill-line (C-x Rubout)' | 8236 `backward-kill-line (C-x Rubout)' |
6667 Kill backward to the beginning of the line. | 8237 Kill backward to the beginning of the line. |
6668 | 8238 |
6669 `unix-line-discard (C-u)' | 8239 `unix-line-discard (C-u)' |
6670 Kill backward from the cursor to the beginning of the current line. | 8240 Kill backward from the cursor to the beginning of the current line. |
(...skipping 45 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6716 `yank (C-y)' | 8286 `yank (C-y)' |
6717 Yank the top of the kill ring into the buffer at point. | 8287 Yank the top of the kill ring into the buffer at point. |
6718 | 8288 |
6719 `yank-pop (M-y)' | 8289 `yank-pop (M-y)' |
6720 Rotate the kill-ring, and yank the new top. You can only do this | 8290 Rotate the kill-ring, and yank the new top. You can only do this |
6721 if the prior command is `yank' or `yank-pop'. | 8291 if the prior command is `yank' or `yank-pop'. |
6722 | 8292 |
6723 | 8293 |
6724 File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev:
Commands For Killing, Up: Bindable Readline Commands | 8294 File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev:
Commands For Killing, Up: Bindable Readline Commands |
6725 | 8295 |
6726 31.4.5 Specifying Numeric Arguments | 8296 32.4.5 Specifying Numeric Arguments |
6727 ----------------------------------- | 8297 ----------------------------------- |
6728 | 8298 |
6729 `digit-argument (M-0, M-1, ... M--)' | 8299 `digit-argument (M-0, M-1, ... M--)' |
6730 Add this digit to the argument already accumulating, or start a new | 8300 Add this digit to the argument already accumulating, or start a new |
6731 argument. `M--' starts a negative argument. | 8301 argument. `M--' starts a negative argument. |
6732 | 8302 |
6733 `universal-argument ()' | 8303 `universal-argument ()' |
6734 This is another way to specify an argument. If this command is | 8304 This is another way to specify an argument. If this command is |
6735 followed by one or more digits, optionally with a leading minus | 8305 followed by one or more digits, optionally with a leading minus |
6736 sign, those digits define the argument. If the command is | 8306 sign, those digits define the argument. If the command is |
6737 followed by digits, executing `universal-argument' again ends the | 8307 followed by digits, executing `universal-argument' again ends the |
6738 numeric argument, but is otherwise ignored. As a special case, if | 8308 numeric argument, but is otherwise ignored. As a special case, if |
6739 this command is immediately followed by a character that is | 8309 this command is immediately followed by a character that is |
6740 neither a digit or minus sign, the argument count for the next | 8310 neither a digit or minus sign, the argument count for the next |
6741 command is multiplied by four. The argument count is initially | 8311 command is multiplied by four. The argument count is initially |
6742 one, so executing this function the first time makes the argument | 8312 one, so executing this function the first time makes the argument |
6743 count four, a second time makes the argument count sixteen, and so | 8313 count four, a second time makes the argument count sixteen, and so |
6744 on. By default, this is not bound to a key. | 8314 on. By default, this is not bound to a key. |
6745 | 8315 |
6746 | 8316 |
6747 File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: N
umeric Arguments, Up: Bindable Readline Commands | 8317 File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: N
umeric Arguments, Up: Bindable Readline Commands |
6748 | 8318 |
6749 31.4.6 Letting Readline Type For You | 8319 32.4.6 Letting Readline Type For You |
6750 ------------------------------------ | 8320 ------------------------------------ |
6751 | 8321 |
6752 `complete (<TAB>)' | 8322 `complete (<TAB>)' |
6753 Attempt to perform completion on the text before point. The | 8323 Attempt to perform completion on the text before point. The |
6754 actual completion performed is application-specific. The default | 8324 actual completion performed is application-specific. The default |
6755 is filename completion. | 8325 is filename completion. |
6756 | 8326 |
6757 `possible-completions (M-?)' | 8327 `possible-completions (M-?)' |
6758 List the possible completions of the text before point. When | 8328 List the possible completions of the text before point. When |
6759 displaying completions, Readline sets the number of columns used | 8329 displaying completions, Readline sets the number of columns used |
(...skipping 25 matching lines...) Expand all Loading... |
6785 `delete-char-or-list ()' | 8355 `delete-char-or-list ()' |
6786 Deletes the character under the cursor if not at the beginning or | 8356 Deletes the character under the cursor if not at the beginning or |
6787 end of the line (like `delete-char'). If at the end of the line, | 8357 end of the line (like `delete-char'). If at the end of the line, |
6788 behaves identically to `possible-completions'. This command is | 8358 behaves identically to `possible-completions'. This command is |
6789 unbound by default. | 8359 unbound by default. |
6790 | 8360 |
6791 | 8361 |
6792 | 8362 |
6793 File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Co
mmands For Completion, Up: Bindable Readline Commands | 8363 File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Co
mmands For Completion, Up: Bindable Readline Commands |
6794 | 8364 |
6795 31.4.7 Keyboard Macros | 8365 32.4.7 Keyboard Macros |
6796 ---------------------- | 8366 ---------------------- |
6797 | 8367 |
6798 `start-kbd-macro (C-x ()' | 8368 `start-kbd-macro (C-x ()' |
6799 Begin saving the characters typed into the current keyboard macro. | 8369 Begin saving the characters typed into the current keyboard macro. |
6800 | 8370 |
6801 `end-kbd-macro (C-x ))' | 8371 `end-kbd-macro (C-x ))' |
6802 Stop saving the characters typed into the current keyboard macro | 8372 Stop saving the characters typed into the current keyboard macro |
6803 and save the definition. | 8373 and save the definition. |
6804 | 8374 |
6805 `call-last-kbd-macro (C-x e)' | 8375 `call-last-kbd-macro (C-x e)' |
6806 Re-execute the last keyboard macro defined, by making the | 8376 Re-execute the last keyboard macro defined, by making the |
6807 characters in the macro appear as if typed at the keyboard. | 8377 characters in the macro appear as if typed at the keyboard. |
6808 | 8378 |
6809 | 8379 |
6810 | 8380 |
6811 File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bind
able Readline Commands | 8381 File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bind
able Readline Commands |
6812 | 8382 |
6813 31.4.8 Some Miscellaneous Commands | 8383 32.4.8 Some Miscellaneous Commands |
6814 ---------------------------------- | 8384 ---------------------------------- |
6815 | 8385 |
6816 `re-read-init-file (C-x C-r)' | 8386 `re-read-init-file (C-x C-r)' |
6817 Read in the contents of the INPUTRC file, and incorporate any | 8387 Read in the contents of the INPUTRC file, and incorporate any |
6818 bindings or variable assignments found there. | 8388 bindings or variable assignments found there. |
6819 | 8389 |
6820 `abort (C-g)' | 8390 `abort (C-g)' |
6821 Abort the current editing command and ring the terminal's bell | 8391 Abort the current editing command and ring the terminal's bell |
6822 (subject to the setting of `bell-style'). | 8392 (subject to the setting of `bell-style'). |
6823 | 8393 |
(...skipping 76 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6900 mode. | 8470 mode. |
6901 | 8471 |
6902 `vi-editing-mode (M-C-j)' | 8472 `vi-editing-mode (M-C-j)' |
6903 When in `emacs' editing mode, this causes a switch to `vi' editing | 8473 When in `emacs' editing mode, this causes a switch to `vi' editing |
6904 mode. | 8474 mode. |
6905 | 8475 |
6906 | 8476 |
6907 | 8477 |
6908 File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up:
Command Line Editing | 8478 File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up:
Command Line Editing |
6909 | 8479 |
6910 31.5 Readline vi Mode | 8480 32.5 Readline vi Mode |
6911 ===================== | 8481 ===================== |
6912 | 8482 |
6913 While the Readline library does not have a full set of `vi' editing | 8483 While the Readline library does not have a full set of `vi' editing |
6914 functions, it does contain enough to allow simple editing of the line. | 8484 functions, it does contain enough to allow simple editing of the line. |
6915 The Readline `vi' mode behaves as specified in the POSIX standard. | 8485 The Readline `vi' mode behaves as specified in the POSIX standard. |
6916 | 8486 |
6917 In order to switch interactively between `emacs' and `vi' editing | 8487 In order to switch interactively between `emacs' and `vi' editing |
6918 modes, use the command `M-C-j' (bound to emacs-editing-mode when in | 8488 modes, use the command `M-C-j' (bound to emacs-editing-mode when in |
6919 `vi' mode and to vi-editing-mode in `emacs' mode). The Readline | 8489 `vi' mode and to vi-editing-mode in `emacs' mode). The Readline |
6920 default is `emacs' mode. | 8490 default is `emacs' mode. |
6921 | 8491 |
6922 When you enter a line in `vi' mode, you are already placed in | 8492 When you enter a line in `vi' mode, you are already placed in |
6923 `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches | 8493 `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches |
6924 you into `command' mode, where you can edit the text of the line with | 8494 you into `command' mode, where you can edit the text of the line with |
6925 the standard `vi' movement keys, move to previous history lines with | 8495 the standard `vi' movement keys, move to previous history lines with |
6926 `k' and subsequent lines with `j', and so forth. | 8496 `k' and subsequent lines with `j', and so forth. |
6927 | 8497 |
6928 | 8498 |
6929 File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: C
ommand Line Editing, Up: Top | 8499 File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: C
ommand Line Editing, Up: Top |
6930 | 8500 |
6931 32 Using History Interactively | 8501 33 Using History Interactively |
6932 ****************************** | 8502 ****************************** |
6933 | 8503 |
6934 This chapter describes how to use the GNU History Library interactively, | 8504 This chapter describes how to use the GNU History Library interactively, |
6935 from a user's standpoint. It should be considered a user's guide. For | 8505 from a user's standpoint. It should be considered a user's guide. For |
6936 information on using the GNU History Library in your own programs, | 8506 information on using the GNU History Library in your own programs, |
6937 *note Programming with GNU History: (history)Programming with GNU | 8507 *note Programming with GNU History: (history)Programming with GNU |
6938 History. | 8508 History. |
6939 | 8509 |
6940 * Menu: | 8510 * Menu: |
6941 | 8511 |
6942 * History Interaction:: What it feels like using History as a user. | 8512 * History Interaction:: What it feels like using History as a user. |
6943 | 8513 |
6944 | 8514 |
6945 File: gdb.info, Node: History Interaction, Up: Using History Interactively | 8515 File: gdb.info, Node: History Interaction, Up: Using History Interactively |
6946 | 8516 |
6947 32.1 History Expansion | 8517 33.1 History Expansion |
6948 ====================== | 8518 ====================== |
6949 | 8519 |
6950 The History library provides a history expansion feature that is similar | 8520 The History library provides a history expansion feature that is similar |
6951 to the history expansion provided by `csh'. This section describes the | 8521 to the history expansion provided by `csh'. This section describes the |
6952 syntax used to manipulate the history information. | 8522 syntax used to manipulate the history information. |
6953 | 8523 |
6954 History expansions introduce words from the history list into the | 8524 History expansions introduce words from the history list into the |
6955 input stream, making it easy to repeat commands, insert the arguments | 8525 input stream, making it easy to repeat commands, insert the arguments |
6956 to a previous command into the current input line, or fix errors in | 8526 to a previous command into the current input line, or fix errors in |
6957 previous commands quickly. | 8527 previous commands quickly. |
(...skipping 11 matching lines...) Expand all Loading... |
6969 | 8539 |
6970 * Menu: | 8540 * Menu: |
6971 | 8541 |
6972 * Event Designators:: How to specify which history line to use. | 8542 * Event Designators:: How to specify which history line to use. |
6973 * Word Designators:: Specifying which words are of interest. | 8543 * Word Designators:: Specifying which words are of interest. |
6974 * Modifiers:: Modifying the results of substitution. | 8544 * Modifiers:: Modifying the results of substitution. |
6975 | 8545 |
6976 | 8546 |
6977 File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History
Interaction | 8547 File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History
Interaction |
6978 | 8548 |
6979 32.1.1 Event Designators | 8549 33.1.1 Event Designators |
6980 ------------------------ | 8550 ------------------------ |
6981 | 8551 |
6982 An event designator is a reference to a command line entry in the | 8552 An event designator is a reference to a command line entry in the |
6983 history list. Unless the reference is absolute, events are relative to | 8553 history list. Unless the reference is absolute, events are relative to |
6984 the current position in the history list. | 8554 the current position in the history list. |
6985 | 8555 |
6986 `!' | 8556 `!' |
6987 Start a history substitution, except when followed by a space, tab, | 8557 Start a history substitution, except when followed by a space, tab, |
6988 the end of the line, or `='. | 8558 the end of the line, or `='. |
6989 | 8559 |
(...skipping 19 matching lines...) Expand all Loading... |
7009 Quick Substitution. Repeat the last command, replacing STRING1 | 8579 Quick Substitution. Repeat the last command, replacing STRING1 |
7010 with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. | 8580 with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. |
7011 | 8581 |
7012 `!#' | 8582 `!#' |
7013 The entire command line typed so far. | 8583 The entire command line typed so far. |
7014 | 8584 |
7015 | 8585 |
7016 | 8586 |
7017 File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designat
ors, Up: History Interaction | 8587 File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designat
ors, Up: History Interaction |
7018 | 8588 |
7019 32.1.2 Word Designators | 8589 33.1.2 Word Designators |
7020 ----------------------- | 8590 ----------------------- |
7021 | 8591 |
7022 Word designators are used to select desired words from the event. A | 8592 Word designators are used to select desired words from the event. A |
7023 `:' separates the event specification from the word designator. It may | 8593 `:' separates the event specification from the word designator. It may |
7024 be omitted if the word designator begins with a `^', `$', `*', `-', or | 8594 be omitted if the word designator begins with a `^', `$', `*', `-', or |
7025 `%'. Words are numbered from the beginning of the line, with the first | 8595 `%'. Words are numbered from the beginning of the line, with the first |
7026 word being denoted by 0 (zero). Words are inserted into the current | 8596 word being denoted by 0 (zero). Words are inserted into the current |
7027 line separated by single spaces. | 8597 line separated by single spaces. |
7028 | 8598 |
7029 For example, | 8599 For example, |
(...skipping 41 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7071 `X-' | 8641 `X-' |
7072 Abbreviates `X-$' like `X*', but omits the last word. | 8642 Abbreviates `X-$' like `X*', but omits the last word. |
7073 | 8643 |
7074 | 8644 |
7075 If a word designator is supplied without an event specification, the | 8645 If a word designator is supplied without an event specification, the |
7076 previous command is used as the event. | 8646 previous command is used as the event. |
7077 | 8647 |
7078 | 8648 |
7079 File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interact
ion | 8649 File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interact
ion |
7080 | 8650 |
7081 32.1.3 Modifiers | 8651 33.1.3 Modifiers |
7082 ---------------- | 8652 ---------------- |
7083 | 8653 |
7084 After the optional word designator, you can add a sequence of one or | 8654 After the optional word designator, you can add a sequence of one or |
7085 more of the following modifiers, each preceded by a `:'. | 8655 more of the following modifiers, each preceded by a `:'. |
7086 | 8656 |
7087 `h' | 8657 `h' |
7088 Remove a trailing pathname component, leaving only the head. | 8658 Remove a trailing pathname component, leaving only the head. |
7089 | 8659 |
7090 `t' | 8660 `t' |
7091 Remove all leading pathname components, leaving the tail. | 8661 Remove all leading pathname components, leaving the tail. |
(...skipping 75 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7167 | 8737 |
7168 All the documentation for GDB comes as part of the machine-readable | 8738 All the documentation for GDB comes as part of the machine-readable |
7169 distribution. The documentation is written in Texinfo format, which is | 8739 distribution. The documentation is written in Texinfo format, which is |
7170 a documentation system that uses a single source file to produce both | 8740 a documentation system that uses a single source file to produce both |
7171 on-line information and a printed manual. You can use one of the Info | 8741 on-line information and a printed manual. You can use one of the Info |
7172 formatting commands to create the on-line version of the documentation | 8742 formatting commands to create the on-line version of the documentation |
7173 and TeX (or `texi2roff') to typeset the printed version. | 8743 and TeX (or `texi2roff') to typeset the printed version. |
7174 | 8744 |
7175 GDB includes an already formatted copy of the on-line Info version | 8745 GDB includes an already formatted copy of the on-line Info version |
7176 of this manual in the `gdb' subdirectory. The main Info file is | 8746 of this manual in the `gdb' subdirectory. The main Info file is |
7177 `gdb-7.4.1/gdb/gdb.info', and it refers to subordinate files matching | 8747 `gdb-7.5.1/gdb/gdb.info', and it refers to subordinate files matching |
7178 `gdb.info*' in the same directory. If necessary, you can print out | 8748 `gdb.info*' in the same directory. If necessary, you can print out |
7179 these files, or read them with any editor; but they are easier to read | 8749 these files, or read them with any editor; but they are easier to read |
7180 using the `info' subsystem in GNU Emacs or the standalone `info' | 8750 using the `info' subsystem in GNU Emacs or the standalone `info' |
7181 program, available as part of the GNU Texinfo distribution. | 8751 program, available as part of the GNU Texinfo distribution. |
7182 | 8752 |
7183 If you want to format these Info files yourself, you need one of the | 8753 If you want to format these Info files yourself, you need one of the |
7184 Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. | 8754 Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. |
7185 | 8755 |
7186 If you have `makeinfo' installed, and are in the top level GDB | 8756 If you have `makeinfo' installed, and are in the top level GDB |
7187 source directory (`gdb-7.4.1', in the case of version 7.4.1), you can | 8757 source directory (`gdb-7.5.1', in the case of version 7.5.1), you can |
7188 make the Info file by typing: | 8758 make the Info file by typing: |
7189 | 8759 |
7190 cd gdb | 8760 cd gdb |
7191 make gdb.info | 8761 make gdb.info |
7192 | 8762 |
7193 If you want to typeset and print copies of this manual, you need TeX, | 8763 If you want to typeset and print copies of this manual, you need TeX, |
7194 a program to print its DVI output files, and `texinfo.tex', the Texinfo | 8764 a program to print its DVI output files, and `texinfo.tex', the Texinfo |
7195 definitions file. | 8765 definitions file. |
7196 | 8766 |
7197 TeX is a typesetting program; it does not print files directly, but | 8767 TeX is a typesetting program; it does not print files directly, but |
7198 produces output files called DVI files. To print a typeset document, | 8768 produces output files called DVI files. To print a typeset document, |
7199 you need a program to print DVI files. If your system has TeX | 8769 you need a program to print DVI files. If your system has TeX |
7200 installed, chances are it has such a program. The precise command to | 8770 installed, chances are it has such a program. The precise command to |
7201 use depends on your system; `lpr -d' is common; another (for PostScript | 8771 use depends on your system; `lpr -d' is common; another (for PostScript |
7202 devices) is `dvips'. The DVI print command may require a file name | 8772 devices) is `dvips'. The DVI print command may require a file name |
7203 without any extension or a `.dvi' extension. | 8773 without any extension or a `.dvi' extension. |
7204 | 8774 |
7205 TeX also requires a macro definitions file called `texinfo.tex'. | 8775 TeX also requires a macro definitions file called `texinfo.tex'. |
7206 This file tells TeX how to typeset a document written in Texinfo | 8776 This file tells TeX how to typeset a document written in Texinfo |
7207 format. On its own, TeX cannot either read or typeset a Texinfo file. | 8777 format. On its own, TeX cannot either read or typeset a Texinfo file. |
7208 `texinfo.tex' is distributed with GDB and is located in the | 8778 `texinfo.tex' is distributed with GDB and is located in the |
7209 `gdb-VERSION-NUMBER/texinfo' directory. | 8779 `gdb-VERSION-NUMBER/texinfo' directory. |
7210 | 8780 |
7211 If you have TeX and a DVI printer program installed, you can typeset | 8781 If you have TeX and a DVI printer program installed, you can typeset |
7212 and print this manual. First switch to the `gdb' subdirectory of the | 8782 and print this manual. First switch to the `gdb' subdirectory of the |
7213 main source directory (for example, to `gdb-7.4.1/gdb') and type: | 8783 main source directory (for example, to `gdb-7.5.1/gdb') and type: |
7214 | 8784 |
7215 make gdb.dvi | 8785 make gdb.dvi |
7216 | 8786 |
7217 Then give `gdb.dvi' to your DVI printing program. | 8787 Then give `gdb.dvi' to your DVI printing program. |
7218 | 8788 |
7219 ---------- Footnotes ---------- | 8789 ---------- Footnotes ---------- |
7220 | 8790 |
7221 (1) In `gdb-7.4.1/gdb/refcard.ps' of the version 7.4.1 release. | 8791 (1) In `gdb-7.5.1/gdb/refcard.ps' of the version 7.5.1 release. |
7222 | 8792 |
7223 | 8793 |
7224 File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Forma
tting Documentation, Up: Top | 8794 File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Forma
tting Documentation, Up: Top |
7225 | 8795 |
7226 Appendix C Installing GDB | 8796 Appendix C Installing GDB |
7227 ************************* | 8797 ************************* |
7228 | 8798 |
7229 * Menu: | 8799 * Menu: |
7230 | 8800 |
7231 * Requirements:: Requirements for building GDB | 8801 * Requirements:: Requirements for building GDB |
(...skipping 72 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7304 | 8874 |
7305 GDB's top-level `configure' and `Makefile' will arrange to build | 8875 GDB's top-level `configure' and `Makefile' will arrange to build |
7306 Libiconv if a directory named `libiconv' appears in the top-most | 8876 Libiconv if a directory named `libiconv' appears in the top-most |
7307 source directory. If Libiconv is built this way, and if the | 8877 source directory. If Libiconv is built this way, and if the |
7308 operating system does not provide a suitable `iconv' | 8878 operating system does not provide a suitable `iconv' |
7309 implementation, then the just-built library will automatically be | 8879 implementation, then the just-built library will automatically be |
7310 used by GDB. One easy way to set this up is to download GNU | 8880 used by GDB. One easy way to set this up is to download GNU |
7311 Libiconv, unpack it, and then rename the directory holding the | 8881 Libiconv, unpack it, and then rename the directory holding the |
7312 Libiconv source code to `libiconv'. | 8882 Libiconv source code to `libiconv'. |
7313 | 8883 |
7314 | |
7315 File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Require
ments, Up: Installing GDB | |
7316 | |
7317 C.2 Invoking the GDB `configure' Script | |
7318 ======================================= | |
7319 | |
7320 GDB comes with a `configure' script that automates the process of | |
7321 preparing GDB for installation; you can then use `make' to build the | |
7322 `gdb' program. | |
7323 | |
7324 The GDB distribution includes all the source code you need for GDB | |
7325 in a single directory, whose name is usually composed by appending the | |
7326 version number to `gdb'. | |
7327 | |
7328 For example, the GDB version 7.4.1 distribution is in the | |
7329 `gdb-7.4.1' directory. That directory contains: | |
7330 | |
7331 `gdb-7.4.1/configure (and supporting files)' | |
7332 script for configuring GDB and all its supporting libraries | |
7333 | |
7334 `gdb-7.4.1/gdb' | |
7335 the source specific to GDB itself | |
7336 | |
7337 `gdb-7.4.1/bfd' | |
7338 source for the Binary File Descriptor library | |
7339 | |
7340 `gdb-7.4.1/include' | |
7341 GNU include files | |
7342 | |
7343 `gdb-7.4.1/libiberty' | |
7344 source for the `-liberty' free software library | |
7345 | |
7346 `gdb-7.4.1/opcodes' | |
7347 source for the library of opcode tables and disassemblers | |
7348 | |
7349 `gdb-7.4.1/readline' | |
7350 source for the GNU command-line interface | |
7351 | |
7352 `gdb-7.4.1/glob' | |
7353 source for the GNU filename pattern-matching subroutine | |
7354 | |
7355 `gdb-7.4.1/mmalloc' | |
7356 source for the GNU memory-mapped malloc package | |
7357 | |
7358 The simplest way to configure and build GDB is to run `configure' | |
7359 from the `gdb-VERSION-NUMBER' source directory, which in this example | |
7360 is the `gdb-7.4.1' directory. | |
7361 | |
7362 First switch to the `gdb-VERSION-NUMBER' source directory if you are | |
7363 not already in it; then run `configure'. Pass the identifier for the | |
7364 platform on which GDB will run as an argument. | |
7365 | |
7366 For example: | |
7367 | |
7368 cd gdb-7.4.1 | |
7369 ./configure HOST | |
7370 make | |
7371 | |
7372 where HOST is an identifier such as `sun4' or `decstation', that | |
7373 identifies the platform where GDB will run. (You can often leave off | |
7374 HOST; `configure' tries to guess the correct value by examining your | |
7375 system.) | |
7376 | |
7377 Running `configure HOST' and then running `make' builds the `bfd', | |
7378 `readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. | |
7379 The configured source files, and the binaries, are left in the | |
7380 corresponding source directories. | |
7381 | |
7382 `configure' is a Bourne-shell (`/bin/sh') script; if your system | |
7383 does not recognize this automatically when you run a different shell, | |
7384 you may need to run `sh' on it explicitly: | |
7385 | |
7386 sh configure HOST | |
7387 | |
7388 If you run `configure' from a directory that contains source | |
7389 directories for multiple libraries or programs, such as the `gdb-7.4.1' | |
7390 source directory for version 7.4.1, `configure' creates configuration | |
7391 files for every directory level underneath (unless you tell it not to, | |
7392 with the `--norecursion' option). | |
7393 | |
7394 You should run the `configure' script from the top directory in the | |
7395 source tree, the `gdb-VERSION-NUMBER' directory. If you run | |
7396 `configure' from one of the subdirectories, you will configure only | |
7397 that subdirectory. That is usually not what you want. In particular, | |
7398 if you run the first `configure' from the `gdb' subdirectory of the | |
7399 `gdb-VERSION-NUMBER' directory, you will omit the configuration of | |
7400 `bfd', `readline', and other sibling directories of the `gdb' | |
7401 subdirectory. This leads to build errors about missing include files | |
7402 such as `bfd/bfd.h'. | |
7403 | |
7404 You can install `gdb' anywhere; it has no hardwired paths. However, | |
7405 you should make sure that the shell on your path (named by the `SHELL' | |
7406 environment variable) is publicly readable. Remember that GDB uses the | |
7407 shell to start your program--some systems refuse to let GDB debug child | |
7408 processes whose programs are not readable. | |
7409 | |
7410 | |
7411 File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Conf
igure, Up: Installing GDB | |
7412 | |
7413 C.3 Compiling GDB in Another Directory | |
7414 ====================================== | |
7415 | |
7416 If you want to run GDB versions for several host or target machines, | |
7417 you need a different `gdb' compiled for each combination of host and | |
7418 target. `configure' is designed to make this easy by allowing you to | |
7419 generate each configuration in a separate subdirectory, rather than in | |
7420 the source directory. If your `make' program handles the `VPATH' | |
7421 feature (GNU `make' does), running `make' in each of these directories | |
7422 builds the `gdb' program specified there. | |
7423 | |
7424 To build `gdb' in a separate directory, run `configure' with the | |
7425 `--srcdir' option to specify where to find the source. (You also need | |
7426 to specify a path to find `configure' itself from your working | |
7427 directory. If the path to `configure' would be the same as the | |
7428 argument to `--srcdir', you can leave out the `--srcdir' option; it is | |
7429 assumed.) | |
7430 | |
7431 For example, with version 7.4.1, you can build GDB in a separate | |
7432 directory for a Sun 4 like this: | |
7433 | |
7434 cd gdb-7.4.1 | |
7435 mkdir ../gdb-sun4 | |
7436 cd ../gdb-sun4 | |
7437 ../gdb-7.4.1/configure sun4 | |
7438 make | |
7439 | |
7440 When `configure' builds a configuration using a remote source | |
7441 directory, it creates a tree for the binaries with the same structure | |
7442 (and using the same names) as the tree under the source directory. In | |
7443 the example, you'd find the Sun 4 library `libiberty.a' in the | |
7444 directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. | |
7445 | |
7446 Make sure that your path to the `configure' script has just one | |
7447 instance of `gdb' in it. If your path to `configure' looks like | |
7448 `../gdb-7.4.1/gdb/configure', you are configuring only one subdirectory | |
7449 of GDB, not the whole package. This leads to build errors about | |
7450 missing include files such as `bfd/bfd.h'. | |
7451 | |
7452 One popular reason to build several GDB configurations in separate | |
7453 directories is to configure GDB for cross-compiling (where GDB runs on | |
7454 one machine--the "host"--while debugging programs that run on another | |
7455 machine--the "target"). You specify a cross-debugging target by giving | |
7456 the `--target=TARGET' option to `configure'. | |
7457 | |
7458 When you run `make' to build a program or library, you must run it | |
7459 in a configured directory--whatever directory you were in when you | |
7460 called `configure' (or one of its subdirectories). | |
7461 | |
7462 The `Makefile' that `configure' generates in each source directory | |
7463 also runs recursively. If you type `make' in a source directory such | |
7464 as `gdb-7.4.1' (or in a separate configured directory configured with | |
7465 `--srcdir=DIRNAME/gdb-7.4.1'), you will build all the required | |
7466 libraries, and then build GDB. | |
7467 | |
7468 When you have multiple hosts or targets configured in separate | |
7469 directories, you can run `make' on them in parallel (for example, if | |
7470 they are NFS-mounted on each of the hosts); they will not interfere | |
7471 with each other. | |
7472 | |
7473 | |
7474 File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate O
bjdir, Up: Installing GDB | |
7475 | |
7476 C.4 Specifying Names for Hosts and Targets | |
7477 ========================================== | |
7478 | |
7479 The specifications used for hosts and targets in the `configure' script | |
7480 are based on a three-part naming scheme, but some short predefined | |
7481 aliases are also supported. The full naming scheme encodes three pieces | |
7482 of information in the following pattern: | |
7483 | |
7484 ARCHITECTURE-VENDOR-OS | |
7485 | |
7486 For example, you can use the alias `sun4' as a HOST argument, or as | |
7487 the value for TARGET in a `--target=TARGET' option. The equivalent | |
7488 full name is `sparc-sun-sunos4'. | |
7489 | |
7490 The `configure' script accompanying GDB does not provide any query | |
7491 facility to list all supported host and target names or aliases. | |
7492 `configure' calls the Bourne shell script `config.sub' to map | |
7493 abbreviations to full names; you can read the script, if you wish, or | |
7494 you can use it to test your guesses on abbreviations--for example: | |
7495 | |
7496 % sh config.sub i386-linux | |
7497 i386-pc-linux-gnu | |
7498 % sh config.sub alpha-linux | |
7499 alpha-unknown-linux-gnu | |
7500 % sh config.sub hp9k700 | |
7501 hppa1.1-hp-hpux | |
7502 % sh config.sub sun4 | |
7503 sparc-sun-sunos4.1.1 | |
7504 % sh config.sub sun3 | |
7505 m68k-sun-sunos4.1.1 | |
7506 % sh config.sub i986v | |
7507 Invalid configuration `i986v': machine `i986v' not recognized | |
7508 | |
7509 `config.sub' is also distributed in the GDB source directory | |
7510 (`gdb-7.4.1', for version 7.4.1). | |
7511 | |
7512 | |
7513 File: gdb.info, Node: Configure Options, Next: System-wide configuration, Pre
v: Config Names, Up: Installing GDB | |
7514 | |
7515 C.5 `configure' Options | |
7516 ======================= | |
7517 | |
7518 Here is a summary of the `configure' options and arguments that are | |
7519 most often useful for building GDB. `configure' also has several other | |
7520 options not listed here. *note (configure.info)What Configure Does::, | |
7521 for a full explanation of `configure'. | |
7522 | |
7523 configure [--help] | |
7524 [--prefix=DIR] | |
7525 [--exec-prefix=DIR] | |
7526 [--srcdir=DIRNAME] | |
7527 [--norecursion] [--rm] | |
7528 [--target=TARGET] | |
7529 HOST | |
7530 | |
7531 You may introduce options with a single `-' rather than `--' if you | |
7532 prefer; but you may abbreviate option names if you use `--'. | |
7533 | |
7534 `--help' | |
7535 Display a quick summary of how to invoke `configure'. | |
7536 | |
7537 `--prefix=DIR' | |
7538 Configure the source to install programs and files under directory | |
7539 `DIR'. | |
7540 | |
7541 `--exec-prefix=DIR' | |
7542 Configure the source to install programs under directory `DIR'. | |
7543 | |
7544 `--srcdir=DIRNAME' | |
7545 *Warning: using this option requires GNU `make', or another `make' | |
7546 that implements the `VPATH' feature.* | |
7547 Use this option to make configurations in directories separate | |
7548 from the GDB source directories. Among other things, you can use | |
7549 this to build (or maintain) several configurations simultaneously, | |
7550 in separate directories. `configure' writes | |
7551 configuration-specific files in the current directory, but | |
7552 arranges for them to use the source in the directory DIRNAME. | |
7553 `configure' creates directories under the working directory in | |
7554 parallel to the source directories below DIRNAME. | |
7555 | |
7556 `--norecursion' | |
7557 Configure only the directory level where `configure' is executed; | |
7558 do not propagate configuration to subdirectories. | |
7559 | |
7560 `--target=TARGET' | |
7561 Configure GDB for cross-debugging programs running on the specified | |
7562 TARGET. Without this option, GDB is configured to debug programs | |
7563 that run on the same machine (HOST) as GDB itself. | |
7564 | |
7565 There is no convenient way to generate a list of all available | |
7566 targets. | |
7567 | |
7568 `HOST ...' | |
7569 Configure GDB to run on the specified HOST. | |
7570 | |
7571 There is no convenient way to generate a list of all available | |
7572 hosts. | |
7573 | |
7574 There are many other options available as well, but they are | |
7575 generally needed for special purposes only. | |
7576 | |
7577 | |
7578 File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up:
Installing GDB | |
7579 | |
7580 C.6 System-wide configuration and settings | |
7581 ========================================== | |
7582 | |
7583 GDB can be configured to have a system-wide init file; this file will | |
7584 be read and executed at startup (*note What GDB does during startup: | |
7585 Startup.). | |
7586 | |
7587 Here is the corresponding configure option: | |
7588 | |
7589 `--with-system-gdbinit=FILE' | |
7590 Specify that the default location of the system-wide init file is | |
7591 FILE. | |
7592 | |
7593 If GDB has been configured with the option `--prefix=$prefix', it | |
7594 may be subject to relocation. Two possible cases: | |
7595 | |
7596 * If the default location of this init file contains `$prefix', it | |
7597 will be subject to relocation. Suppose that the configure options | |
7598 are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit'; | |
7599 if GDB is moved from `$prefix' to `$install', the system init file | |
7600 is looked for as `$install/etc/gdbinit' instead of | |
7601 `$prefix/etc/gdbinit'. | |
7602 | |
7603 * By contrast, if the default location does not contain the prefix, | |
7604 it will not be relocated. E.g. if GDB has been configured with | |
7605 `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit', | |
7606 then GDB will always look for `/usr/share/gdb/gdbinit', wherever | |
7607 GDB is installed. | |
7608 | |
7609 | |
7610 File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Inst
alling GDB, Up: Top | |
7611 | |
7612 Appendix D Maintenance Commands | |
7613 ******************************* | |
7614 | |
7615 In addition to commands intended for GDB users, GDB includes a number | |
7616 of commands intended for GDB developers, that are not documented | |
7617 elsewhere in this manual. These commands are provided here for | |
7618 reference. (For commands that turn on debugging messages, see *Note | |
7619 Debugging Output::.) | |
7620 | |
7621 `maint agent EXPRESSION' | |
7622 `maint agent-eval EXPRESSION' | |
7623 Translate the given EXPRESSION into remote agent bytecodes. This | |
7624 command is useful for debugging the Agent Expression mechanism | |
7625 (*note Agent Expressions::). The `agent' version produces an | |
7626 expression useful for data collection, such as by tracepoints, | |
7627 while `maint agent-eval' produces an expression that evaluates | |
7628 directly to a result. For instance, a collection expression for | |
7629 `globa + globb' will include bytecodes to record four bytes of | |
7630 memory at each of the addresses of `globa' and `globb', while | |
7631 discarding the result of the addition, while an evaluation | |
7632 expression will do the addition and return the sum. | |
7633 | |
7634 `maint info breakpoints' | |
7635 Using the same format as `info breakpoints', display both the | |
7636 breakpoints you've set explicitly, and those GDB is using for | |
7637 internal purposes. Internal breakpoints are shown with negative | |
7638 breakpoint numbers. The type column identifies what kind of | |
7639 breakpoint is shown: | |
7640 | |
7641 `breakpoint' | |
7642 Normal, explicitly set breakpoint. | |
7643 | |
7644 `watchpoint' | |
7645 Normal, explicitly set watchpoint. | |
7646 | |
7647 `longjmp' | |
7648 Internal breakpoint, used to handle correctly stepping through | |
7649 `longjmp' calls. | |
7650 | |
7651 `longjmp resume' | |
7652 Internal breakpoint at the target of a `longjmp'. | |
7653 | |
7654 `until' | |
7655 Temporary internal breakpoint used by the GDB `until' command. | |
7656 | |
7657 `finish' | |
7658 Temporary internal breakpoint used by the GDB `finish' | |
7659 command. | |
7660 | |
7661 `shlib events' | |
7662 Shared library events. | |
7663 | |
7664 | |
7665 `set displaced-stepping' | |
7666 `show displaced-stepping' | |
7667 Control whether or not GDB will do "displaced stepping" if the | |
7668 target supports it. Displaced stepping is a way to single-step | |
7669 over breakpoints without removing them from the inferior, by | |
7670 executing an out-of-line copy of the instruction that was | |
7671 originally at the breakpoint location. It is also known as | |
7672 out-of-line single-stepping. | |
7673 | |
7674 `set displaced-stepping on' | |
7675 If the target architecture supports it, GDB will use | |
7676 displaced stepping to step over breakpoints. | |
7677 | |
7678 `set displaced-stepping off' | |
7679 GDB will not use displaced stepping to step over breakpoints, | |
7680 even if such is supported by the target architecture. | |
7681 | |
7682 `set displaced-stepping auto' | |
7683 This is the default mode. GDB will use displaced stepping | |
7684 only if non-stop mode is active (*note Non-Stop Mode::) and | |
7685 the target architecture supports displaced stepping. | |
7686 | |
7687 `maint check-symtabs' | |
7688 Check the consistency of psymtabs and symtabs. | |
7689 | |
7690 `maint cplus first_component NAME' | |
7691 Print the first C++ class/namespace component of NAME. | |
7692 | |
7693 `maint cplus namespace' | |
7694 Print the list of possible C++ namespaces. | |
7695 | |
7696 `maint demangle NAME' | |
7697 Demangle a C++ or Objective-C mangled NAME. | |
7698 | |
7699 `maint deprecate COMMAND [REPLACEMENT]' | |
7700 `maint undeprecate COMMAND' | |
7701 Deprecate or undeprecate the named COMMAND. Deprecated commands | |
7702 cause GDB to issue a warning when you use them. The optional | |
7703 argument REPLACEMENT says which newer command should be used in | |
7704 favor of the deprecated one; if it is given, GDB will mention the | |
7705 replacement as part of the warning. | |
7706 | |
7707 `maint dump-me' | |
7708 Cause a fatal signal in the debugger and force it to dump its core. | |
7709 This is supported only on systems which support aborting a program | |
7710 with the `SIGQUIT' signal. | |
7711 | |
7712 `maint internal-error [MESSAGE-TEXT]' | |
7713 `maint internal-warning [MESSAGE-TEXT]' | |
7714 Cause GDB to call the internal function `internal_error' or | |
7715 `internal_warning' and hence behave as though an internal error or | |
7716 internal warning has been detected. In addition to reporting the | |
7717 internal problem, these functions give the user the opportunity to | |
7718 either quit GDB or create a core file of the current GDB session. | |
7719 | |
7720 These commands take an optional parameter MESSAGE-TEXT that is | |
7721 used as the text of the error or warning message. | |
7722 | |
7723 Here's an example of using `internal-error': | |
7724 | |
7725 (gdb) maint internal-error testing, 1, 2 | |
7726 .../maint.c:121: internal-error: testing, 1, 2 | |
7727 A problem internal to GDB has been detected. Further | |
7728 debugging may prove unreliable. | |
7729 Quit this debugging session? (y or n) n | |
7730 Create a core file? (y or n) n | |
7731 (gdb) | |
7732 | |
7733 `maint set internal-error ACTION [ask|yes|no]' | |
7734 `maint show internal-error ACTION' | |
7735 `maint set internal-warning ACTION [ask|yes|no]' | |
7736 `maint show internal-warning ACTION' | |
7737 When GDB reports an internal problem (error or warning) it gives | |
7738 the user the opportunity to both quit GDB and create a core file | |
7739 of the current GDB session. These commands let you override the | |
7740 default behaviour for each particular ACTION, described in the | |
7741 table below. | |
7742 | |
7743 `quit' | |
7744 You can specify that GDB should always (yes) or never (no) | |
7745 quit. The default is to ask the user what to do. | |
7746 | |
7747 `corefile' | |
7748 You can specify that GDB should always (yes) or never (no) | |
7749 create a core file. The default is to ask the user what to | |
7750 do. | |
7751 | |
7752 `maint packet TEXT' | |
7753 If GDB is talking to an inferior via the serial protocol, then | |
7754 this command sends the string TEXT to the inferior, and displays | |
7755 the response packet. GDB supplies the initial `$' character, the | |
7756 terminating `#' character, and the checksum. | |
7757 | |
7758 `maint print architecture [FILE]' | |
7759 Print the entire architecture configuration. The optional argument | |
7760 FILE names the file where the output goes. | |
7761 | |
7762 `maint print c-tdesc' | |
7763 Print the current target description (*note Target Descriptions::) | |
7764 as a C source file. The created source file can be used in GDB | |
7765 when an XML parser is not available to parse the description. | |
7766 | |
7767 `maint print dummy-frames' | |
7768 Prints the contents of GDB's internal dummy-frame stack. | |
7769 | |
7770 (gdb) b add | |
7771 ... | |
7772 (gdb) print add(2,3) | |
7773 Breakpoint 2, add (a=2, b=3) at ... | |
7774 58 return (a + b); | |
7775 The program being debugged stopped while in a function called from GDB
. | |
7776 ... | |
7777 (gdb) maint print dummy-frames | |
7778 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 | |
7779 top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c} | |
7780 call_lo=0x01014000 call_hi=0x01014001 | |
7781 (gdb) | |
7782 | |
7783 Takes an optional file parameter. | |
7784 | |
7785 `maint print registers [FILE]' | |
7786 `maint print raw-registers [FILE]' | |
7787 `maint print cooked-registers [FILE]' | |
7788 `maint print register-groups [FILE]' | |
7789 `maint print remote-registers [FILE]' | |
7790 Print GDB's internal register data structures. | |
7791 | |
7792 The command `maint print raw-registers' includes the contents of | |
7793 the raw register cache; the command `maint print cooked-registers' | |
7794 includes the (cooked) value of all registers, including registers | |
7795 which aren't available on the target nor visible to user; the | |
7796 command `maint print register-groups' includes the groups that | |
7797 each register is a member of; and the command `maint print | |
7798 remote-registers' includes the remote target's register numbers | |
7799 and offsets in the `G' packets. *Note Registers: | |
7800 (gdbint)Registers. | |
7801 | |
7802 These commands take an optional parameter, a file name to which to | |
7803 write the information. | |
7804 | |
7805 `maint print reggroups [FILE]' | |
7806 Print GDB's internal register group data structures. The optional | |
7807 argument FILE tells to what file to write the information. | |
7808 | |
7809 The register groups info looks like this: | |
7810 | |
7811 (gdb) maint print reggroups | |
7812 Group Type | |
7813 general user | |
7814 float user | |
7815 all user | |
7816 vector user | |
7817 system user | |
7818 save internal | |
7819 restore internal | |
7820 | |
7821 `flushregs' | |
7822 This command forces GDB to flush its internal register cache. | |
7823 | |
7824 `maint print objfiles' | |
7825 Print a dump of all known object files. For each object file, this | |
7826 command prints its name, address in memory, and all of its psymtabs | |
7827 and symtabs. | |
7828 | |
7829 `maint print section-scripts [REGEXP]' | |
7830 Print a dump of scripts specified in the `.debug_gdb_section' | |
7831 section. If REGEXP is specified, only print scripts loaded by | |
7832 object files matching REGEXP. For each script, this command | |
7833 prints its name as specified in the objfile, and the full path if | |
7834 known. *Note .debug_gdb_scripts section::. | |
7835 | |
7836 `maint print statistics' | |
7837 This command prints, for each object file in the program, various | |
7838 data about that object file followed by the byte cache ("bcache") | |
7839 statistics for the object file. The objfile data includes the | |
7840 number of minimal, partial, full, and stabs symbols, the number of | |
7841 types defined by the objfile, the number of as yet unexpanded psym | |
7842 tables, the number of line tables and string tables, and the | |
7843 amount of memory used by the various tables. The bcache | |
7844 statistics include the counts, sizes, and counts of duplicates of | |
7845 all and unique objects, max, average, and median entry size, total | |
7846 memory used and its overhead and savings, and various measures of | |
7847 the hash table size and chain lengths. | |
7848 | |
7849 `maint print target-stack' | |
7850 A "target" is an interface between the debugger and a particular | |
7851 kind of file or process. Targets can be stacked in "strata", so | |
7852 that more than one target can potentially respond to a request. | |
7853 In particular, memory accesses will walk down the stack of targets | |
7854 until they find a target that is interested in handling that | |
7855 particular address. | |
7856 | |
7857 This command prints a short description of each layer that was | |
7858 pushed on the "target stack", starting from the top layer down to | |
7859 the bottom one. | |
7860 | |
7861 `maint print type EXPR' | |
7862 Print the type chain for a type specified by EXPR. The argument | |
7863 can be either a type name or a symbol. If it is a symbol, the | |
7864 type of that symbol is described. The type chain produced by this | |
7865 command is a recursive definition of the data type as stored in | |
7866 GDB's data structures, including its flags and contained types. | |
7867 | |
7868 `maint set dwarf2 always-disassemble' | |
7869 | |
7870 `maint show dwarf2 always-disassemble' | |
7871 Control the behavior of `info address' when using DWARF debugging | |
7872 information. | |
7873 | |
7874 The default is `off', which means that GDB should try to describe | |
7875 a variable's location in an easily readable format. When `on', | |
7876 GDB will instead display the DWARF location expression in an | |
7877 assembly-like format. Note that some locations are too complex | |
7878 for GDB to describe simply; in this case you will always see the | |
7879 disassembly form. | |
7880 | |
7881 Here is an example of the resulting disassembly: | |
7882 | |
7883 (gdb) info addr argc | |
7884 Symbol "argc" is a complex DWARF expression: | |
7885 1: DW_OP_fbreg 0 | |
7886 | |
7887 For more information on these expressions, see the DWARF standard | |
7888 (http://www.dwarfstd.org/). | |
7889 | |
7890 `maint set dwarf2 max-cache-age' | |
7891 `maint show dwarf2 max-cache-age' | |
7892 Control the DWARF 2 compilation unit cache. | |
7893 | |
7894 In object files with inter-compilation-unit references, such as | |
7895 those produced by the GCC option `-feliminate-dwarf2-dups', the | |
7896 DWARF 2 reader needs to frequently refer to previously read | |
7897 compilation units. This setting controls how long a compilation | |
7898 unit will remain in the cache if it is not referenced. A higher | |
7899 limit means that cached compilation units will be stored in memory | |
7900 longer, and more total memory will be used. Setting it to zero | |
7901 disables caching, which will slow down GDB startup, but reduce | |
7902 memory consumption. | |
7903 | |
7904 `maint set profile' | |
7905 `maint show profile' | |
7906 Control profiling of GDB. | |
7907 | |
7908 Profiling will be disabled until you use the `maint set profile' | |
7909 command to enable it. When you enable profiling, the system will | |
7910 begin collecting timing and execution count data; when you disable | |
7911 profiling or exit GDB, the results will be written to a log file. | |
7912 Remember that if you use profiling, GDB will overwrite the | |
7913 profiling log file (often called `gmon.out'). If you have a | |
7914 record of important profiling data in a `gmon.out' file, be sure | |
7915 to move it to a safe location. | |
7916 | |
7917 Configuring with `--enable-profiling' arranges for GDB to be | |
7918 compiled with the `-pg' compiler option. | |
7919 | |
7920 `maint set show-debug-regs' | |
7921 `maint show show-debug-regs' | |
7922 Control whether to show variables that mirror the hardware debug | |
7923 registers. Use `ON' to enable, `OFF' to disable. If enabled, the | |
7924 debug registers values are shown when GDB inserts or removes a | |
7925 hardware breakpoint or watchpoint, and when the inferior triggers | |
7926 a hardware-assisted breakpoint or watchpoint. | |
7927 | |
7928 `maint set show-all-tib' | |
7929 `maint show show-all-tib' | |
7930 Control whether to show all non zero areas within a 1k block | |
7931 starting at thread local base, when using the `info w32 | |
7932 thread-information-block' command. | |
7933 | |
7934 `maint space' | |
7935 Control whether to display memory usage for each command. If set | |
7936 to a nonzero value, GDB will display how much memory each command | |
7937 took, following the command's own output. This can also be | |
7938 requested by invoking GDB with the `--statistics' command-line | |
7939 switch (*note Mode Options::). | |
7940 | |
7941 `maint time' | |
7942 Control whether to display the execution time of GDB for each | |
7943 command. If set to a nonzero value, GDB will display how much | |
7944 time it took to execute each command, following the command's own | |
7945 output. Both CPU time and wallclock time are printed. Printing | |
7946 both is useful when trying to determine whether the cost is CPU | |
7947 or, e.g., disk/network, latency. Note that the CPU time printed | |
7948 is for GDB only, it does not include the execution time of the | |
7949 inferior because there's no mechanism currently to compute how | |
7950 much time was spent by GDB and how much time was spent by the | |
7951 program been debugged. This can also be requested by invoking GDB | |
7952 with the `--statistics' command-line switch (*note Mode Options::). | |
7953 | |
7954 `maint translate-address [SECTION] ADDR' | |
7955 Find the symbol stored at the location specified by the address | |
7956 ADDR and an optional section name SECTION. If found, GDB prints | |
7957 the name of the closest symbol and an offset from the symbol's | |
7958 location to the specified address. This is similar to the `info | |
7959 address' command (*note Symbols::), except that this command also | |
7960 allows to find symbols in other sections. | |
7961 | |
7962 If section was not specified, the section in which the symbol was | |
7963 found is also printed. For dynamically linked executables, the | |
7964 name of executable or shared library containing the symbol is | |
7965 printed as well. | |
7966 | |
7967 | |
7968 The following command is useful for non-interactive invocations of | |
7969 GDB, such as in the test suite. | |
7970 | |
7971 `set watchdog NSEC' | |
7972 Set the maximum number of seconds GDB will wait for the target | |
7973 operation to finish. If this time expires, GDB reports and error | |
7974 and the command is aborted. | |
7975 | |
7976 `show watchdog' | |
7977 Show the current setting of the target wait timeout. | |
7978 | |
7979 | |
7980 File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Mainten
ance Commands, Up: Top | |
7981 | |
7982 Appendix E GDB Remote Serial Protocol | |
7983 ************************************* | |
7984 | |
7985 * Menu: | |
7986 | |
7987 * Overview:: | |
7988 * Packets:: | |
7989 * Stop Reply Packets:: | |
7990 * General Query Packets:: | |
7991 * Architecture-Specific Protocol Details:: | |
7992 * Tracepoint Packets:: | |
7993 * Host I/O Packets:: | |
7994 * Interrupts:: | |
7995 * Notification Packets:: | |
7996 * Remote Non-Stop:: | |
7997 * Packet Acknowledgment:: | |
7998 * Examples:: | |
7999 * File-I/O Remote Protocol Extension:: | |
8000 * Library List Format:: | |
8001 * Library List Format for SVR4 Targets:: | |
8002 * Memory Map Format:: | |
8003 * Thread List Format:: | |
8004 * Traceframe Info Format:: | |
8005 | |
8006 | |
8007 File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol | |
8008 | |
8009 E.1 Overview | |
8010 ============ | |
8011 | |
8012 There may be occasions when you need to know something about the | |
8013 protocol--for example, if there is only one serial port to your target | |
8014 machine, you might want your program to do something special if it | |
8015 recognizes a packet meant for GDB. | |
8016 | |
8017 In the examples below, `->' and `<-' are used to indicate | |
8018 transmitted and received data, respectively. | |
8019 | |
8020 All GDB commands and responses (other than acknowledgments and | |
8021 notifications, see *Note Notification Packets::) are sent as a PACKET. | |
8022 A PACKET is introduced with the character `$', the actual PACKET-DATA, | |
8023 and the terminating character `#' followed by a two-digit CHECKSUM: | |
8024 | |
8025 `$'PACKET-DATA`#'CHECKSUM | |
8026 The two-digit CHECKSUM is computed as the modulo 256 sum of all | |
8027 characters between the leading `$' and the trailing `#' (an eight bit | |
8028 unsigned checksum). | |
8029 | |
8030 Implementors should note that prior to GDB 5.0 the protocol | |
8031 specification also included an optional two-digit SEQUENCE-ID: | |
8032 | |
8033 `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM | |
8034 | |
8035 That SEQUENCE-ID was appended to the acknowledgment. GDB has never | |
8036 output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 | |
8037 must not accept SEQUENCE-ID. | |
8038 | |
8039 When either the host or the target machine receives a packet, the | |
8040 first response expected is an acknowledgment: either `+' (to indicate | |
8041 the package was received correctly) or `-' (to request retransmission): | |
8042 | |
8043 -> `$'PACKET-DATA`#'CHECKSUM | |
8044 <- `+' | |
8045 The `+'/`-' acknowledgments can be disabled once a connection is | |
8046 established. *Note Packet Acknowledgment::, for details. | |
8047 | |
8048 The host (GDB) sends COMMANDs, and the target (the debugging stub | |
8049 incorporated in your program) sends a RESPONSE. In the case of step | |
8050 and continue COMMANDs, the response is only sent when the operation has | |
8051 completed, and the target has again stopped all threads in all attached | |
8052 processes. This is the default all-stop mode behavior, but the remote | |
8053 protocol also supports GDB's non-stop execution mode; see *Note Remote | |
8054 Non-Stop::, for details. | |
8055 | |
8056 PACKET-DATA consists of a sequence of characters with the exception | |
8057 of `#' and `$' (see `X' packet for additional exceptions). | |
8058 | |
8059 Fields within the packet should be separated using `,' `;' or `:'. | |
8060 Except where otherwise noted all numbers are represented in HEX with | |
8061 leading zeros suppressed. | |
8062 | |
8063 Implementors should note that prior to GDB 5.0, the character `:' | |
8064 could not appear as the third character in a packet (as it would | |
8065 potentially conflict with the SEQUENCE-ID). | |
8066 | |
8067 Binary data in most packets is encoded either as two hexadecimal | |
8068 digits per byte of binary data. This allowed the traditional remote | |
8069 protocol to work over connections which were only seven-bit clean. | |
8070 Some packets designed more recently assume an eight-bit clean | |
8071 connection, and use a more efficient encoding to send and receive | |
8072 binary data. | |
8073 | |
8074 The binary data representation uses `7d' (ASCII `}') as an escape | |
8075 character. Any escaped byte is transmitted as the escape character | |
8076 followed by the original character XORed with `0x20'. For example, the | |
8077 byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The | |
8078 bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}') | |
8079 must always be escaped. Responses sent by the stub must also escape | |
8080 `0x2a' (ASCII `*'), so that it is not interpreted as the start of a | |
8081 run-length encoded sequence (described next). | |
8082 | |
8083 Response DATA can be run-length encoded to save space. Run-length | |
8084 encoding replaces runs of identical characters with one instance of the | |
8085 repeated character, followed by a `*' and a repeat count. The repeat | |
8086 count is itself sent encoded, to avoid binary characters in DATA: a | |
8087 value of N is sent as `N+29'. For a repeat count greater or equal to | |
8088 3, this produces a printable ASCII character, e.g. a space (ASCII code | |
8089 32) for a repeat count of 3. (This is because run-length encoding | |
8090 starts to win for counts 3 or more.) Thus, for example, `0* ' is a | |
8091 run-length encoding of "0000": the space character after `*' means | |
8092 repeat the leading `0' `32 - 29 = 3' more times. | |
8093 | |
8094 The printable characters `#' and `$' or with a numeric value greater | |
8095 than 126 must not be used. Runs of six repeats (`#') or seven repeats | |
8096 (`$') can be expanded using a repeat count of only five (`"'). For | |
8097 example, `00000000' can be encoded as `0*"00'. | |
8098 | |
8099 The error response returned for some packets includes a two character | |
8100 error number. That number is not well defined. | |
8101 | |
8102 For any COMMAND not supported by the stub, an empty response | |
8103 (`$#00') should be returned. That way it is possible to extend the | |
8104 protocol. A newer GDB can tell if a packet is supported based on that | |
8105 response. | |
8106 | |
8107 At a minimum, a stub is required to support the `g' and `G' commands | |
8108 for register access, and the `m' and `M' commands for memory access. | |
8109 Stubs that only control single-threaded targets can implement run | |
8110 control with the `c' (continue), and `s' (step) commands. Stubs that | |
8111 support multi-threading targets should support the `vCont' command. | |
8112 All other commands are optional. | |
8113 | |
8114 | |
8115 File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up:
Remote Protocol | |
8116 | |
8117 E.2 Packets | |
8118 =========== | |
8119 | |
8120 The following table provides a complete list of all currently defined | |
8121 COMMANDs and their corresponding response DATA. *Note File-I/O Remote | |
8122 Protocol Extension::, for details about the File I/O extension of the | |
8123 remote protocol. | |
8124 | |
8125 Each packet's description has a template showing the packet's overall | |
8126 syntax, followed by an explanation of the packet's meaning. We include | |
8127 spaces in some of the templates for clarity; these are not part of the | |
8128 packet's syntax. No GDB packet uses spaces to separate its components. | |
8129 For example, a template like `foo BAR BAZ' describes a packet | |
8130 beginning with the three ASCII bytes `foo', followed by a BAR, followed | |
8131 directly by a BAZ. GDB does not transmit a space character between the | |
8132 `foo' and the BAR, or between the BAR and the BAZ. | |
8133 | |
8134 Several packets and replies include a THREAD-ID field to identify a | |
8135 thread. Normally these are positive numbers with a target-specific | |
8136 interpretation, formatted as big-endian hex strings. A THREAD-ID can | |
8137 also be a literal `-1' to indicate all threads, or `0' to pick any | |
8138 thread. | |
8139 | |
8140 In addition, the remote protocol supports a multiprocess feature in | |
8141 which the THREAD-ID syntax is extended to optionally include both | |
8142 process and thread ID fields, as `pPID.TID'. The PID (process) and TID | |
8143 (thread) components each have the format described above: a positive | |
8144 number with target-specific interpretation formatted as a big-endian | |
8145 hex string, literal `-1' to indicate all processes or threads | |
8146 (respectively), or `0' to indicate an arbitrary process or thread. | |
8147 Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It | |
8148 is an error to specify all processes but a specific thread, such as | |
8149 `p-1.TID'. Note that the `p' prefix is _not_ used for those packets | |
8150 and replies explicitly documented to include a process ID, rather than | |
8151 a THREAD-ID. | |
8152 | |
8153 The multiprocess THREAD-ID syntax extensions are only used if both | |
8154 GDB and the stub report support for the `multiprocess' feature using | |
8155 `qSupported'. *Note multiprocess extensions::, for more information. | |
8156 | |
8157 Note that all packet forms beginning with an upper- or lower-case | |
8158 letter, other than those described here, are reserved for future use. | |
8159 | |
8160 Here are the packet descriptions. | |
8161 | |
8162 `!' | |
8163 Enable extended mode. In extended mode, the remote server is made | |
8164 persistent. The `R' packet is used to restart the program being | |
8165 debugged. | |
8166 | |
8167 Reply: | |
8168 `OK' | |
8169 The remote target both supports and has enabled extended mode. | |
8170 | |
8171 `?' | |
8172 Indicate the reason the target halted. The reply is the same as | |
8173 for step and continue. This packet has a special interpretation | |
8174 when the target is in non-stop mode; see *Note Remote Non-Stop::. | |
8175 | |
8176 Reply: *Note Stop Reply Packets::, for the reply specifications. | |
8177 | |
8178 `A ARGLEN,ARGNUM,ARG,...' | |
8179 Initialized `argv[]' array passed into program. ARGLEN specifies | |
8180 the number of bytes in the hex encoded byte stream ARG. See | |
8181 `gdbserver' for more details. | |
8182 | |
8183 Reply: | |
8184 `OK' | |
8185 The arguments were set. | |
8186 | |
8187 `E NN' | |
8188 An error occurred. | |
8189 | |
8190 `b BAUD' | |
8191 (Don't use this packet; its behavior is not well-defined.) Change | |
8192 the serial line speed to BAUD. | |
8193 | |
8194 JTC: _When does the transport layer state change? When it's | |
8195 received, or after the ACK is transmitted. In either case, there | |
8196 are problems if the command or the acknowledgment packet is | |
8197 dropped._ | |
8198 | |
8199 Stan: _If people really wanted to add something like this, and get | |
8200 it working for the first time, they ought to modify ser-unix.c to | |
8201 send some kind of out-of-band message to a specially-setup stub | |
8202 and have the switch happen "in between" packets, so that from | |
8203 remote protocol's point of view, nothing actually happened._ | |
8204 | |
8205 `B ADDR,MODE' | |
8206 Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR. | |
8207 | |
8208 Don't use this packet. Use the `Z' and `z' packets instead (*note | |
8209 insert breakpoint or watchpoint packet::). | |
8210 | |
8211 `bc' | |
8212 Backward continue. Execute the target system in reverse. No | |
8213 parameter. *Note Reverse Execution::, for more information. | |
8214 | |
8215 Reply: *Note Stop Reply Packets::, for the reply specifications. | |
8216 | |
8217 `bs' | |
8218 Backward single step. Execute one instruction in reverse. No | |
8219 parameter. *Note Reverse Execution::, for more information. | |
8220 | |
8221 Reply: *Note Stop Reply Packets::, for the reply specifications. | |
8222 | |
8223 `c [ADDR]' | |
8224 Continue. ADDR is address to resume. If ADDR is omitted, resume | |
8225 at current address. | |
8226 | |
8227 This packet is deprecated for multi-threading support. *Note | |
8228 vCont packet::. | |
8229 | |
8230 Reply: *Note Stop Reply Packets::, for the reply specifications. | |
8231 | |
8232 `C SIG[;ADDR]' | |
8233 Continue with signal SIG (hex signal number). If `;ADDR' is | |
8234 omitted, resume at same address. | |
8235 | |
8236 This packet is deprecated for multi-threading support. *Note | |
8237 vCont packet::. | |
8238 | |
8239 Reply: *Note Stop Reply Packets::, for the reply specifications. | |
8240 | |
8241 `d' | |
8242 Toggle debug flag. | |
8243 | |
8244 Don't use this packet; instead, define a general set packet (*note | |
8245 General Query Packets::). | |
8246 | |
8247 `D' | |
8248 `D;PID' | |
8249 The first form of the packet is used to detach GDB from the remote | |
8250 system. It is sent to the remote target before GDB disconnects | |
8251 via the `detach' command. | |
8252 | |
8253 The second form, including a process ID, is used when multiprocess | |
8254 protocol extensions are enabled (*note multiprocess extensions::), | |
8255 to detach only a specific process. The PID is specified as a | |
8256 big-endian hex string. | |
8257 | |
8258 Reply: | |
8259 `OK' | |
8260 for success | |
8261 | |
8262 `E NN' | |
8263 for an error | |
8264 | |
8265 `F RC,EE,CF;XX' | |
8266 A reply from GDB to an `F' packet sent by the target. This is | |
8267 part of the File-I/O protocol extension. *Note File-I/O Remote | |
8268 Protocol Extension::, for the specification. | |
8269 | |
8270 `g' | |
8271 Read general registers. | |
8272 | |
8273 Reply: | |
8274 `XX...' | |
8275 Each byte of register data is described by two hex digits. | |
8276 The bytes with the register are transmitted in target byte | |
8277 order. The size of each register and their position within | |
8278 the `g' packet are determined by the GDB internal gdbarch | |
8279 functions `DEPRECATED_REGISTER_RAW_SIZE' and | |
8280 `gdbarch_register_name'. The specification of several | |
8281 standard `g' packets is specified below. | |
8282 | |
8283 When reading registers from a trace frame (*note Using the | |
8284 Collected Data: Analyze Collected Data.), the stub may also | |
8285 return a string of literal `x''s in place of the register | |
8286 data digits, to indicate that the corresponding register has | |
8287 not been collected, thus its value is unavailable. For | |
8288 example, for an architecture with 4 registers of 4 bytes | |
8289 each, the following reply indicates to GDB that registers 0 | |
8290 and 2 have not been collected, while registers 1 and 3 have | |
8291 been collected, and both have zero value: | |
8292 | |
8293 -> `g' | |
8294 <- `xxxxxxxx00000000xxxxxxxx00000000' | |
8295 | |
8296 `E NN' | |
8297 for an error. | |
8298 | |
8299 `G XX...' | |
8300 Write general registers. *Note read registers packet::, for a | |
8301 description of the XX... data. | |
8302 | |
8303 Reply: | |
8304 `OK' | |
8305 for success | |
8306 | |
8307 `E NN' | |
8308 for an error | |
8309 | |
8310 `H OP THREAD-ID' | |
8311 Set thread for subsequent operations (`m', `M', `g', `G', et.al.). | |
8312 OP depends on the operation to be performed: it should be `c' for | |
8313 step and continue operations (note that this is deprecated, | |
8314 supporting the `vCont' command is a better option), `g' for other | |
8315 operations. The thread designator THREAD-ID has the format and | |
8316 interpretation described in *Note thread-id syntax::. | |
8317 | |
8318 Reply: | |
8319 `OK' | |
8320 for success | |
8321 | |
8322 `E NN' | |
8323 for an error | |
8324 | |
8325 `i [ADDR[,NNN]]' | |
8326 Step the remote target by a single clock cycle. If `,NNN' is | |
8327 present, cycle step NNN cycles. If ADDR is present, cycle step | |
8328 starting at that address. | |
8329 | |
8330 `I' | |
8331 Signal, then cycle step. *Note step with signal packet::. *Note | |
8332 cycle step packet::. | |
8333 | |
8334 `k' | |
8335 Kill request. | |
8336 | |
8337 FIXME: _There is no description of how to operate when a specific | |
8338 thread context has been selected (i.e. does 'k' kill only that | |
8339 thread?)_. | |
8340 | |
8341 `m ADDR,LENGTH' | |
8342 Read LENGTH bytes of memory starting at address ADDR. Note that | |
8343 ADDR may not be aligned to any particular boundary. | |
8344 | |
8345 The stub need not use any particular size or alignment when | |
8346 gathering data from memory for the response; even if ADDR is | |
8347 word-aligned and LENGTH is a multiple of the word size, the stub | |
8348 is free to use byte accesses, or not. For this reason, this | |
8349 packet may not be suitable for accessing memory-mapped I/O devices. | |
8350 | |
8351 Reply: | |
8352 `XX...' | |
8353 Memory contents; each byte is transmitted as a two-digit | |
8354 hexadecimal number. The reply may contain fewer bytes than | |
8355 requested if the server was able to read only part of the | |
8356 region of memory. | |
8357 | |
8358 `E NN' | |
8359 NN is errno | |
8360 | |
8361 `M ADDR,LENGTH:XX...' | |
8362 Write LENGTH bytes of memory starting at address ADDR. XX... is | |
8363 the data; each byte is transmitted as a two-digit hexadecimal | |
8364 number. | |
8365 | |
8366 Reply: | |
8367 `OK' | |
8368 for success | |
8369 | |
8370 `E NN' | |
8371 for an error (this includes the case where only part of the | |
8372 data was written). | |
8373 | |
8374 `p N' | |
8375 Read the value of register N; N is in hex. *Note read registers | |
8376 packet::, for a description of how the returned register value is | |
8377 encoded. | |
8378 | |
8379 Reply: | |
8380 `XX...' | |
8381 the register's value | |
8382 | |
8383 `E NN' | |
8384 for an error | |
8385 | |
8386 `' | |
8387 Indicating an unrecognized QUERY. | |
8388 | |
8389 `P N...=R...' | |
8390 Write register N... with value R.... The register number N is in | |
8391 hexadecimal, and R... contains two hex digits for each byte in the | |
8392 register (target byte order). | |
8393 | |
8394 Reply: | |
8395 `OK' | |
8396 for success | |
8397 | |
8398 `E NN' | |
8399 for an error | |
8400 | |
8401 `q NAME PARAMS...' | |
8402 `Q NAME PARAMS...' | |
8403 General query (`q') and set (`Q'). These packets are described | |
8404 fully in *Note General Query Packets::. | |
8405 | |
8406 `r' | |
8407 Reset the entire system. | |
8408 | |
8409 Don't use this packet; use the `R' packet instead. | |
8410 | |
8411 `R XX' | |
8412 Restart the program being debugged. XX, while needed, is ignored. | |
8413 This packet is only available in extended mode (*note extended | |
8414 mode::). | |
8415 | |
8416 The `R' packet has no reply. | |
8417 | |
8418 `s [ADDR]' | |
8419 Single step. ADDR is the address at which to resume. If ADDR is | |
8420 omitted, resume at same address. | |
8421 | |
8422 This packet is deprecated for multi-threading support. *Note | |
8423 vCont packet::. | |
8424 | |
8425 Reply: *Note Stop Reply Packets::, for the reply specifications. | |
8426 | |
8427 `S SIG[;ADDR]' | |
8428 Step with signal. This is analogous to the `C' packet, but | |
8429 requests a single-step, rather than a normal resumption of | |
8430 execution. | |
8431 | |
8432 This packet is deprecated for multi-threading support. *Note | |
8433 vCont packet::. | |
8434 | |
8435 Reply: *Note Stop Reply Packets::, for the reply specifications. | |
8436 | |
8437 `t ADDR:PP,MM' | |
8438 Search backwards starting at address ADDR for a match with pattern | |
8439 PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 | |
8440 digits. | |
8441 | |
8442 `T THREAD-ID' | |
8443 Find out if the thread THREAD-ID is alive. *Note thread-id | |
8444 syntax::. | |
8445 | |
8446 Reply: | |
8447 `OK' | |
8448 thread is still alive | |
8449 | |
8450 `E NN' | |
8451 thread is dead | |
8452 | |
8453 `v' | |
8454 Packets starting with `v' are identified by a multi-letter name, | |
8455 up to the first `;' or `?' (or the end of the packet). | |
8456 | |
8457 `vAttach;PID' | |
8458 Attach to a new process with the specified process ID PID. The | |
8459 process ID is a hexadecimal integer identifying the process. In | |
8460 all-stop mode, all threads in the attached process are stopped; in | |
8461 non-stop mode, it may be attached without being stopped if that is | |
8462 supported by the target. | |
8463 | |
8464 This packet is only available in extended mode (*note extended | |
8465 mode::). | |
8466 | |
8467 Reply: | |
8468 `E NN' | |
8469 for an error | |
8470 | |
8471 `Any stop packet' | |
8472 for success in all-stop mode (*note Stop Reply Packets::) | |
8473 | |
8474 `OK' | |
8475 for success in non-stop mode (*note Remote Non-Stop::) | |
8476 | |
8477 `vCont[;ACTION[:THREAD-ID]]...' | |
8478 Resume the inferior, specifying different actions for each thread. | |
8479 If an action is specified with no THREAD-ID, then it is applied to | |
8480 any threads that don't have a specific action specified; if no | |
8481 default action is specified then other threads should remain | |
8482 stopped in all-stop mode and in their current state in non-stop | |
8483 mode. Specifying multiple default actions is an error; specifying | |
8484 no actions is also an error. Thread IDs are specified using the | |
8485 syntax described in *Note thread-id syntax::. | |
8486 | |
8487 Currently supported actions are: | |
8488 | |
8489 `c' | |
8490 Continue. | |
8491 | |
8492 `C SIG' | |
8493 Continue with signal SIG. The signal SIG should be two hex | |
8494 digits. | |
8495 | |
8496 `s' | |
8497 Step. | |
8498 | |
8499 `S SIG' | |
8500 Step with signal SIG. The signal SIG should be two hex | |
8501 digits. | |
8502 | |
8503 `t' | |
8504 Stop. | |
8505 | |
8506 The optional argument ADDR normally associated with the `c', `C', | |
8507 `s', and `S' packets is not supported in `vCont'. | |
8508 | |
8509 The `t' action is only relevant in non-stop mode (*note Remote | |
8510 Non-Stop::) and may be ignored by the stub otherwise. A stop | |
8511 reply should be generated for any affected thread not already | |
8512 stopped. When a thread is stopped by means of a `t' action, the | |
8513 corresponding stop reply should indicate that the thread has | |
8514 stopped with signal `0', regardless of whether the target uses | |
8515 some other signal as an implementation detail. | |
8516 | |
8517 Reply: *Note Stop Reply Packets::, for the reply specifications. | |
8518 | |
8519 `vCont?' | |
8520 Request a list of actions supported by the `vCont' packet. | |
8521 | |
8522 Reply: | |
8523 `vCont[;ACTION...]' | |
8524 The `vCont' packet is supported. Each ACTION is a supported | |
8525 command in the `vCont' packet. | |
8526 | |
8527 `' | |
8528 The `vCont' packet is not supported. | |
8529 | |
8530 `vFile:OPERATION:PARAMETER...' | |
8531 Perform a file operation on the target system. For details, see | |
8532 *Note Host I/O Packets::. | |
8533 | |
8534 `vFlashErase:ADDR,LENGTH' | |
8535 Direct the stub to erase LENGTH bytes of flash starting at ADDR. | |
8536 The region may enclose any number of flash blocks, but its start | |
8537 and end must fall on block boundaries, as indicated by the flash | |
8538 block size appearing in the memory map (*note Memory Map | |
8539 Format::). GDB groups flash memory programming operations | |
8540 together, and sends a `vFlashDone' request after each group; the | |
8541 stub is allowed to delay erase operation until the `vFlashDone' | |
8542 packet is received. | |
8543 | |
8544 The stub must support `vCont' if it reports support for | |
8545 multiprocess extensions (*note multiprocess extensions::). Note | |
8546 that in this case `vCont' actions can be specified to apply to all | |
8547 threads in a process by using the `pPID.-1' form of the THREAD-ID. | |
8548 | |
8549 Reply: | |
8550 `OK' | |
8551 for success | |
8552 | |
8553 `E NN' | |
8554 for an error | |
8555 | |
8556 `vFlashWrite:ADDR:XX...' | |
8557 Direct the stub to write data to flash address ADDR. The data is | |
8558 passed in binary form using the same encoding as for the `X' | |
8559 packet (*note Binary Data::). The memory ranges specified by | |
8560 `vFlashWrite' packets preceding a `vFlashDone' packet must not | |
8561 overlap, and must appear in order of increasing addresses | |
8562 (although `vFlashErase' packets for higher addresses may already | |
8563 have been received; the ordering is guaranteed only between | |
8564 `vFlashWrite' packets). If a packet writes to an address that was | |
8565 neither erased by a preceding `vFlashErase' packet nor by some | |
8566 other target-specific method, the results are unpredictable. | |
8567 | |
8568 Reply: | |
8569 `OK' | |
8570 for success | |
8571 | |
8572 `E.memtype' | |
8573 for vFlashWrite addressing non-flash memory | |
8574 | |
8575 `E NN' | |
8576 for an error | |
8577 | |
8578 `vFlashDone' | |
8579 Indicate to the stub that flash programming operation is finished. | |
8580 The stub is permitted to delay or batch the effects of a group of | |
8581 `vFlashErase' and `vFlashWrite' packets until a `vFlashDone' | |
8582 packet is received. The contents of the affected regions of flash | |
8583 memory are unpredictable until the `vFlashDone' request is | |
8584 completed. | |
8585 | |
8586 `vKill;PID' | |
8587 Kill the process with the specified process ID. PID is a | |
8588 hexadecimal integer identifying the process. This packet is used | |
8589 in preference to `k' when multiprocess protocol extensions are | |
8590 supported; see *Note multiprocess extensions::. | |
8591 | |
8592 Reply: | |
8593 `E NN' | |
8594 for an error | |
8595 | |
8596 `OK' | |
8597 for success | |
8598 | |
8599 `vRun;FILENAME[;ARGUMENT]...' | |
8600 Run the program FILENAME, passing it each ARGUMENT on its command | |
8601 line. The file and arguments are hex-encoded strings. If | |
8602 FILENAME is an empty string, the stub may use a default program | |
8603 (e.g. the last program run). The program is created in the stopped | |
8604 state. | |
8605 | |
8606 This packet is only available in extended mode (*note extended | |
8607 mode::). | |
8608 | |
8609 Reply: | |
8610 `E NN' | |
8611 for an error | |
8612 | |
8613 `Any stop packet' | |
8614 for success (*note Stop Reply Packets::) | |
8615 | |
8616 `vStopped' | |
8617 In non-stop mode (*note Remote Non-Stop::), acknowledge a previous | |
8618 stop reply and prompt for the stub to report another one. | |
8619 | |
8620 Reply: | |
8621 `Any stop packet' | |
8622 if there is another unreported stop event (*note Stop Reply | |
8623 Packets::) | |
8624 | |
8625 `OK' | |
8626 if there are no unreported stop events | |
8627 | |
8628 `X ADDR,LENGTH:XX...' | |
8629 Write data to memory, where the data is transmitted in binary. | |
8630 ADDR is address, LENGTH is number of bytes, `XX...' is binary data | |
8631 (*note Binary Data::). | |
8632 | |
8633 Reply: | |
8634 `OK' | |
8635 for success | |
8636 | |
8637 `E NN' | |
8638 for an error | |
8639 | |
8640 `z TYPE,ADDR,KIND' | |
8641 `Z TYPE,ADDR,KIND' | |
8642 Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint | |
8643 starting at address ADDRESS of kind KIND. | |
8644 | |
8645 Each breakpoint and watchpoint packet TYPE is documented | |
8646 separately. | |
8647 | |
8648 _Implementation notes: A remote target shall return an empty string | |
8649 for an unrecognized breakpoint or watchpoint packet TYPE. A | |
8650 remote target shall support either both or neither of a given | |
8651 `ZTYPE...' and `zTYPE...' packet pair. To avoid potential | |
8652 problems with duplicate packets, the operations should be | |
8653 implemented in an idempotent way._ | |
8654 | |
8655 `z0,ADDR,KIND' | |
8656 `Z0,ADDR,KIND' | |
8657 Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR | |
8658 of type KIND. | |
8659 | |
8660 A memory breakpoint is implemented by replacing the instruction at | |
8661 ADDR with a software breakpoint or trap instruction. The KIND is | |
8662 target-specific and typically indicates the size of the breakpoint | |
8663 in bytes that should be inserted. E.g., the ARM and MIPS can | |
8664 insert either a 2 or 4 byte breakpoint. Some architectures have | |
8665 additional meanings for KIND; see *Note Architecture-Specific | |
8666 Protocol Details::. | |
8667 | |
8668 _Implementation note: It is possible for a target to copy or move | |
8669 code that contains memory breakpoints (e.g., when implementing | |
8670 overlays). The behavior of this packet, in the presence of such a | |
8671 target, is not defined._ | |
8672 | |
8673 Reply: | |
8674 `OK' | |
8675 success | |
8676 | |
8677 `' | |
8678 not supported | |
8679 | |
8680 `E NN' | |
8681 for an error | |
8682 | |
8683 `z1,ADDR,KIND' | |
8684 `Z1,ADDR,KIND' | |
8685 Insert (`Z1') or remove (`z1') a hardware breakpoint at address | |
8686 ADDR. | |
8687 | |
8688 A hardware breakpoint is implemented using a mechanism that is not | |
8689 dependant on being able to modify the target's memory. KIND has | |
8690 the same meaning as in `Z0' packets. | |
8691 | |
8692 _Implementation note: A hardware breakpoint is not affected by code | |
8693 movement._ | |
8694 | |
8695 Reply: | |
8696 `OK' | |
8697 success | |
8698 | |
8699 `' | |
8700 not supported | |
8701 | |
8702 `E NN' | |
8703 for an error | |
8704 | |
8705 `z2,ADDR,KIND' | |
8706 `Z2,ADDR,KIND' | |
8707 Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND | |
8708 is interpreted as the number of bytes to watch. | |
8709 | |
8710 Reply: | |
8711 `OK' | |
8712 success | |
8713 | |
8714 `' | |
8715 not supported | |
8716 | |
8717 `E NN' | |
8718 for an error | |
8719 | |
8720 `z3,ADDR,KIND' | |
8721 `Z3,ADDR,KIND' | |
8722 Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is | |
8723 interpreted as the number of bytes to watch. | |
8724 | |
8725 Reply: | |
8726 `OK' | |
8727 success | |
8728 | |
8729 `' | |
8730 not supported | |
8731 | |
8732 `E NN' | |
8733 for an error | |
8734 | |
8735 `z4,ADDR,KIND' | |
8736 `Z4,ADDR,KIND' | |
8737 Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND | |
8738 is interpreted as the number of bytes to watch. | |
8739 | |
8740 Reply: | |
8741 `OK' | |
8742 success | |
8743 | |
8744 `' | |
8745 not supported | |
8746 | |
8747 `E NN' | |
8748 for an error | |
8749 | |
8750 | |
8751 | |
8752 File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev:
Packets, Up: Remote Protocol | |
8753 | |
8754 E.3 Stop Reply Packets | |
8755 ====================== | |
8756 | |
8757 The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?' | |
8758 packets can receive any of the below as a reply. Except for `?' and | |
8759 `vStopped', that reply is only returned when the target halts. In the | |
8760 below the exact meaning of "signal number" is defined by the header | |
8761 `include/gdb/signals.h' in the GDB source code. | |
8762 | |
8763 As in the description of request packets, we include spaces in the | |
8764 reply templates for clarity; these are not part of the reply packet's | |
8765 syntax. No GDB stop reply packet uses spaces to separate its | |
8766 components. | |
8767 | |
8768 `S AA' | |
8769 The program received signal number AA (a two-digit hexadecimal | |
8770 number). This is equivalent to a `T' response with no N:R pairs. | |
8771 | |
8772 `T AA N1:R1;N2:R2;...' | |
8773 The program received signal number AA (a two-digit hexadecimal | |
8774 number). This is equivalent to an `S' response, except that the | |
8775 `N:R' pairs can carry values of important registers and other | |
8776 information directly in the stop reply packet, reducing round-trip | |
8777 latency. Single-step and breakpoint traps are reported this way. | |
8778 Each `N:R' pair is interpreted as follows: | |
8779 | |
8780 * If N is a hexadecimal number, it is a register number, and the | |
8781 corresponding R gives that register's value. R is a series | |
8782 of bytes in target byte order, with each byte given by a | |
8783 two-digit hex number. | |
8784 | |
8785 * If N is `thread', then R is the THREAD-ID of the stopped | |
8786 thread, as specified in *Note thread-id syntax::. | |
8787 | |
8788 * If N is `core', then R is the hexadecimal number of the core | |
8789 on which the stop event was detected. | |
8790 | |
8791 * If N is a recognized "stop reason", it describes a more | |
8792 specific event that stopped the target. The currently | |
8793 defined stop reasons are listed below. AA should be `05', | |
8794 the trap signal. At most one stop reason should be present. | |
8795 | |
8796 * Otherwise, GDB should ignore this `N:R' pair and go on to the | |
8797 next; this allows us to extend the protocol in the future. | |
8798 | |
8799 The currently defined stop reasons are: | |
8800 | |
8801 `watch' | |
8802 `rwatch' | |
8803 `awatch' | |
8804 The packet indicates a watchpoint hit, and R is the data | |
8805 address, in hex. | |
8806 | |
8807 `library' | |
8808 The packet indicates that the loaded libraries have changed. | |
8809 GDB should use `qXfer:libraries:read' to fetch a new list of | |
8810 loaded libraries. R is ignored. | |
8811 | |
8812 `replaylog' | |
8813 The packet indicates that the target cannot continue replaying | |
8814 logged execution events, because it has reached the end (or | |
8815 the beginning when executing backward) of the log. The value | |
8816 of R will be either `begin' or `end'. *Note Reverse | |
8817 Execution::, for more information. | |
8818 | |
8819 `W AA' | |
8820 `W AA ; process:PID' | |
8821 The process exited, and AA is the exit status. This is only | |
8822 applicable to certain targets. | |
8823 | |
8824 The second form of the response, including the process ID of the | |
8825 exited process, can be used only when GDB has reported support for | |
8826 multiprocess protocol extensions; see *Note multiprocess | |
8827 extensions::. The PID is formatted as a big-endian hex string. | |
8828 | |
8829 `X AA' | |
8830 `X AA ; process:PID' | |
8831 The process terminated with signal AA. | |
8832 | |
8833 The second form of the response, including the process ID of the | |
8834 terminated process, can be used only when GDB has reported support | |
8835 for multiprocess protocol extensions; see *Note multiprocess | |
8836 extensions::. The PID is formatted as a big-endian hex string. | |
8837 | |
8838 `O XX...' | |
8839 `XX...' is hex encoding of ASCII data, to be written as the | |
8840 program's console output. This can happen at any time while the | |
8841 program is running and the debugger should continue to wait for | |
8842 `W', `T', etc. This reply is not permitted in non-stop mode. | |
8843 | |
8844 `F CALL-ID,PARAMETER...' | |
8845 CALL-ID is the identifier which says which host system call should | |
8846 be called. This is just the name of the function. Translation | |
8847 into the correct system call is only applicable as it's defined in | |
8848 GDB. *Note File-I/O Remote Protocol Extension::, for a list of | |
8849 implemented system calls. | |
8850 | |
8851 `PARAMETER...' is a list of parameters as defined for this very | |
8852 system call. | |
8853 | |
8854 The target replies with this packet when it expects GDB to call a | |
8855 host system call on behalf of the target. GDB replies with an | |
8856 appropriate `F' packet and keeps up waiting for the next reply | |
8857 packet from the target. The latest `C', `c', `S' or `s' action is | |
8858 expected to be continued. *Note File-I/O Remote Protocol | |
8859 Extension::, for more details. | |
8860 | |
8861 | |
OLD | NEW |