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: Symbol Errors, Next: Data Files, Prev: Index Files, Up
: GDB Files |
| 45 |
| 46 18.4 Errors Reading Symbol Files |
| 47 ================================ |
| 48 |
| 49 While reading a symbol file, GDB occasionally encounters problems, such |
| 50 as symbol types it does not recognize, or known bugs in compiler |
| 51 output. By default, GDB does not notify you of such problems, since |
| 52 they are relatively common and primarily of interest to people |
| 53 debugging compilers. If you are interested in seeing information about |
| 54 ill-constructed symbol tables, you can either ask GDB to print only one |
| 55 message about each such type of problem, no matter how many times the |
| 56 problem occurs; or you can ask GDB to print more messages, to see how |
| 57 many times the problems occur, with the `set complaints' command (*note |
| 58 Optional Warnings and Messages: Messages/Warnings.). |
| 59 |
| 60 The messages currently printed, and their meanings, include: |
| 61 |
| 62 `inner block not inside outer block in SYMBOL' |
| 63 The symbol information shows where symbol scopes begin and end |
| 64 (such as at the start of a function or a block of statements). |
| 65 This error indicates that an inner scope block is not fully |
| 66 contained in its outer scope blocks. |
| 67 |
| 68 GDB circumvents the problem by treating the inner block as if it |
| 69 had the same scope as the outer block. In the error message, |
| 70 SYMBOL may be shown as "`(don't know)'" if the outer block is not a |
| 71 function. |
| 72 |
| 73 `block at ADDRESS out of order' |
| 74 The symbol information for symbol scope blocks should occur in |
| 75 order of increasing addresses. This error indicates that it does |
| 76 not do so. |
| 77 |
| 78 GDB does not circumvent this problem, and has trouble locating |
| 79 symbols in the source file whose symbols it is reading. (You can |
| 80 often determine what source file is affected by specifying `set |
| 81 verbose on'. *Note Optional Warnings and Messages: |
| 82 Messages/Warnings.) |
| 83 |
| 84 `bad block start address patched' |
| 85 The symbol information for a symbol scope block has a start address |
| 86 smaller than the address of the preceding source line. This is |
| 87 known to occur in the SunOS 4.1.1 (and earlier) C compiler. |
| 88 |
| 89 GDB circumvents the problem by treating the symbol scope block as |
| 90 starting on the previous source line. |
| 91 |
| 92 `bad string table offset in symbol N' |
| 93 Symbol number N contains a pointer into the string table which is |
| 94 larger than the size of the string table. |
| 95 |
| 96 GDB circumvents the problem by considering the symbol to have the |
| 97 name `foo', which may cause other problems if many symbols end up |
| 98 with this name. |
| 99 |
| 100 `unknown symbol type `0xNN'' |
| 101 The symbol information contains new data types that GDB does not |
| 102 yet know how to read. `0xNN' is the symbol type of the |
| 103 uncomprehended information, in hexadecimal. |
| 104 |
| 105 GDB circumvents the error by ignoring this symbol information. |
| 106 This usually allows you to debug your program, though certain |
| 107 symbols are not accessible. If you encounter such a problem and |
| 108 feel like debugging it, you can debug `gdb' with itself, breakpoint |
| 109 on `complain', then go up to the function `read_dbx_symtab' and |
| 110 examine `*bufp' to see the symbol. |
| 111 |
| 112 `stub type has NULL name' |
| 113 GDB could not find the full definition for a struct or class. |
| 114 |
| 115 `const/volatile indicator missing (ok if using g++ v1.x), got...' |
| 116 The symbol information for a C++ member function is missing some |
| 117 information that recent versions of the compiler should have |
| 118 output for it. |
| 119 |
| 120 `info mismatch between compiler and debugger' |
| 121 GDB could not parse a type specification output by the compiler. |
| 122 |
| 123 |
| 124 |
| 125 File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files |
| 126 |
| 127 18.5 GDB Data Files |
| 128 =================== |
| 129 |
| 130 GDB will sometimes read an auxiliary data file. These files are kept |
| 131 in a directory known as the "data directory". |
| 132 |
| 133 You can set the data directory's name, and view the name GDB is |
| 134 currently using. |
| 135 |
| 136 `set data-directory DIRECTORY' |
| 137 Set the directory which GDB searches for auxiliary data files to |
| 138 DIRECTORY. |
| 139 |
| 140 `show data-directory' |
| 141 Show the directory GDB searches for auxiliary data files. |
| 142 |
| 143 You can set the default data directory by using the configure-time |
| 144 `--with-gdb-datadir' option. If the data directory is inside GDB's |
| 145 configured binary prefix (set with `--prefix' or `--exec-prefix'), then |
| 146 the default data directory will be updated automatically if the |
| 147 installed GDB is moved to a new location. |
| 148 |
| 149 The data directory may also be specified with the `--data-directory' |
| 150 command line option. *Note Mode Options::. |
| 151 |
| 152 |
| 153 File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up:
Top |
| 154 |
| 155 19 Specifying a Debugging Target |
| 156 ******************************** |
| 157 |
| 158 A "target" is the execution environment occupied by your program. |
| 159 |
| 160 Often, GDB runs in the same host environment as your program; in |
| 161 that case, the debugging target is specified as a side effect when you |
| 162 use the `file' or `core' commands. When you need more flexibility--for |
| 163 example, running GDB on a physically separate host, or controlling a |
| 164 standalone system over a serial port or a realtime system over a TCP/IP |
| 165 connection--you can use the `target' command to specify one of the |
| 166 target types configured for GDB (*note Commands for Managing Targets: |
| 167 Target Commands.). |
| 168 |
| 169 It is possible to build GDB for several different "target |
| 170 architectures". When GDB is built like that, you can choose one of the |
| 171 available architectures with the `set architecture' command. |
| 172 |
| 173 `set architecture ARCH' |
| 174 This command sets the current target architecture to ARCH. The |
| 175 value of ARCH can be `"auto"', in addition to one of the supported |
| 176 architectures. |
| 177 |
| 178 `show architecture' |
| 179 Show the current target architecture. |
| 180 |
| 181 `set processor' |
| 182 `processor' |
| 183 These are alias commands for, respectively, `set architecture' and |
| 184 `show architecture'. |
| 185 |
| 186 * Menu: |
| 187 |
| 188 * Active Targets:: Active targets |
| 189 * Target Commands:: Commands for managing targets |
| 190 * Byte Order:: Choosing target byte order |
| 191 |
| 192 |
| 193 File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets |
| 194 |
| 195 19.1 Active Targets |
| 196 =================== |
| 197 |
| 198 There are multiple classes of targets such as: processes, executable |
| 199 files or recording sessions. Core files belong to the process class, |
| 200 making core file and process mutually exclusive. Otherwise, GDB can |
| 201 work concurrently on multiple active targets, one in each class. This |
| 202 allows you to (for example) start a process and inspect its activity, |
| 203 while still having access to the executable file after the process |
| 204 finishes. Or if you start process recording (*note Reverse |
| 205 Execution::) and `reverse-step' there, you are presented a virtual |
| 206 layer of the recording target, while the process target remains stopped |
| 207 at the chronologically last point of the process execution. |
| 208 |
| 209 Use the `core-file' and `exec-file' commands to select a new core |
| 210 file or executable target (*note Commands to Specify Files: Files.). To |
| 211 specify as a target a process that is already running, use the `attach' |
| 212 command (*note Debugging an Already-running Process: Attach.). |
| 213 |
| 214 |
| 215 File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets
, Up: Targets |
| 216 |
| 217 19.2 Commands for Managing Targets |
| 218 ================================== |
| 219 |
| 220 `target TYPE PARAMETERS' |
| 221 Connects the GDB host environment to a target machine or process. |
| 222 A target is typically a protocol for talking to debugging |
| 223 facilities. You use the argument TYPE to specify the type or |
| 224 protocol of the target machine. |
| 225 |
| 226 Further PARAMETERS are interpreted by the target protocol, but |
| 227 typically include things like device names or host names to connect |
| 228 with, process numbers, and baud rates. |
| 229 |
| 230 The `target' command does not repeat if you press <RET> again |
| 231 after executing the command. |
| 232 |
| 233 `help target' |
| 234 Displays the names of all targets available. To display targets |
| 235 currently selected, use either `info target' or `info files' |
| 236 (*note Commands to Specify Files: Files.). |
| 237 |
| 238 `help target NAME' |
| 239 Describe a particular target, including any parameters necessary to |
| 240 select it. |
| 241 |
| 242 `set gnutarget ARGS' |
| 243 GDB uses its own library BFD to read your files. GDB knows |
| 244 whether it is reading an "executable", a "core", or a ".o" file; |
| 245 however, you can specify the file format with the `set gnutarget' |
| 246 command. Unlike most `target' commands, with `gnutarget' the |
| 247 `target' refers to a program, not a machine. |
| 248 |
| 249 _Warning:_ To specify a file format with `set gnutarget', you |
| 250 must know the actual BFD name. |
| 251 |
| 252 *Note Commands to Specify Files: Files. |
| 253 |
| 254 `show gnutarget' |
| 255 Use the `show gnutarget' command to display what file format |
| 256 `gnutarget' is set to read. If you have not set `gnutarget', GDB |
| 257 will determine the file format for each file automatically, and |
| 258 `show gnutarget' displays `The current BDF target is "auto"'. |
| 259 |
| 260 Here are some common targets (available, or not, depending on the GDB |
| 261 configuration): |
| 262 |
| 263 `target exec PROGRAM' |
| 264 An executable file. `target exec PROGRAM' is the same as |
| 265 `exec-file PROGRAM'. |
| 266 |
| 267 `target core FILENAME' |
| 268 A core dump file. `target core FILENAME' is the same as |
| 269 `core-file FILENAME'. |
| 270 |
| 271 `target remote MEDIUM' |
| 272 A remote system connected to GDB via a serial line or network |
| 273 connection. This command tells GDB to use its own remote protocol |
| 274 over MEDIUM for debugging. *Note Remote Debugging::. |
| 275 |
| 276 For example, if you have a board connected to `/dev/ttya' on the |
| 277 machine running GDB, you could say: |
| 278 |
| 279 target remote /dev/ttya |
| 280 |
| 281 `target remote' supports the `load' command. This is only useful |
| 282 if you have some other way of getting the stub to the target |
| 283 system, and you can put it somewhere in memory where it won't get |
| 284 clobbered by the download. |
| 285 |
| 286 `target sim [SIMARGS] ...' |
| 287 Builtin CPU simulator. GDB includes simulators for most |
| 288 architectures. In general, |
| 289 target sim |
| 290 load |
| 291 run |
| 292 works; however, you cannot assume that a specific memory map, |
| 293 device drivers, or even basic I/O is available, although some |
| 294 simulators do provide these. For info about any |
| 295 processor-specific simulator details, see the appropriate section |
| 296 in *Note Embedded Processors: Embedded Processors. |
| 297 |
| 298 |
| 299 Some configurations may include these targets as well: |
| 300 |
| 301 `target nrom DEV' |
| 302 NetROM ROM emulator. This target only supports downloading. |
| 303 |
| 304 |
| 305 Different targets are available on different configurations of GDB; |
| 306 your configuration may have more or fewer targets. |
| 307 |
| 308 Many remote targets require you to download the executable's code |
| 309 once you've successfully established a connection. You may wish to |
| 310 control various aspects of this process. |
| 311 |
| 312 `set hash' |
| 313 This command controls whether a hash mark `#' is displayed while |
| 314 downloading a file to the remote monitor. If on, a hash mark is |
| 315 displayed after each S-record is successfully downloaded to the |
| 316 monitor. |
| 317 |
| 318 `show hash' |
| 319 Show the current status of displaying the hash mark. |
| 320 |
| 321 `set debug monitor' |
| 322 Enable or disable display of communications messages between GDB |
| 323 and the remote monitor. |
| 324 |
| 325 `show debug monitor' |
| 326 Show the current status of displaying communications between GDB |
| 327 and the remote monitor. |
| 328 |
| 329 `load FILENAME' |
| 330 Depending on what remote debugging facilities are configured into |
| 331 GDB, the `load' command may be available. Where it exists, it is |
| 332 meant to make FILENAME (an executable) available for debugging on |
| 333 the remote system--by downloading, or dynamic linking, for example. |
| 334 `load' also records the FILENAME symbol table in GDB, like the |
| 335 `add-symbol-file' command. |
| 336 |
| 337 If your GDB does not have a `load' command, attempting to execute |
| 338 it gets the error message "`You can't do that when your target is |
| 339 ...'" |
| 340 |
| 341 The file is loaded at whatever address is specified in the |
| 342 executable. For some object file formats, you can specify the |
| 343 load address when you link the program; for other formats, like |
| 344 a.out, the object file format specifies a fixed address. |
| 345 |
| 346 Depending on the remote side capabilities, GDB may be able to load |
| 347 programs into flash memory. |
| 348 |
| 349 `load' does not repeat if you press <RET> again after using it. |
| 350 |
| 351 |
| 352 File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets |
| 353 |
| 354 19.3 Choosing Target Byte Order |
| 355 =============================== |
| 356 |
| 357 Some types of processors, such as the MIPS, PowerPC, and Renesas SH, |
| 358 offer the ability to run either big-endian or little-endian byte |
| 359 orders. Usually the executable or symbol will include a bit to |
| 360 designate the endian-ness, and you will not need to worry about which |
| 361 to use. However, you may still find it useful to adjust GDB's idea of |
| 362 processor endian-ness manually. |
| 363 |
| 364 `set endian big' |
| 365 Instruct GDB to assume the target is big-endian. |
| 366 |
| 367 `set endian little' |
| 368 Instruct GDB to assume the target is little-endian. |
| 369 |
| 370 `set endian auto' |
| 371 Instruct GDB to use the byte order associated with the executable. |
| 372 |
| 373 `show endian' |
| 374 Display GDB's current idea of the target byte order. |
| 375 |
| 376 |
| 377 Note that these commands merely adjust interpretation of symbolic |
| 378 data on the host, and that they have absolutely no effect on the target |
| 379 system. |
| 380 |
| 381 |
| 382 File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets,
Up: Top |
| 383 |
| 384 20 Debugging Remote Programs |
| 385 **************************** |
| 386 |
| 387 If you are trying to debug a program running on a machine that cannot |
| 388 run GDB in the usual way, it is often useful to use remote debugging. |
| 389 For example, you might use remote debugging on an operating system |
| 390 kernel, or on a small system which does not have a general purpose |
| 391 operating system powerful enough to run a full-featured debugger. |
| 392 |
| 393 Some configurations of GDB have special serial or TCP/IP interfaces |
| 394 to make this work with particular debugging targets. In addition, GDB |
| 395 comes with a generic serial protocol (specific to GDB, but not specific |
| 396 to any particular target system) which you can use if you write the |
| 397 remote stubs--the code that runs on the remote system to communicate |
| 398 with GDB. |
| 399 |
| 400 Other remote targets may be available in your configuration of GDB; |
| 401 use `help target' to list them. |
| 402 |
| 403 * Menu: |
| 404 |
| 405 * Connecting:: Connecting to a remote target |
| 406 * File Transfer:: Sending files to a remote system |
| 407 * Server:: Using the gdbserver program |
| 408 * Remote Configuration:: Remote configuration |
| 409 * Remote Stub:: Implementing a remote stub |
| 410 |
| 411 |
| 412 File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging |
| 413 |
| 414 20.1 Connecting to a Remote Target |
| 415 ================================== |
| 416 |
| 417 On the GDB host machine, you will need an unstripped copy of your |
| 418 program, since GDB needs symbol and debugging information. Start up |
| 419 GDB as usual, using the name of the local copy of your program as the |
| 420 first argument. |
| 421 |
| 422 GDB can communicate with the target over a serial line, or over an |
| 423 IP network using TCP or UDP. In each case, GDB uses the same protocol |
| 424 for debugging your program; only the medium carrying the debugging |
| 425 packets varies. The `target remote' command establishes a connection |
| 426 to the target. Its arguments indicate which medium to use: |
| 427 |
| 428 `target remote SERIAL-DEVICE' |
| 429 Use SERIAL-DEVICE to communicate with the target. For example, to |
| 430 use a serial line connected to the device named `/dev/ttyb': |
| 431 |
| 432 target remote /dev/ttyb |
| 433 |
| 434 If you're using a serial line, you may want to give GDB the |
| 435 `--baud' option, or use the `set remotebaud' command (*note set |
| 436 remotebaud: Remote Configuration.) before the `target' command. |
| 437 |
| 438 `target remote `HOST:PORT'' |
| 439 `target remote `tcp:HOST:PORT'' |
| 440 Debug using a TCP connection to PORT on HOST. The HOST may be |
| 441 either a host name or a numeric IP address; PORT must be a decimal |
| 442 number. The HOST could be the target machine itself, if it is |
| 443 directly connected to the net, or it might be a terminal server |
| 444 which in turn has a serial line to the target. |
| 445 |
| 446 For example, to connect to port 2828 on a terminal server named |
| 447 `manyfarms': |
| 448 |
| 449 target remote manyfarms:2828 |
| 450 |
| 451 If your remote target is actually running on the same machine as |
| 452 your debugger session (e.g. a simulator for your target running on |
| 453 the same host), you can omit the hostname. For example, to |
| 454 connect to port 1234 on your local machine: |
| 455 |
| 456 target remote :1234 |
| 457 Note that the colon is still required here. |
| 458 |
| 459 `target remote `udp:HOST:PORT'' |
| 460 Debug using UDP packets to PORT on HOST. For example, to connect |
| 461 to UDP port 2828 on a terminal server named `manyfarms': |
| 462 |
| 463 target remote udp:manyfarms:2828 |
| 464 |
| 465 When using a UDP connection for remote debugging, you should keep |
| 466 in mind that the `U' stands for "Unreliable". UDP can silently |
| 467 drop packets on busy or unreliable networks, which will cause |
| 468 havoc with your debugging session. |
| 469 |
| 470 `target remote | COMMAND' |
| 471 Run COMMAND in the background and communicate with it using a |
| 472 pipe. The COMMAND is a shell command, to be parsed and expanded |
| 473 by the system's command shell, `/bin/sh'; it should expect remote |
| 474 protocol packets on its standard input, and send replies on its |
| 475 standard output. You could use this to run a stand-alone simulator |
| 476 that speaks the remote debugging protocol, to make net connections |
| 477 using programs like `ssh', or for other similar tricks. |
| 478 |
| 479 If COMMAND closes its standard output (perhaps by exiting), GDB |
| 480 will try to send it a `SIGTERM' signal. (If the program has |
| 481 already exited, this will have no effect.) |
| 482 |
| 483 |
| 484 Once the connection has been established, you can use all the usual |
| 485 commands to examine and change data. The remote program is already |
| 486 running; you can use `step' and `continue', and you do not need to use |
| 487 `run'. |
| 488 |
| 489 Whenever GDB is waiting for the remote program, if you type the |
| 490 interrupt character (often `Ctrl-c'), GDB attempts to stop the program. |
| 491 This may or may not succeed, depending in part on the hardware and the |
| 492 serial drivers the remote system uses. If you type the interrupt |
| 493 character once again, GDB displays this prompt: |
| 494 |
| 495 Interrupted while waiting for the program. |
| 496 Give up (and stop debugging it)? (y or n) |
| 497 |
| 498 If you type `y', GDB abandons the remote debugging session. (If you |
| 499 decide you want to try again later, you can use `target remote' again |
| 500 to connect once more.) If you type `n', GDB goes back to waiting. |
| 501 |
| 502 `detach' |
| 503 When you have finished debugging the remote program, you can use |
| 504 the `detach' command to release it from GDB control. Detaching |
| 505 from the target normally resumes its execution, but the results |
| 506 will depend on your particular remote stub. After the `detach' |
| 507 command, GDB is free to connect to another target. |
| 508 |
| 509 `disconnect' |
| 510 The `disconnect' command behaves like `detach', except that the |
| 511 target is generally not resumed. It will wait for GDB (this |
| 512 instance or another one) to connect and continue debugging. After |
| 513 the `disconnect' command, GDB is again free to connect to another |
| 514 target. |
| 515 |
| 516 `monitor CMD' |
| 517 This command allows you to send arbitrary commands directly to the |
| 518 remote monitor. Since GDB doesn't care about the commands it |
| 519 sends like this, this command is the way to extend GDB--you can |
| 520 add new commands that only the external monitor will understand |
| 521 and implement. |
| 522 |
| 523 |
| 524 File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Rem
ote Debugging |
| 525 |
| 526 20.2 Sending files to a remote system |
| 527 ===================================== |
| 528 |
| 529 Some remote targets offer the ability to transfer files over the same |
| 530 connection used to communicate with GDB. This is convenient for |
| 531 targets accessible through other means, e.g. GNU/Linux systems running |
| 532 `gdbserver' over a network interface. For other targets, e.g. embedded |
| 533 devices with only a single serial port, this may be the only way to |
| 534 upload or download files. |
| 535 |
| 536 Not all remote targets support these commands. |
| 537 |
| 538 `remote put HOSTFILE TARGETFILE' |
| 539 Copy file HOSTFILE from the host system (the machine running GDB) |
| 540 to TARGETFILE on the target system. |
| 541 |
| 542 `remote get TARGETFILE HOSTFILE' |
| 543 Copy file TARGETFILE from the target system to HOSTFILE on the |
| 544 host system. |
| 545 |
| 546 `remote delete TARGETFILE' |
| 547 Delete TARGETFILE from the target system. |
| 548 |
| 549 |
| 550 |
44 File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer
, Up: Remote Debugging | 551 File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer
, Up: Remote Debugging |
45 | 552 |
46 20.3 Using the `gdbserver' Program | 553 20.3 Using the `gdbserver' Program |
47 ================================== | 554 ================================== |
48 | 555 |
49 `gdbserver' is a control program for Unix-like systems, which allows | 556 `gdbserver' is a control program for Unix-like systems, which allows |
50 you to connect your program with a remote GDB via `target remote'--but | 557 you to connect your program with a remote GDB via `target remote'--but |
51 without linking in the usual debugging stub. | 558 without linking in the usual debugging stub. |
52 | 559 |
53 `gdbserver' is not a complete replacement for the debugging stubs, | 560 `gdbserver' is not a complete replacement for the debugging stubs, |
(...skipping 25 matching lines...) Expand all Loading... |
79 does not need your program's symbol table, so you can strip the program | 586 does not need your program's symbol table, so you can strip the program |
80 if necessary to save space. GDB on the host system does all the symbol | 587 if necessary to save space. GDB on the host system does all the symbol |
81 handling. | 588 handling. |
82 | 589 |
83 To use the server, you must tell it how to communicate with GDB; the | 590 To use the server, you must tell it how to communicate with GDB; the |
84 name of your program; and the arguments for your program. The usual | 591 name of your program; and the arguments for your program. The usual |
85 syntax is: | 592 syntax is: |
86 | 593 |
87 target> gdbserver COMM PROGRAM [ ARGS ... ] | 594 target> gdbserver COMM PROGRAM [ ARGS ... ] |
88 | 595 |
89 COMM is either a device name (to use a serial line) or a TCP | 596 COMM is either a device name (to use a serial line), or a TCP |
90 hostname and portnumber. For example, to debug Emacs with the argument | 597 hostname and portnumber, or `-' or `stdio' to use stdin/stdout of |
91 `foo.txt' and communicate with GDB over the serial port `/dev/com1': | 598 `gdbserver'. For example, to debug Emacs with the argument `foo.txt' |
| 599 and communicate with GDB over the serial port `/dev/com1': |
92 | 600 |
93 target> gdbserver /dev/com1 emacs foo.txt | 601 target> gdbserver /dev/com1 emacs foo.txt |
94 | 602 |
95 `gdbserver' waits passively for the host GDB to communicate with it. | 603 `gdbserver' waits passively for the host GDB to communicate with it. |
96 | 604 |
97 To use a TCP connection instead of a serial line: | 605 To use a TCP connection instead of a serial line: |
98 | 606 |
99 target> gdbserver host:2345 emacs foo.txt | 607 target> gdbserver host:2345 emacs foo.txt |
100 | 608 |
101 The only difference from the previous example is the first argument, | 609 The only difference from the previous example is the first argument, |
102 specifying that you are communicating with the host GDB via TCP. The | 610 specifying that you are communicating with the host GDB via TCP. The |
103 `host:2345' argument means that `gdbserver' is to expect a TCP | 611 `host:2345' argument means that `gdbserver' is to expect a TCP |
104 connection from machine `host' to local TCP port 2345. (Currently, the | 612 connection from machine `host' to local TCP port 2345. (Currently, the |
105 `host' part is ignored.) You can choose any number you want for the | 613 `host' part is ignored.) You can choose any number you want for the |
106 port number as long as it does not conflict with any TCP ports already | 614 port number as long as it does not conflict with any TCP ports already |
107 in use on the target system (for example, `23' is reserved for | 615 in use on the target system (for example, `23' is reserved for |
108 `telnet').(1) You must use the same port number with the host GDB | 616 `telnet').(1) You must use the same port number with the host GDB |
109 `target remote' command. | 617 `target remote' command. |
110 | 618 |
| 619 The `stdio' connection is useful when starting `gdbserver' with ssh: |
| 620 |
| 621 (gdb) target remote | ssh -T hostname gdbserver - hello |
| 622 |
| 623 The `-T' option to ssh is provided because we don't need a remote |
| 624 pty, and we don't want escape-character handling. Ssh does this by |
| 625 default when a command is provided, the flag is provided to make it |
| 626 explicit. You could elide it if you want to. |
| 627 |
| 628 Programs started with stdio-connected gdbserver have `/dev/null' for |
| 629 `stdin', and `stdout',`stderr' are sent back to gdb for display through |
| 630 a pipe connected to gdbserver. Both `stdout' and `stderr' use the same |
| 631 pipe. |
| 632 |
111 20.3.1.1 Attaching to a Running Program | 633 20.3.1.1 Attaching to a Running Program |
112 ....................................... | 634 ....................................... |
113 | 635 |
114 On some targets, `gdbserver' can also attach to running programs. This | 636 On some targets, `gdbserver' can also attach to running programs. This |
115 is accomplished via the `--attach' argument. The syntax is: | 637 is accomplished via the `--attach' argument. The syntax is: |
116 | 638 |
117 target> gdbserver --attach COMM PID | 639 target> gdbserver --attach COMM PID |
118 | 640 |
119 PID is the process ID of a currently running process. It isn't | 641 PID is the process ID of a currently running process. It isn't |
120 necessary to point `gdbserver' at a binary for the running process. | 642 necessary to point `gdbserver' at a binary for the running process. |
(...skipping 421 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
542 storage-address' `__thread' | 1064 storage-address' `__thread' |
543 variables | 1065 variables |
544 `get-thread-information-block-address'`qGetTIBAddr' Display | 1066 `get-thread-information-block-address'`qGetTIBAddr' Display |
545 MS-Windows Thread | 1067 MS-Windows Thread |
546 Information Block. | 1068 Information Block. |
547 `search-memory' `qSearch:memory' `find' | 1069 `search-memory' `qSearch:memory' `find' |
548 `supported-packets' `qSupported' Remote | 1070 `supported-packets' `qSupported' Remote |
549 communications | 1071 communications |
550 parameters | 1072 parameters |
551 `pass-signals' `QPassSignals' `handle SIGNAL' | 1073 `pass-signals' `QPassSignals' `handle SIGNAL' |
| 1074 `program-signals' `QProgramSignals' `handle SIGNAL' |
552 `hostio-close-packet'`vFile:close' `remote get', | 1075 `hostio-close-packet'`vFile:close' `remote get', |
553 `remote put' | 1076 `remote put' |
554 `hostio-open-packet' `vFile:open' `remote get', | 1077 `hostio-open-packet' `vFile:open' `remote get', |
555 `remote put' | 1078 `remote put' |
556 `hostio-pread-packet'`vFile:pread' `remote get', | 1079 `hostio-pread-packet'`vFile:pread' `remote get', |
557 `remote put' | 1080 `remote put' |
558 `hostio-pwrite-packet'`vFile:pwrite' `remote get', | 1081 `hostio-pwrite-packet'`vFile:pwrite' `remote get', |
559 `remote put' | 1082 `remote put' |
560 `hostio-unlink-packet'`vFile:unlink' `remote delete' | 1083 `hostio-unlink-packet'`vFile:unlink' `remote delete' |
| 1084 `hostio-readlink-packet'`vFile:readlink' Host I/O |
561 `noack-packet' `QStartNoAckMode' Packet | 1085 `noack-packet' `QStartNoAckMode' Packet |
562 acknowledgment | 1086 acknowledgment |
563 `osdata' `qXfer:osdata:read' `info os' | 1087 `osdata' `qXfer:osdata:read' `info os' |
564 `query-attached' `qAttached' Querying remote | 1088 `query-attached' `qAttached' Querying remote |
565 process attach | 1089 process attach |
566 state. | 1090 state. |
567 `traceframe-info' `qXfer:traceframe-info:read'Traceframe info | 1091 `traceframe-info' `qXfer:traceframe-info:read'Traceframe info |
568 `install-in-trace' `InstallInTrace' Install | 1092 `install-in-trace' `InstallInTrace' Install |
569 tracepoint in | 1093 tracepoint in |
570 tracing | 1094 tracing |
571 `disable-randomization'`QDisableRandomization' `set | 1095 `disable-randomization'`QDisableRandomization' `set |
572 disable-randomization' | 1096 disable-randomization' |
| 1097 `conditional-breakpoints-packet'`Z0 and Z1' `Support for |
| 1098 target-side |
| 1099 breakpoint |
| 1100 condition |
| 1101 evaluation' |
573 | 1102 |
574 | 1103 |
575 File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Deb
ugging | 1104 File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Deb
ugging |
576 | 1105 |
577 20.5 Implementing a Remote Stub | 1106 20.5 Implementing a Remote Stub |
578 =============================== | 1107 =============================== |
579 | 1108 |
580 The stub files provided with GDB implement the target side of the | 1109 The stub files provided with GDB implement the target side of the |
581 communication protocol, and the GDB side is implemented in the GDB | 1110 communication protocol, and the GDB side is implemented in the GDB |
582 source file `remote.c'. Normally, you can simply allow these | 1111 source file `remote.c'. Normally, you can simply allow these |
(...skipping 73 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
656 File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub | 1185 File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub |
657 | 1186 |
658 20.5.1 What the Stub Can Do for You | 1187 20.5.1 What the Stub Can Do for You |
659 ----------------------------------- | 1188 ----------------------------------- |
660 | 1189 |
661 The debugging stub for your architecture supplies these three | 1190 The debugging stub for your architecture supplies these three |
662 subroutines: | 1191 subroutines: |
663 | 1192 |
664 `set_debug_traps' | 1193 `set_debug_traps' |
665 This routine arranges for `handle_exception' to run when your | 1194 This routine arranges for `handle_exception' to run when your |
666 program stops. You must call this subroutine explicitly near the | 1195 program stops. You must call this subroutine explicitly in your |
667 beginning of your program. | 1196 program's startup code. |
668 | 1197 |
669 `handle_exception' | 1198 `handle_exception' |
670 This is the central workhorse, but your program never calls it | 1199 This is the central workhorse, but your program never calls it |
671 explicitly--the setup code arranges for `handle_exception' to run | 1200 explicitly--the setup code arranges for `handle_exception' to run |
672 when a trap is triggered. | 1201 when a trap is triggered. |
673 | 1202 |
674 `handle_exception' takes control when your program stops during | 1203 `handle_exception' takes control when your program stops during |
675 execution (for example, on a breakpoint), and mediates | 1204 execution (for example, on a breakpoint), and mediates |
676 communications with GDB on the host machine. This is where the | 1205 communications with GDB on the host machine. This is where the |
677 communications protocol is implemented; `handle_exception' acts as | 1206 communications protocol is implemented; `handle_exception' acts as |
(...skipping 107 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
785 ------------------------------ | 1314 ------------------------------ |
786 | 1315 |
787 In summary, when your program is ready to debug, you must follow these | 1316 In summary, when your program is ready to debug, you must follow these |
788 steps. | 1317 steps. |
789 | 1318 |
790 1. Make sure you have defined the supporting low-level routines | 1319 1. Make sure you have defined the supporting low-level routines |
791 (*note What You Must Do for the Stub: Bootstrapping.): | 1320 (*note What You Must Do for the Stub: Bootstrapping.): |
792 `getDebugChar', `putDebugChar', | 1321 `getDebugChar', `putDebugChar', |
793 `flush_i_cache', `memset', `exceptionHandler'. | 1322 `flush_i_cache', `memset', `exceptionHandler'. |
794 | 1323 |
795 2. Insert these lines near the top of your program: | 1324 2. Insert these lines in your program's startup code, before the main |
| 1325 procedure is called: |
796 | 1326 |
797 set_debug_traps(); | 1327 set_debug_traps(); |
798 breakpoint(); | 1328 breakpoint(); |
799 | 1329 |
| 1330 On some machines, when a breakpoint trap is raised, the hardware |
| 1331 automatically makes the PC point to the instruction after the |
| 1332 breakpoint. If your machine doesn't do that, you may need to |
| 1333 adjust `handle_exception' to arrange for it to return to the |
| 1334 instruction after the breakpoint on this first invocation, so that |
| 1335 your program doesn't keep hitting the initial breakpoint instead |
| 1336 of making progress. |
| 1337 |
800 3. For the 680x0 stub only, you need to provide a variable called | 1338 3. For the 680x0 stub only, you need to provide a variable called |
801 `exceptionHook'. Normally you just use: | 1339 `exceptionHook'. Normally you just use: |
802 | 1340 |
803 void (*exceptionHook)() = 0; | 1341 void (*exceptionHook)() = 0; |
804 | 1342 |
805 but if before calling `set_debug_traps', you set it to point to a | 1343 but if before calling `set_debug_traps', you set it to point to a |
806 function in your program, that function is called when `GDB' | 1344 function in your program, that function is called when `GDB' |
807 continues after stopping on a trap (for example, bus error). The | 1345 continues after stopping on a trap (for example, bus error). The |
808 function indicated by `exceptionHook' is called with one | 1346 function indicated by `exceptionHook' is called with one |
809 parameter: an `int' which is the exception number. | 1347 parameter: an `int' which is the exception number. |
(...skipping 893 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1703 about acceptable commands. | 2241 about acceptable commands. |
1704 | 2242 |
1705 * Menu: | 2243 * Menu: |
1706 | 2244 |
1707 * ARM:: ARM RDI | 2245 * ARM:: ARM RDI |
1708 * M32R/D:: Renesas M32R/D | 2246 * M32R/D:: Renesas M32R/D |
1709 * M68K:: Motorola M68K | 2247 * M68K:: Motorola M68K |
1710 * MicroBlaze:: Xilinx MicroBlaze | 2248 * MicroBlaze:: Xilinx MicroBlaze |
1711 * MIPS Embedded:: MIPS Embedded | 2249 * MIPS Embedded:: MIPS Embedded |
1712 * OpenRISC 1000:: OpenRisc 1000 | 2250 * OpenRISC 1000:: OpenRisc 1000 |
| 2251 * PowerPC Embedded:: PowerPC Embedded |
1713 * PA:: HP PA Embedded | 2252 * PA:: HP PA Embedded |
1714 * PowerPC Embedded:: PowerPC Embedded | |
1715 * Sparclet:: Tsqware Sparclet | 2253 * Sparclet:: Tsqware Sparclet |
1716 * Sparclite:: Fujitsu Sparclite | 2254 * Sparclite:: Fujitsu Sparclite |
1717 * Z8000:: Zilog Z8000 | 2255 * Z8000:: Zilog Z8000 |
1718 * AVR:: Atmel AVR | 2256 * AVR:: Atmel AVR |
1719 * CRIS:: CRIS | 2257 * CRIS:: CRIS |
1720 * Super-H:: Renesas Super-H | 2258 * Super-H:: Renesas Super-H |
1721 | 2259 |
1722 | 2260 |
1723 File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors | 2261 File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors |
1724 | 2262 |
(...skipping 248 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1973 Show MicroBlaze-specific debugging level. | 2511 Show MicroBlaze-specific debugging level. |
1974 | 2512 |
1975 | 2513 |
1976 File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze,
Up: Embedded Processors | 2514 File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze,
Up: Embedded Processors |
1977 | 2515 |
1978 21.3.5 MIPS Embedded | 2516 21.3.5 MIPS Embedded |
1979 -------------------- | 2517 -------------------- |
1980 | 2518 |
1981 GDB can use the MIPS remote debugging protocol to talk to a MIPS board | 2519 GDB can use the MIPS remote debugging protocol to talk to a MIPS board |
1982 attached to a serial line. This is available when you configure GDB | 2520 attached to a serial line. This is available when you configure GDB |
1983 with `--target=mips-idt-ecoff'. | 2521 with `--target=mips-elf'. |
1984 | 2522 |
1985 Use these GDB commands to specify the connection to your target | 2523 Use these GDB commands to specify the connection to your target |
1986 board: | 2524 board: |
1987 | 2525 |
1988 `target mips PORT' | 2526 `target mips PORT' |
1989 To run a program on the board, start up `gdb' with the name of | 2527 To run a program on the board, start up `gdb' with the name of |
1990 your program as the argument. To connect to the board, use the | 2528 your program as the argument. To connect to the board, use the |
1991 command `target mips PORT', where PORT is the name of the serial | 2529 command `target mips PORT', where PORT is the name of the serial |
1992 port connected to the board. If the program has not already been | 2530 port connected to the board. If the program has not already been |
1993 downloaded to the board, you may use the `load' command to | 2531 downloaded to the board, you may use the `load' command to |
(...skipping 61 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2055 `set retransmit-timeout SECONDS' | 2593 `set retransmit-timeout SECONDS' |
2056 `show timeout' | 2594 `show timeout' |
2057 `show retransmit-timeout' | 2595 `show retransmit-timeout' |
2058 You can control the timeout used while waiting for a packet, in | 2596 You can control the timeout used while waiting for a packet, in |
2059 the MIPS remote protocol, with the `set timeout SECONDS' command. | 2597 the MIPS remote protocol, with the `set timeout SECONDS' command. |
2060 The default is 5 seconds. Similarly, you can control the timeout | 2598 The default is 5 seconds. Similarly, you can control the timeout |
2061 used while waiting for an acknowledgment of a packet with the `set | 2599 used while waiting for an acknowledgment of a packet with the `set |
2062 retransmit-timeout SECONDS' command. The default is 3 seconds. | 2600 retransmit-timeout SECONDS' command. The default is 3 seconds. |
2063 You can inspect both values with `show timeout' and `show | 2601 You can inspect both values with `show timeout' and `show |
2064 retransmit-timeout'. (These commands are _only_ available when | 2602 retransmit-timeout'. (These commands are _only_ available when |
2065 GDB is configured for `--target=mips-idt-ecoff'.) | 2603 GDB is configured for `--target=mips-elf'.) |
2066 | 2604 |
2067 The timeout set by `set timeout' does not apply when GDB is | 2605 The timeout set by `set timeout' does not apply when GDB is |
2068 waiting for your program to stop. In that case, GDB waits forever | 2606 waiting for your program to stop. In that case, GDB waits forever |
2069 because it has no way of knowing how long the program is going to | 2607 because it has no way of knowing how long the program is going to |
2070 run before stopping. | 2608 run before stopping. |
2071 | 2609 |
2072 `set syn-garbage-limit NUM' | 2610 `set syn-garbage-limit NUM' |
2073 Limit the maximum number of characters GDB should ignore when it | 2611 Limit the maximum number of characters GDB should ignore when it |
2074 tries to synchronize with the remote target. The default is 10 | 2612 tries to synchronize with the remote target. The default is 10 |
2075 characters. Setting the limit to -1 means there's no limit. | 2613 characters. Setting the limit to -1 means there's no limit. |
(...skipping 25 matching lines...) Expand all Loading... |
2101 PMON monitor for breakpoint commands. | 2639 PMON monitor for breakpoint commands. |
2102 | 2640 |
2103 `show monitor-warnings' | 2641 `show monitor-warnings' |
2104 Show the current setting of printing monitor warnings. | 2642 Show the current setting of printing monitor warnings. |
2105 | 2643 |
2106 `pmon COMMAND' | 2644 `pmon COMMAND' |
2107 This command allows sending an arbitrary COMMAND string to the | 2645 This command allows sending an arbitrary COMMAND string to the |
2108 monitor. The monitor must be in debug mode for this to work. | 2646 monitor. The monitor must be in debug mode for this to work. |
2109 | 2647 |
2110 | 2648 |
2111 File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embe
dded Processors | 2649 File: gdb.info, Node: OpenRISC 1000, Next: PowerPC Embedded, Prev: MIPS Embed
ded, Up: Embedded Processors |
2112 | 2650 |
2113 21.3.6 OpenRISC 1000 | 2651 21.3.6 OpenRISC 1000 |
2114 -------------------- | 2652 -------------------- |
2115 | 2653 |
2116 See OR1k Architecture document (`www.opencores.org') for more | 2654 See OR1k Architecture document (`www.opencores.org') for more |
2117 information about platform and commands. | 2655 information about platform and commands. |
2118 | 2656 |
2119 `target jtag jtag://HOST:PORT' | 2657 `target jtag jtag://HOST:PORT' |
2120 Connects to remote JTAG server. JTAG remote server can be either | 2658 Connects to remote JTAG server. JTAG remote server can be either |
2121 an or1ksim or JTAG server, connected via parallel port to the | 2659 an or1ksim or JTAG server, connected via parallel port to the |
(...skipping 84 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2206 Prints trace buffer, using current record configuration. | 2744 Prints trace buffer, using current record configuration. |
2207 | 2745 |
2208 `htrace mode continuous' | 2746 `htrace mode continuous' |
2209 Set continuous trace mode. | 2747 Set continuous trace mode. |
2210 | 2748 |
2211 `htrace mode suspend' | 2749 `htrace mode suspend' |
2212 Set suspend trace mode. | 2750 Set suspend trace mode. |
2213 | 2751 |
2214 | 2752 |
2215 | 2753 |
2216 File: gdb.info, Node: PowerPC Embedded, Next: Sparclet, Prev: PA, Up: Embedd
ed Processors | 2754 File: gdb.info, Node: PowerPC Embedded, Next: PA, Prev: OpenRISC 1000, Up: E
mbedded Processors |
2217 | 2755 |
2218 21.3.7 PowerPC Embedded | 2756 21.3.7 PowerPC Embedded |
2219 ----------------------- | 2757 ----------------------- |
2220 | 2758 |
2221 GDB supports using the DVC (Data Value Compare) register to implement | 2759 GDB supports using the DVC (Data Value Compare) register to implement |
2222 in hardware simple hardware watchpoint conditions of the form: | 2760 in hardware simple hardware watchpoint conditions of the form: |
2223 | 2761 |
2224 (gdb) watch ADDRESS|VARIABLE \ | 2762 (gdb) watch ADDRESS|VARIABLE \ |
2225 if ADDRESS|VARIABLE == CONSTANT EXPRESSION | 2763 if ADDRESS|VARIABLE == CONSTANT EXPRESSION |
2226 | 2764 |
(...skipping 75 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2302 Set the timeout for SDS protocol reads to be NSEC seconds. The | 2840 Set the timeout for SDS protocol reads to be NSEC seconds. The |
2303 default is 2 seconds. | 2841 default is 2 seconds. |
2304 | 2842 |
2305 `show sdstimeout' | 2843 `show sdstimeout' |
2306 Show the current value of the SDS timeout. | 2844 Show the current value of the SDS timeout. |
2307 | 2845 |
2308 `sds COMMAND' | 2846 `sds COMMAND' |
2309 Send the specified COMMAND string to the SDS monitor. | 2847 Send the specified COMMAND string to the SDS monitor. |
2310 | 2848 |
2311 | 2849 |
2312 File: gdb.info, Node: PA, Next: PowerPC Embedded, Prev: OpenRISC 1000, Up: E
mbedded Processors | 2850 File: gdb.info, Node: PA, Next: Sparclet, Prev: PowerPC Embedded, Up: Embedd
ed Processors |
2313 | 2851 |
2314 21.3.8 HP PA Embedded | 2852 21.3.8 HP PA Embedded |
2315 --------------------- | 2853 --------------------- |
2316 | 2854 |
2317 `target op50n DEV' | 2855 `target op50n DEV' |
2318 OP50N monitor, running on an OKI HPPA board. | 2856 OP50N monitor, running on an OKI HPPA board. |
2319 | 2857 |
2320 `target w89k DEV' | 2858 `target w89k DEV' |
2321 W89K monitor, running on a Winbond HPPA board. | 2859 W89K monitor, running on a Winbond HPPA board. |
2322 | 2860 |
2323 | 2861 |
2324 | 2862 |
2325 File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PowerPC Embedded, Up:
Embedded Processors | 2863 File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PA, Up: Embedded Proc
essors |
2326 | 2864 |
2327 21.3.9 Tsqware Sparclet | 2865 21.3.9 Tsqware Sparclet |
2328 ----------------------- | 2866 ----------------------- |
2329 | 2867 |
2330 GDB enables developers to debug tasks running on Sparclet targets from | 2868 GDB enables developers to debug tasks running on Sparclet targets from |
2331 a Unix host. GDB uses code that runs on both the Unix host and on the | 2869 a Unix host. GDB uses code that runs on both the Unix host and on the |
2332 Sparclet target. The program `gdb' is installed and executed on the | 2870 Sparclet target. The program `gdb' is installed and executed on the |
2333 Unix host. | 2871 Unix host. |
2334 | 2872 |
2335 `remotetimeout ARGS' | 2873 `remotetimeout ARGS' |
(...skipping 213 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2549 | 3087 |
2550 | 3088 |
2551 File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors | 3089 File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors |
2552 | 3090 |
2553 21.3.14 Renesas Super-H | 3091 21.3.14 Renesas Super-H |
2554 ----------------------- | 3092 ----------------------- |
2555 | 3093 |
2556 For the Renesas Super-H processor, GDB provides these commands: | 3094 For the Renesas Super-H processor, GDB provides these commands: |
2557 | 3095 |
2558 `regs' | 3096 `regs' |
| 3097 This command is deprecated, and `info all-registers' should be |
| 3098 used instead. |
| 3099 |
2559 Show the values of all Super-H registers. | 3100 Show the values of all Super-H registers. |
2560 | 3101 |
2561 `set sh calling-convention CONVENTION' | 3102 `set sh calling-convention CONVENTION' |
2562 Set the calling-convention used when calling functions from GDB. | 3103 Set the calling-convention used when calling functions from GDB. |
2563 Allowed values are `gcc', which is the default setting, and | 3104 Allowed values are `gcc', which is the default setting, and |
2564 `renesas'. With the `gcc' setting, functions are called using the | 3105 `renesas'. With the `gcc' setting, functions are called using the |
2565 GCC calling convention. If the DWARF-2 information of the called | 3106 GCC calling convention. If the DWARF-2 information of the called |
2566 function specifies that the function follows the Renesas calling | 3107 function specifies that the function follows the Renesas calling |
2567 convention, the function is called using the Renesas calling | 3108 convention, the function is called using the Renesas calling |
2568 convention. If the calling convention is set to `renesas', the | 3109 convention. If the calling convention is set to `renesas', the |
(...skipping 11 matching lines...) Expand all Loading... |
2580 | 3121 |
2581 21.4 Architectures | 3122 21.4 Architectures |
2582 ================== | 3123 ================== |
2583 | 3124 |
2584 This section describes characteristics of architectures that affect all | 3125 This section describes characteristics of architectures that affect all |
2585 uses of GDB with the architecture, both native and cross. | 3126 uses of GDB with the architecture, both native and cross. |
2586 | 3127 |
2587 * Menu: | 3128 * Menu: |
2588 | 3129 |
2589 * i386:: | 3130 * i386:: |
2590 * A29K:: | |
2591 * Alpha:: | 3131 * Alpha:: |
2592 * MIPS:: | 3132 * MIPS:: |
2593 * HPPA:: HP PA architecture | 3133 * HPPA:: HP PA architecture |
2594 * SPU:: Cell Broadband Engine SPU architecture | 3134 * SPU:: Cell Broadband Engine SPU architecture |
2595 * PowerPC:: | 3135 * PowerPC:: |
2596 | 3136 |
2597 | 3137 |
2598 File: gdb.info, Node: i386, Next: A29K, Up: Architectures | 3138 File: gdb.info, Node: i386, Next: Alpha, Up: Architectures |
2599 | 3139 |
2600 21.4.1 x86 Architecture-specific Issues | 3140 21.4.1 x86 Architecture-specific Issues |
2601 --------------------------------------- | 3141 --------------------------------------- |
2602 | 3142 |
2603 `set struct-convention MODE' | 3143 `set struct-convention MODE' |
2604 Set the convention used by the inferior to return `struct's and | 3144 Set the convention used by the inferior to return `struct's and |
2605 `union's from functions to MODE. Possible values of MODE are | 3145 `union's from functions to MODE. Possible values of MODE are |
2606 `"pcc"', `"reg"', and `"default"' (the default). `"default"' or | 3146 `"pcc"', `"reg"', and `"default"' (the default). `"default"' or |
2607 `"pcc"' means that `struct's are returned on the stack, while | 3147 `"pcc"' means that `struct's are returned on the stack, while |
2608 `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4, | 3148 `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4, |
2609 or 8 bytes will be returned in a register. | 3149 or 8 bytes will be returned in a register. |
2610 | 3150 |
2611 `show struct-convention' | 3151 `show struct-convention' |
2612 Show the current setting of the convention to return `struct's | 3152 Show the current setting of the convention to return `struct's |
2613 from functions. | 3153 from functions. |
2614 | 3154 |
2615 | 3155 |
2616 File: gdb.info, Node: A29K, Next: Alpha, Prev: i386, Up: Architectures | 3156 File: gdb.info, Node: Alpha, Next: MIPS, Prev: i386, Up: Architectures |
2617 | 3157 |
2618 21.4.2 A29K | 3158 21.4.2 Alpha |
2619 ----------- | |
2620 | |
2621 `set rstack_high_address ADDRESS' | |
2622 On AMD 29000 family processors, registers are saved in a separate | |
2623 "register stack". There is no way for GDB to determine the extent | |
2624 of this stack. Normally, GDB just assumes that the stack is | |
2625 "large enough". This may result in GDB referencing memory | |
2626 locations that do not exist. If necessary, you can get around | |
2627 this problem by specifying the ending address of the register | |
2628 stack with the `set rstack_high_address' command. The argument | |
2629 should be an address, which you probably want to precede with `0x' | |
2630 to specify in hexadecimal. | |
2631 | |
2632 `show rstack_high_address' | |
2633 Display the current limit of the register stack, on AMD 29000 | |
2634 family processors. | |
2635 | |
2636 | |
2637 | |
2638 File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures | |
2639 | |
2640 21.4.3 Alpha | |
2641 ------------ | 3159 ------------ |
2642 | 3160 |
2643 See the following section. | 3161 See the following section. |
2644 | 3162 |
2645 | 3163 |
2646 File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures | 3164 File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures |
2647 | 3165 |
2648 21.4.4 MIPS | 3166 21.4.3 MIPS |
2649 ----------- | 3167 ----------- |
2650 | 3168 |
2651 Alpha- and MIPS-based computers use an unusual stack frame, which | 3169 Alpha- and MIPS-based computers use an unusual stack frame, which |
2652 sometimes requires GDB to search backward in the object code to find | 3170 sometimes requires GDB to search backward in the object code to find |
2653 the beginning of a function. | 3171 the beginning of a function. |
2654 | 3172 |
2655 To improve response time (especially for embedded applications, where | 3173 To improve response time (especially for embedded applications, where |
2656 GDB may be restricted to a slow serial line for this search) you may | 3174 GDB may be restricted to a slow serial line for this search) you may |
2657 want to limit the size of this search, using one of these commands: | 3175 want to limit the size of this search, using one of these commands: |
2658 | 3176 |
(...skipping 30 matching lines...) Expand all Loading... |
2689 | 3207 |
2690 `n64' | 3208 `n64' |
2691 | 3209 |
2692 `eabi32' | 3210 `eabi32' |
2693 | 3211 |
2694 `eabi64' | 3212 `eabi64' |
2695 | 3213 |
2696 `show mips abi' | 3214 `show mips abi' |
2697 Show the MIPS ABI used by GDB to debug the inferior. | 3215 Show the MIPS ABI used by GDB to debug the inferior. |
2698 | 3216 |
| 3217 `set mips compression ARG' |
| 3218 Tell GDB which MIPS compressed ISA (Instruction Set Architecture) |
| 3219 encoding is used by the inferior. GDB uses this for code |
| 3220 disassembly and other internal interpretation purposes. This |
| 3221 setting is only referred to when no executable has been associated |
| 3222 with the debugging session or the executable does not provide |
| 3223 information about the encoding it uses. Otherwise this setting is |
| 3224 automatically updated from information provided by the executable. |
| 3225 |
| 3226 Possible values of ARG are `mips16' and `micromips'. The default |
| 3227 compressed ISA encoding is `mips16', as executables containing |
| 3228 MIPS16 code frequently are not identified as such. |
| 3229 |
| 3230 This setting is "sticky"; that is, it retains its value across |
| 3231 debugging sessions until reset either explicitly with this command |
| 3232 or implicitly from an executable. |
| 3233 |
| 3234 The compiler and/or assembler typically add symbol table |
| 3235 annotations to identify functions compiled for the MIPS16 or |
| 3236 microMIPS ISAs. If these function-scope annotations are present, |
| 3237 GDB uses them in preference to the global compressed ISA encoding |
| 3238 setting. |
| 3239 |
| 3240 `show mips compression' |
| 3241 Show the MIPS compressed ISA encoding used by GDB to debug the |
| 3242 inferior. |
| 3243 |
2699 `set mipsfpu' | 3244 `set mipsfpu' |
2700 `show mipsfpu' | 3245 `show mipsfpu' |
2701 *Note set mipsfpu: MIPS Embedded. | 3246 *Note set mipsfpu: MIPS Embedded. |
2702 | 3247 |
2703 `set mips mask-address ARG' | 3248 `set mips mask-address ARG' |
2704 This command determines whether the most-significant 32 bits of | 3249 This command determines whether the most-significant 32 bits of |
2705 64-bit MIPS addresses are masked off. The argument ARG can be | 3250 64-bit MIPS addresses are masked off. The argument ARG can be |
2706 `on', `off', or `auto'. The latter is the default setting, which | 3251 `on', `off', or `auto'. The latter is the default setting, which |
2707 lets GDB determine the correct value. | 3252 lets GDB determine the correct value. |
2708 | 3253 |
(...skipping 14 matching lines...) Expand all Loading... |
2723 `set debug mips' | 3268 `set debug mips' |
2724 This command turns on and off debugging messages for the | 3269 This command turns on and off debugging messages for the |
2725 MIPS-specific target code in GDB. | 3270 MIPS-specific target code in GDB. |
2726 | 3271 |
2727 `show debug mips' | 3272 `show debug mips' |
2728 Show the current setting of MIPS debugging messages. | 3273 Show the current setting of MIPS debugging messages. |
2729 | 3274 |
2730 | 3275 |
2731 File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures | 3276 File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures |
2732 | 3277 |
2733 21.4.5 HPPA | 3278 21.4.4 HPPA |
2734 ----------- | 3279 ----------- |
2735 | 3280 |
2736 When GDB is debugging the HP PA architecture, it provides the following | 3281 When GDB is debugging the HP PA architecture, it provides the following |
2737 special commands: | 3282 special commands: |
2738 | 3283 |
2739 `set debug hppa' | 3284 `set debug hppa' |
2740 This command determines whether HPPA architecture-specific | 3285 This command determines whether HPPA architecture-specific |
2741 debugging messages are to be displayed. | 3286 debugging messages are to be displayed. |
2742 | 3287 |
2743 `show debug hppa' | 3288 `show debug hppa' |
2744 Show whether HPPA debugging messages are displayed. | 3289 Show whether HPPA debugging messages are displayed. |
2745 | 3290 |
2746 `maint print unwind ADDRESS' | 3291 `maint print unwind ADDRESS' |
2747 This command displays the contents of the unwind table entry at the | 3292 This command displays the contents of the unwind table entry at the |
2748 given ADDRESS. | 3293 given ADDRESS. |
2749 | 3294 |
2750 | 3295 |
2751 | 3296 |
2752 File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures | 3297 File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures |
2753 | 3298 |
2754 21.4.6 Cell Broadband Engine SPU architecture | 3299 21.4.5 Cell Broadband Engine SPU architecture |
2755 --------------------------------------------- | 3300 --------------------------------------------- |
2756 | 3301 |
2757 When GDB is debugging the Cell Broadband Engine SPU architecture, it | 3302 When GDB is debugging the Cell Broadband Engine SPU architecture, it |
2758 provides the following special commands: | 3303 provides the following special commands: |
2759 | 3304 |
2760 `info spu event' | 3305 `info spu event' |
2761 Display SPU event facility status. Shows current event mask and | 3306 Display SPU event facility status. Shows current event mask and |
2762 pending event status. | 3307 pending event status. |
2763 | 3308 |
2764 `info spu signal' | 3309 `info spu signal' |
(...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2802 accessed via the cache. If an application does not use the | 3347 accessed via the cache. If an application does not use the |
2803 software-managed cache, this option has no effect. | 3348 software-managed cache, this option has no effect. |
2804 | 3349 |
2805 `show spu auto-flush-cache' | 3350 `show spu auto-flush-cache' |
2806 Show whether to automatically flush the software-managed cache. | 3351 Show whether to automatically flush the software-managed cache. |
2807 | 3352 |
2808 | 3353 |
2809 | 3354 |
2810 File: gdb.info, Node: PowerPC, Prev: SPU, Up: Architectures | 3355 File: gdb.info, Node: PowerPC, Prev: SPU, Up: Architectures |
2811 | 3356 |
2812 21.4.7 PowerPC | 3357 21.4.6 PowerPC |
2813 -------------- | 3358 -------------- |
2814 | 3359 |
2815 When GDB is debugging the PowerPC architecture, it provides a set of | 3360 When GDB is debugging the PowerPC architecture, it provides a set of |
2816 pseudo-registers to enable inspection of 128-bit wide Decimal Floating | 3361 pseudo-registers to enable inspection of 128-bit wide Decimal Floating |
2817 Point numbers stored in the floating point registers. These values must | 3362 Point numbers stored in the floating point registers. These values must |
2818 be stored in two consecutive registers, always starting at an even | 3363 be stored in two consecutive registers, always starting at an even |
2819 register like `f0' or `f2'. | 3364 register like `f0' or `f2'. |
2820 | 3365 |
2821 The pseudo-registers go from `$dl0' through `$dl15', and are formed | 3366 The pseudo-registers go from `$dl0' through `$dl15', and are formed |
2822 by joining the even/odd register pairs `f0' and `f1' for `$dl0', `f2' | 3367 by joining the even/odd register pairs `f0' and `f1' for `$dl0', `f2' |
(...skipping 13 matching lines...) Expand all Loading... |
2836 Print Settings: Print Settings. Other settings are described here. | 3381 Print Settings: Print Settings. Other settings are described here. |
2837 | 3382 |
2838 * Menu: | 3383 * Menu: |
2839 | 3384 |
2840 * Prompt:: Prompt | 3385 * Prompt:: Prompt |
2841 * Editing:: Command editing | 3386 * Editing:: Command editing |
2842 * Command History:: Command history | 3387 * Command History:: Command history |
2843 * Screen Size:: Screen size | 3388 * Screen Size:: Screen size |
2844 * Numbers:: Numbers | 3389 * Numbers:: Numbers |
2845 * ABI:: Configuring the current ABI | 3390 * ABI:: Configuring the current ABI |
| 3391 * Auto-loading:: Automatically loading associated files |
2846 * Messages/Warnings:: Optional warnings and messages | 3392 * Messages/Warnings:: Optional warnings and messages |
2847 * Debugging Output:: Optional messages about internal happenings | 3393 * Debugging Output:: Optional messages about internal happenings |
2848 * Other Misc Settings:: Other Miscellaneous Settings | 3394 * Other Misc Settings:: Other Miscellaneous Settings |
2849 | 3395 |
2850 | 3396 |
2851 File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB | 3397 File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB |
2852 | 3398 |
2853 22.1 Prompt | 3399 22.1 Prompt |
2854 =========== | 3400 =========== |
2855 | 3401 |
(...skipping 241 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3097 | 3643 |
3098 `set radix [BASE]' | 3644 `set radix [BASE]' |
3099 `show radix' | 3645 `show radix' |
3100 These commands set and show the default base for both input and | 3646 These commands set and show the default base for both input and |
3101 output of numbers. `set radix' sets the radix of input and output | 3647 output of numbers. `set radix' sets the radix of input and output |
3102 to the same base; without an argument, it resets the radix back to | 3648 to the same base; without an argument, it resets the radix back to |
3103 its default value of 10. | 3649 its default value of 10. |
3104 | 3650 |
3105 | 3651 |
3106 | 3652 |
3107 File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Contr
olling GDB | 3653 File: gdb.info, Node: ABI, Next: Auto-loading, Prev: Numbers, Up: Controllin
g GDB |
3108 | 3654 |
3109 22.6 Configuring the Current ABI | 3655 22.6 Configuring the Current ABI |
3110 ================================ | 3656 ================================ |
3111 | 3657 |
3112 GDB can determine the "ABI" (Application Binary Interface) of your | 3658 GDB can determine the "ABI" (Application Binary Interface) of your |
3113 application automatically. However, sometimes you need to override its | 3659 application automatically. However, sometimes you need to override its |
3114 conclusions. Use these commands to manage GDB's view of the current | 3660 conclusions. Use these commands to manage GDB's view of the current |
3115 ABI. | 3661 ABI. |
3116 | 3662 |
3117 One GDB configuration can debug binaries for multiple operating | 3663 One GDB configuration can debug binaries for multiple operating |
(...skipping 52 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3170 Show the C++ ABI currently in use. | 3716 Show the C++ ABI currently in use. |
3171 | 3717 |
3172 `set cp-abi' | 3718 `set cp-abi' |
3173 With no argument, show the list of supported C++ ABI's. | 3719 With no argument, show the list of supported C++ ABI's. |
3174 | 3720 |
3175 `set cp-abi ABI' | 3721 `set cp-abi ABI' |
3176 `set cp-abi auto' | 3722 `set cp-abi auto' |
3177 Set the current C++ ABI to ABI, or return to automatic detection. | 3723 Set the current C++ ABI to ABI, or return to automatic detection. |
3178 | 3724 |
3179 | 3725 |
3180 File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI,
Up: Controlling GDB | 3726 File: gdb.info, Node: Auto-loading, Next: Messages/Warnings, Prev: ABI, Up:
Controlling GDB |
3181 | 3727 |
3182 22.7 Optional Warnings and Messages | 3728 22.7 Automatically loading associated files |
| 3729 =========================================== |
| 3730 |
| 3731 GDB sometimes reads files with commands and settings automatically, |
| 3732 without being explicitly told so by the user. We call this feature |
| 3733 "auto-loading". While auto-loading is useful for automatically adapting |
| 3734 GDB to the needs of your project, it can sometimes produce unexpected |
| 3735 results or introduce security risks (e.g., if the file comes from |
| 3736 untrusted sources). |
| 3737 |
| 3738 Note that loading of these associated files (including the local |
| 3739 `.gdbinit' file) requires accordingly configured `auto-load safe-path' |
| 3740 (*note Auto-loading safe path::). |
| 3741 |
| 3742 For these reasons, GDB includes commands and options to let you |
| 3743 control when to auto-load files and which files should be auto-loaded. |
| 3744 |
| 3745 `set auto-load off' |
| 3746 Globally disable loading of all auto-loaded files. You may want |
| 3747 to use this command with the `-iex' option (*note Option |
| 3748 -init-eval-command::) such as: |
| 3749 $ gdb -iex "set auto-load off" untrusted-executable corefile |
| 3750 |
| 3751 Be aware that system init file (*note System-wide configuration::) |
| 3752 and init files from your home directory (*note Home Directory Init |
| 3753 File::) still get read (as they come from generally trusted |
| 3754 directories). To prevent GDB from auto-loading even those init |
| 3755 files, use the `-nx' option (*note Mode Options::), in addition to |
| 3756 `set auto-load no'. |
| 3757 |
| 3758 `show auto-load' |
| 3759 Show whether auto-loading of each specific `auto-load' file(s) is |
| 3760 enabled or disabled. |
| 3761 |
| 3762 (gdb) show auto-load |
| 3763 gdb-scripts: Auto-loading of canned sequences of commands scripts is
on. |
| 3764 libthread-db: Auto-loading of inferior specific libthread_db is on. |
| 3765 local-gdbinit: Auto-loading of .gdbinit script from current directory |
| 3766 is on. |
| 3767 python-scripts: Auto-loading of Python scripts is on. |
| 3768 safe-path: List of directories from which it is safe to auto-load fil
es |
| 3769 is $debugdir:$datadir/auto-load. |
| 3770 scripts-directory: List of directories from which to load auto-loaded
scripts |
| 3771 is $debugdir:$datadir/auto-load. |
| 3772 |
| 3773 `info auto-load' |
| 3774 Print whether each specific `auto-load' file(s) have been |
| 3775 auto-loaded or not. |
| 3776 |
| 3777 (gdb) info auto-load |
| 3778 gdb-scripts: |
| 3779 Loaded Script |
| 3780 Yes /home/user/gdb/gdb-gdb.gdb |
| 3781 libthread-db: No auto-loaded libthread-db. |
| 3782 local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been |
| 3783 loaded. |
| 3784 python-scripts: |
| 3785 Loaded Script |
| 3786 Yes /home/user/gdb/gdb-gdb.py |
| 3787 |
| 3788 These are various kinds of files GDB can automatically load: |
| 3789 |
| 3790 * *Note objfile-gdb.py file::, controlled by *Note set auto-load |
| 3791 python-scripts::. |
| 3792 |
| 3793 * *Note objfile-gdb.gdb file::, controlled by *Note set auto-load |
| 3794 gdb-scripts::. |
| 3795 |
| 3796 * *Note dotdebug_gdb_scripts section::, controlled by *Note set |
| 3797 auto-load python-scripts::. |
| 3798 |
| 3799 * *Note Init File in the Current Directory::, controlled by *Note |
| 3800 set auto-load local-gdbinit::. |
| 3801 |
| 3802 * *Note libthread_db.so.1 file::, controlled by *Note set auto-load |
| 3803 libthread-db::. |
| 3804 |
| 3805 These are GDB control commands for the auto-loading: |
| 3806 |
| 3807 *Note set auto-load off::. Disable auto-loading globally. |
| 3808 *Note show auto-load::. Show setting of all kinds of files. |
| 3809 *Note info auto-load::. Show state of all kinds of files. |
| 3810 *Note set auto-load gdb-scripts::. Control for GDB command scripts. |
| 3811 *Note show auto-load gdb-scripts::. Show setting of GDB command scripts. |
| 3812 *Note info auto-load gdb-scripts::. Show state of GDB command scripts. |
| 3813 *Note set auto-load Control for GDB Python scripts. |
| 3814 python-scripts::. |
| 3815 *Note show auto-load Show setting of GDB Python scripts. |
| 3816 python-scripts::. |
| 3817 *Note info auto-load Show state of GDB Python scripts. |
| 3818 python-scripts::. |
| 3819 *Note set auto-load Control for GDB auto-loaded scripts |
| 3820 scripts-directory::. location. |
| 3821 *Note show auto-load Show GDB auto-loaded scripts |
| 3822 scripts-directory::. location. |
| 3823 *Note set auto-load local-gdbinit::. Control for init file in the |
| 3824 current directory. |
| 3825 *Note show auto-load Show setting of init file in the |
| 3826 local-gdbinit::. current directory. |
| 3827 *Note info auto-load Show state of init file in the |
| 3828 local-gdbinit::. current directory. |
| 3829 *Note set auto-load libthread-db::. Control for thread debugging |
| 3830 library. |
| 3831 *Note show auto-load libthread-db::. Show setting of thread debugging |
| 3832 library. |
| 3833 *Note info auto-load libthread-db::. Show state of thread debugging |
| 3834 library. |
| 3835 *Note set auto-load safe-path::. Control directories trusted for |
| 3836 automatic loading. |
| 3837 *Note show auto-load safe-path::. Show directories trusted for |
| 3838 automatic loading. |
| 3839 *Note add-auto-load-safe-path::. Add directory trusted for automatic |
| 3840 loading. |
| 3841 |
| 3842 * Menu: |
| 3843 |
| 3844 * Init File in the Current Directory:: `set/show/info auto-load local-gdbinit' |
| 3845 * libthread_db.so.1 file:: `set/show/info auto-load libthread-db' |
| 3846 * objfile-gdb.gdb file:: `set/show/info auto-load gdb-script' |
| 3847 * Auto-loading safe path:: `set/show/info auto-load safe-path' |
| 3848 * Auto-loading verbose mode:: `set/show debug auto-load' |
| 3849 *Note Python Auto-loading::. |
| 3850 |
| 3851 |
| 3852 File: gdb.info, Node: Init File in the Current Directory, Next: libthread_db.s
o.1 file, Up: Auto-loading |
| 3853 |
| 3854 22.7.1 Automatically loading init file in the current directory |
| 3855 --------------------------------------------------------------- |
| 3856 |
| 3857 By default, GDB reads and executes the canned sequences of commands |
| 3858 from init file (if any) in the current working directory, see *Note |
| 3859 Init File in the Current Directory during Startup::. |
| 3860 |
| 3861 Note that loading of this local `.gdbinit' file also requires |
| 3862 accordingly configured `auto-load safe-path' (*note Auto-loading safe |
| 3863 path::). |
| 3864 |
| 3865 `set auto-load local-gdbinit [on|off]' |
| 3866 Enable or disable the auto-loading of canned sequences of commands |
| 3867 (*note Sequences::) found in init file in the current directory. |
| 3868 |
| 3869 `show auto-load local-gdbinit' |
| 3870 Show whether auto-loading of canned sequences of commands from |
| 3871 init file in the current directory is enabled or disabled. |
| 3872 |
| 3873 `info auto-load local-gdbinit' |
| 3874 Print whether canned sequences of commands from init file in the |
| 3875 current directory have been auto-loaded. |
| 3876 |
| 3877 |
| 3878 File: gdb.info, Node: libthread_db.so.1 file, Next: objfile-gdb.gdb file, Pre
v: Init File in the Current Directory, Up: Auto-loading |
| 3879 |
| 3880 22.7.2 Automatically loading thread debugging library |
| 3881 ----------------------------------------------------- |
| 3882 |
| 3883 This feature is currently present only on GNU/Linux native hosts. |
| 3884 |
| 3885 GDB reads in some cases thread debugging library from places specific |
| 3886 to the inferior (*note set libthread-db-search-path::). |
| 3887 |
| 3888 The special `libthread-db-search-path' entry `$sdir' is processed |
| 3889 without checking this `set auto-load libthread-db' switch as system |
| 3890 libraries have to be trusted in general. In all other cases of |
| 3891 `libthread-db-search-path' entries GDB checks first if `set auto-load |
| 3892 libthread-db' is enabled before trying to open such thread debugging |
| 3893 library. |
| 3894 |
| 3895 Note that loading of this debugging library also requires |
| 3896 accordingly configured `auto-load safe-path' (*note Auto-loading safe |
| 3897 path::). |
| 3898 |
| 3899 `set auto-load libthread-db [on|off]' |
| 3900 Enable or disable the auto-loading of inferior specific thread |
| 3901 debugging library. |
| 3902 |
| 3903 `show auto-load libthread-db' |
| 3904 Show whether auto-loading of inferior specific thread debugging |
| 3905 library is enabled or disabled. |
| 3906 |
| 3907 `info auto-load libthread-db' |
| 3908 Print the list of all loaded inferior specific thread debugging |
| 3909 libraries and for each such library print list of inferior PIDs |
| 3910 using it. |
| 3911 |
| 3912 |
| 3913 File: gdb.info, Node: objfile-gdb.gdb file, Next: Auto-loading safe path, Pre
v: libthread_db.so.1 file, Up: Auto-loading |
| 3914 |
| 3915 22.7.3 The `OBJFILE-gdb.gdb' file |
| 3916 --------------------------------- |
| 3917 |
| 3918 GDB tries to load an `OBJFILE-gdb.gdb' file containing canned sequences |
| 3919 of commands (*note Sequences::), as long as `set auto-load gdb-scripts' |
| 3920 is set to `on'. |
| 3921 |
| 3922 Note that loading of this script file also requires accordingly |
| 3923 configured `auto-load safe-path' (*note Auto-loading safe path::). |
| 3924 |
| 3925 For more background refer to the similar Python scripts auto-loading |
| 3926 description (*note objfile-gdb.py file::). |
| 3927 |
| 3928 `set auto-load gdb-scripts [on|off]' |
| 3929 Enable or disable the auto-loading of canned sequences of commands |
| 3930 scripts. |
| 3931 |
| 3932 `show auto-load gdb-scripts' |
| 3933 Show whether auto-loading of canned sequences of commands scripts |
| 3934 is enabled or disabled. |
| 3935 |
| 3936 `info auto-load gdb-scripts [REGEXP]' |
| 3937 Print the list of all canned sequences of commands scripts that |
| 3938 GDB auto-loaded. |
| 3939 |
| 3940 If REGEXP is supplied only canned sequences of commands scripts with |
| 3941 matching names are printed. |
| 3942 |
| 3943 |
| 3944 File: gdb.info, Node: Auto-loading safe path, Next: Auto-loading verbose mode,
Prev: objfile-gdb.gdb file, Up: Auto-loading |
| 3945 |
| 3946 22.7.4 Security restriction for auto-loading |
| 3947 -------------------------------------------- |
| 3948 |
| 3949 As the files of inferior can come from untrusted source (such as |
| 3950 submitted by an application user) GDB does not always load any files |
| 3951 automatically. GDB provides the `set auto-load safe-path' setting to |
| 3952 list directories trusted for loading files not explicitly requested by |
| 3953 user. Each directory can also be a shell wildcard pattern. |
| 3954 |
| 3955 If the path is not set properly you will see a warning and the file |
| 3956 will not get loaded: |
| 3957 |
| 3958 $ ./gdb -q ./gdb |
| 3959 Reading symbols from /home/user/gdb/gdb...done. |
| 3960 warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been |
| 3961 declined by your `auto-load safe-path' set |
| 3962 to "$debugdir:$datadir/auto-load". |
| 3963 warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been |
| 3964 declined by your `auto-load safe-path' set |
| 3965 to "$debugdir:$datadir/auto-load". |
| 3966 |
| 3967 The list of trusted directories is controlled by the following |
| 3968 commands: |
| 3969 |
| 3970 `set auto-load safe-path [DIRECTORIES]' |
| 3971 Set the list of directories (and their subdirectories) trusted for |
| 3972 automatic loading and execution of scripts. You can also enter a |
| 3973 specific trusted file. Each directory can also be a shell |
| 3974 wildcard pattern; wildcards do not match directory separator - see |
| 3975 `FNM_PATHNAME' for system function `fnmatch' (*note fnmatch: |
| 3976 (libc)Wildcard Matching.). If you omit DIRECTORIES, `auto-load |
| 3977 safe-path' will be reset to its default value as specified during |
| 3978 GDB compilation. |
| 3979 |
| 3980 The list of directories uses path separator (`:' on GNU and Unix |
| 3981 systems, `;' on MS-Windows and MS-DOS) to separate directories, |
| 3982 similarly to the `PATH' environment variable. |
| 3983 |
| 3984 `show auto-load safe-path' |
| 3985 Show the list of directories trusted for automatic loading and |
| 3986 execution of scripts. |
| 3987 |
| 3988 `add-auto-load-safe-path' |
| 3989 Add an entry (or list of entries) the list of directories trusted |
| 3990 for automatic loading and execution of scripts. Multiple entries |
| 3991 may be delimited by the host platform path separator in use. |
| 3992 |
| 3993 This variable defaults to what `--with-auto-load-dir' has been |
| 3994 configured to (*note with-auto-load-dir::). `$debugdir' and `$datadir' |
| 3995 substitution applies the same as for *Note set auto-load |
| 3996 scripts-directory::. The default `set auto-load safe-path' value can |
| 3997 be also overriden by GDB configuration option |
| 3998 `--with-auto-load-safe-path'. |
| 3999 |
| 4000 Setting this variable to `/' disables this security protection, |
| 4001 corresponding GDB configuration option is |
| 4002 `--without-auto-load-safe-path'. This variable is supposed to be set |
| 4003 to the system directories writable by the system superuser only. Users |
| 4004 can add their source directories in init files in their home |
| 4005 directories (*note Home Directory Init File::). See also deprecated |
| 4006 init file in the current directory (*note Init File in the Current |
| 4007 Directory during Startup::). |
| 4008 |
| 4009 To force GDB to load the files it declined to load in the previous |
| 4010 example, you could use one of the following ways: |
| 4011 |
| 4012 `~/.gdbinit': `add-auto-load-safe-path ~/src/gdb' |
| 4013 Specify this trusted directory (or a file) as additional component |
| 4014 of the list. You have to specify also any existing directories |
| 4015 displayed by by `show auto-load safe-path' (such as `/usr:/bin' in |
| 4016 this example). |
| 4017 |
| 4018 `gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" ...' |
| 4019 Specify this directory as in the previous case but just for a |
| 4020 single GDB session. |
| 4021 |
| 4022 `gdb -iex "set auto-load safe-path /" ...' |
| 4023 Disable auto-loading safety for a single GDB session. This |
| 4024 assumes all the files you debug during this GDB session will come |
| 4025 from trusted sources. |
| 4026 |
| 4027 `./configure --without-auto-load-safe-path' |
| 4028 During compilation of GDB you may disable any auto-loading safety. |
| 4029 This assumes all the files you will ever debug with this GDB come |
| 4030 from trusted sources. |
| 4031 |
| 4032 On the other hand you can also explicitly forbid automatic files |
| 4033 loading which also suppresses any such warning messages: |
| 4034 |
| 4035 `gdb -iex "set auto-load no" ...' |
| 4036 You can use GDB command-line option for a single GDB session. |
| 4037 |
| 4038 `~/.gdbinit': `set auto-load no' |
| 4039 Disable auto-loading globally for the user (*note Home Directory |
| 4040 Init File::). While it is improbable, you could also use system |
| 4041 init file instead (*note System-wide configuration::). |
| 4042 |
| 4043 This setting applies to the file names as entered by user. If no |
| 4044 entry matches GDB tries as a last resort to also resolve all the file |
| 4045 names into their canonical form (typically resolving symbolic links) |
| 4046 and compare the entries again. GDB already canonicalizes most of the |
| 4047 filenames on its own before starting the comparison so a canonical form |
| 4048 of directories is recommended to be entered. |
| 4049 |
| 4050 |
| 4051 File: gdb.info, Node: Auto-loading verbose mode, Prev: Auto-loading safe path,
Up: Auto-loading |
| 4052 |
| 4053 22.7.5 Displaying files tried for auto-load |
| 4054 ------------------------------------------- |
| 4055 |
| 4056 For better visibility of all the file locations where you can place |
| 4057 scripts to be auto-loaded with inferior -- or to protect yourself |
| 4058 against accidental execution of untrusted scripts -- GDB provides a |
| 4059 feature for printing all the files attempted to be loaded. Both |
| 4060 existing and non-existing files may be printed. |
| 4061 |
| 4062 For example the list of directories from which it is safe to |
| 4063 auto-load files (*note Auto-loading safe path::) applies also to |
| 4064 canonicalized filenames which may not be too obvious while setting it |
| 4065 up. |
| 4066 |
| 4067 (gdb) set debug auto-load on |
| 4068 (gdb) file ~/src/t/true |
| 4069 auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" |
| 4070 for objfile "/tmp/true". |
| 4071 auto-load: Updating directories of "/usr:/opt". |
| 4072 auto-load: Using directory "/usr". |
| 4073 auto-load: Using directory "/opt". |
| 4074 warning: File "/tmp/true-gdb.gdb" auto-loading has been declined |
| 4075 by your `auto-load safe-path' set to "/usr:/opt". |
| 4076 |
| 4077 `set debug auto-load [on|off]' |
| 4078 Set whether to print the filenames attempted to be auto-loaded. |
| 4079 |
| 4080 `show debug auto-load' |
| 4081 Show whether printing of the filenames attempted to be auto-loaded |
| 4082 is turned on or off. |
| 4083 |
| 4084 |
| 4085 File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: Auto-l
oading, Up: Controlling GDB |
| 4086 |
| 4087 22.8 Optional Warnings and Messages |
3183 =================================== | 4088 =================================== |
3184 | 4089 |
3185 By default, GDB is silent about its inner workings. If you are running | 4090 By default, GDB is silent about its inner workings. If you are running |
3186 on a slow machine, you may want to use the `set verbose' command. This | 4091 on a slow machine, you may want to use the `set verbose' command. This |
3187 makes GDB tell you when it does a lengthy internal operation, so you | 4092 makes GDB tell you when it does a lengthy internal operation, so you |
3188 will not think it has crashed. | 4093 will not think it has crashed. |
3189 | 4094 |
3190 Currently, the messages controlled by `set verbose' are those which | 4095 Currently, the messages controlled by `set verbose' are those which |
3191 announce that the symbol table for a source file is being read; see | 4096 announce that the symbol table for a source file is being read; see |
3192 `symbol-file' in *Note Commands to Specify Files: Files. | 4097 `symbol-file' in *Note Commands to Specify Files: Files. |
(...skipping 55 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3248 | 4153 |
3249 `set trace-commands off' | 4154 `set trace-commands off' |
3250 Disable command tracing. | 4155 Disable command tracing. |
3251 | 4156 |
3252 `show trace-commands' | 4157 `show trace-commands' |
3253 Display the current state of command tracing. | 4158 Display the current state of command tracing. |
3254 | 4159 |
3255 | 4160 |
3256 File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Mess
ages/Warnings, Up: Controlling GDB | 4161 File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Mess
ages/Warnings, Up: Controlling GDB |
3257 | 4162 |
3258 22.8 Optional Messages about Internal Happenings | 4163 22.9 Optional Messages about Internal Happenings |
3259 ================================================ | 4164 ================================================ |
3260 | 4165 |
3261 GDB has commands that enable optional debugging messages from various | 4166 GDB has commands that enable optional debugging messages from various |
3262 GDB subsystems; normally these commands are of interest to GDB | 4167 GDB subsystems; normally these commands are of interest to GDB |
3263 maintainers, or when reporting a bug. This section documents those | 4168 maintainers, or when reporting a bug. This section documents those |
3264 commands. | 4169 commands. |
3265 | 4170 |
3266 `set exec-done-display' | 4171 `set exec-done-display' |
3267 Turns on or off the notification of asynchronous commands' | 4172 Turns on or off the notification of asynchronous commands' |
3268 completion. When on, GDB will print a message when an | 4173 completion. When on, GDB will print a message when an |
(...skipping 28 matching lines...) Expand all Loading... |
3297 `show debug check-physname' | 4202 `show debug check-physname' |
3298 Show the current state of "physname" checking. | 4203 Show the current state of "physname" checking. |
3299 | 4204 |
3300 `set debug dwarf2-die' | 4205 `set debug dwarf2-die' |
3301 Dump DWARF2 DIEs after they are read in. The value is the number | 4206 Dump DWARF2 DIEs after they are read in. The value is the number |
3302 of nesting levels to print. A value of zero turns off the display. | 4207 of nesting levels to print. A value of zero turns off the display. |
3303 | 4208 |
3304 `show debug dwarf2-die' | 4209 `show debug dwarf2-die' |
3305 Show the current state of DWARF2 DIE debugging. | 4210 Show the current state of DWARF2 DIE debugging. |
3306 | 4211 |
| 4212 `set debug dwarf2-read' |
| 4213 Turns on or off display of debugging messages related to reading |
| 4214 DWARF debug info. The default is off. |
| 4215 |
| 4216 `show debug dwarf2-read' |
| 4217 Show the current state of DWARF2 reader debugging. |
| 4218 |
3307 `set debug displaced' | 4219 `set debug displaced' |
3308 Turns on or off display of GDB debugging info for the displaced | 4220 Turns on or off display of GDB debugging info for the displaced |
3309 stepping support. The default is off. | 4221 stepping support. The default is off. |
3310 | 4222 |
3311 `show debug displaced' | 4223 `show debug displaced' |
3312 Displays the current state of displaying GDB debugging info | 4224 Displays the current state of displaying GDB debugging info |
3313 related to displaced stepping. | 4225 related to displaced stepping. |
3314 | 4226 |
3315 `set debug event' | 4227 `set debug event' |
3316 Turns on or off display of GDB event debugging info. The default | 4228 Turns on or off display of GDB event debugging info. The default |
(...skipping 85 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3402 `show debug serial' | 4314 `show debug serial' |
3403 Displays the current state of displaying GDB serial debugging info. | 4315 Displays the current state of displaying GDB serial debugging info. |
3404 | 4316 |
3405 `set debug solib-frv' | 4317 `set debug solib-frv' |
3406 Turns on or off debugging messages for FR-V shared-library code. | 4318 Turns on or off debugging messages for FR-V shared-library code. |
3407 | 4319 |
3408 `show debug solib-frv' | 4320 `show debug solib-frv' |
3409 Display the current state of FR-V shared-library code debugging | 4321 Display the current state of FR-V shared-library code debugging |
3410 messages. | 4322 messages. |
3411 | 4323 |
| 4324 `set debug symtab-create' |
| 4325 Turns on or off display of debugging messages related to symbol |
| 4326 table creation. The default is off. |
| 4327 |
| 4328 `show debug symtab-create' |
| 4329 Show the current state of symbol table creation debugging. |
| 4330 |
3412 `set debug target' | 4331 `set debug target' |
3413 Turns on or off display of GDB target debugging info. This info | 4332 Turns on or off display of GDB target debugging info. This info |
3414 includes what is going on at the target level of GDB, as it | 4333 includes what is going on at the target level of GDB, as it |
3415 happens. The default is 0. Set it to 1 to track events, and to 2 | 4334 happens. The default is 0. Set it to 1 to track events, and to 2 |
3416 to also track the value of large memory transfers. Changes to | 4335 to also track the value of large memory transfers. Changes to |
3417 this flag do not take effect until the next time you connect to a | 4336 this flag do not take effect until the next time you connect to a |
3418 target or use the `run' command. | 4337 target or use the `run' command. |
3419 | 4338 |
3420 `show debug target' | 4339 `show debug target' |
3421 Displays the current state of displaying GDB target debugging info. | 4340 Displays the current state of displaying GDB target debugging info. |
(...skipping 17 matching lines...) Expand all Loading... |
3439 | 4358 |
3440 `set debug xml' | 4359 `set debug xml' |
3441 Turns on or off debugging messages for built-in XML parsers. | 4360 Turns on or off debugging messages for built-in XML parsers. |
3442 | 4361 |
3443 `show debug xml' | 4362 `show debug xml' |
3444 Displays the current state of XML debugging messages. | 4363 Displays the current state of XML debugging messages. |
3445 | 4364 |
3446 | 4365 |
3447 File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Contro
lling GDB | 4366 File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Contro
lling GDB |
3448 | 4367 |
3449 22.9 Other Miscellaneous Settings | 4368 22.10 Other Miscellaneous Settings |
3450 ================================= | 4369 ================================== |
3451 | 4370 |
3452 `set interactive-mode' | 4371 `set interactive-mode' |
3453 If `on', forces GDB to assume that GDB was started in a terminal. | 4372 If `on', forces GDB to assume that GDB was started in a terminal. |
3454 In practice, this means that GDB should wait for the user to | 4373 In practice, this means that GDB should wait for the user to |
3455 answer queries generated by commands entered at the command | 4374 answer queries generated by commands entered at the command |
3456 prompt. If `off', forces GDB to operate in the opposite mode, and | 4375 prompt. If `off', forces GDB to operate in the opposite mode, and |
3457 it uses the default answers to all queries. If `auto' (the | 4376 it uses the default answers to all queries. If `auto' (the |
3458 default), GDB tries to determine whether its standard input is a | 4377 default), GDB tries to determine whether its standard input is a |
3459 terminal, and works in interactive-mode if it is, | 4378 terminal, and works in interactive-mode if it is, |
3460 non-interactively otherwise. | 4379 non-interactively otherwise. |
(...skipping 128 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3589 You may use the `document' command again to change the | 4508 You may use the `document' command again to change the |
3590 documentation of a command. Redefining the command with `define' | 4509 documentation of a command. Redefining the command with `define' |
3591 does not change the documentation. | 4510 does not change the documentation. |
3592 | 4511 |
3593 `dont-repeat' | 4512 `dont-repeat' |
3594 Used inside a user-defined command, this tells GDB that this | 4513 Used inside a user-defined command, this tells GDB that this |
3595 command should not be repeated when the user hits <RET> (*note | 4514 command should not be repeated when the user hits <RET> (*note |
3596 repeat last command: Command Syntax.). | 4515 repeat last command: Command Syntax.). |
3597 | 4516 |
3598 `help user-defined' | 4517 `help user-defined' |
3599 List all user-defined commands, with the first line of the | 4518 List all user-defined commands and all python commands defined in |
3600 documentation (if any) for each. | 4519 class COMAND_USER. The first line of the documentation or |
| 4520 docstring is included (if any). |
3601 | 4521 |
3602 `show user' | 4522 `show user' |
3603 `show user COMMANDNAME' | 4523 `show user COMMANDNAME' |
3604 Display the GDB commands used to define COMMANDNAME (but not its | 4524 Display the GDB commands used to define COMMANDNAME (but not its |
3605 documentation). If no COMMANDNAME is given, display the | 4525 documentation). If no COMMANDNAME is given, display the |
3606 definitions for all user-defined commands. | 4526 definitions for all user-defined commands. This does not work for |
| 4527 user-defined python commands. |
3607 | 4528 |
3608 `show max-user-call-depth' | 4529 `show max-user-call-depth' |
3609 `set max-user-call-depth' | 4530 `set max-user-call-depth' |
3610 The value of `max-user-call-depth' controls how many recursion | 4531 The value of `max-user-call-depth' controls how many recursion |
3611 levels are allowed in user-defined commands before GDB suspects an | 4532 levels are allowed in user-defined commands before GDB suspects an |
3612 infinite recursion and aborts the command. | 4533 infinite recursion and aborts the command. This does not apply to |
| 4534 user-defined python commands. |
3613 | 4535 |
3614 In addition to the above commands, user-defined commands frequently | 4536 In addition to the above commands, user-defined commands frequently |
3615 use control flow commands, described in *Note Command Files::. | 4537 use control flow commands, described in *Note Command Files::. |
3616 | 4538 |
3617 When user-defined commands are executed, the commands of the | 4539 When user-defined commands are executed, the commands of the |
3618 definition are not printed. An error in any command stops execution of | 4540 definition are not printed. An error in any command stops execution of |
3619 the user-defined command. | 4541 the user-defined command. |
3620 | 4542 |
3621 If used interactively, commands that would ask for confirmation | 4543 If used interactively, commands that would ask for confirmation |
3622 proceed without asking when used inside a user-defined command. Many | 4544 proceed without asking when used inside a user-defined command. Many |
(...skipping 321 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3944 Additionally, GDB commands and convenience functions which are | 4866 Additionally, GDB commands and convenience functions which are |
3945 written in Python and are located in the | 4867 written in Python and are located in the |
3946 `DATA-DIRECTORY/python/gdb/command' or | 4868 `DATA-DIRECTORY/python/gdb/command' or |
3947 `DATA-DIRECTORY/python/gdb/function' directories are automatically | 4869 `DATA-DIRECTORY/python/gdb/function' directories are automatically |
3948 imported when GDB starts. | 4870 imported when GDB starts. |
3949 | 4871 |
3950 * Menu: | 4872 * Menu: |
3951 | 4873 |
3952 * Python Commands:: Accessing Python from GDB. | 4874 * Python Commands:: Accessing Python from GDB. |
3953 * Python API:: Accessing GDB from Python. | 4875 * Python API:: Accessing GDB from Python. |
3954 * Auto-loading:: Automatically loading Python code. | 4876 * Python Auto-loading:: Automatically loading Python code. |
3955 * Python modules:: Python modules provided by GDB. | 4877 * Python modules:: Python modules provided by GDB. |
3956 | 4878 |
3957 | 4879 |
3958 File: gdb.info, Node: Python Commands, Next: Python API, Up: Python | 4880 File: gdb.info, Node: Python Commands, Next: Python API, Up: Python |
3959 | 4881 |
3960 23.2.1 Python Commands | 4882 23.2.1 Python Commands |
3961 ---------------------- | 4883 ---------------------- |
3962 | 4884 |
3963 GDB provides one command for accessing the Python interpreter, and one | 4885 GDB provides one command for accessing the Python interpreter, and one |
3964 related setting: | 4886 related setting: |
(...skipping 35 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4000 The script name must end with `.py' and GDB must be configured to | 4922 The script name must end with `.py' and GDB must be configured to |
4001 recognize the script language based on filename extension using | 4923 recognize the script language based on filename extension using |
4002 the `script-extension' setting. *Note Extending GDB: Extending | 4924 the `script-extension' setting. *Note Extending GDB: Extending |
4003 GDB. | 4925 GDB. |
4004 | 4926 |
4005 `python execfile ("script-name")' | 4927 `python execfile ("script-name")' |
4006 This method is based on the `execfile' Python built-in function, | 4928 This method is based on the `execfile' Python built-in function, |
4007 and thus is always available. | 4929 and thus is always available. |
4008 | 4930 |
4009 | 4931 |
4010 File: gdb.info, Node: Python API, Next: Auto-loading, Prev: Python Commands,
Up: Python | 4932 File: gdb.info, Node: Python API, Next: Python Auto-loading, Prev: Python Com
mands, Up: Python |
4011 | 4933 |
4012 23.2.2 Python API | 4934 23.2.2 Python API |
4013 ----------------- | 4935 ----------------- |
4014 | 4936 |
4015 At startup, GDB overrides Python's `sys.stdout' and `sys.stderr' to | 4937 At startup, GDB overrides Python's `sys.stdout' and `sys.stderr' to |
4016 print using GDB's output-paging streams. A Python program which | 4938 print using GDB's output-paging streams. A Python program which |
4017 outputs to one of these streams may have its output interrupted by the | 4939 outputs to one of these streams may have its output interrupted by the |
4018 user (*note Screen Size::). In this situation, a Python | 4940 user (*note Screen Size::). In this situation, a Python |
4019 `KeyboardInterrupt' exception is thrown. | 4941 `KeyboardInterrupt' exception is thrown. |
4020 | 4942 |
(...skipping 11 matching lines...) Expand all Loading... |
4032 * Threads In Python:: Accessing inferior threads from Python. | 4954 * Threads In Python:: Accessing inferior threads from Python. |
4033 * Commands In Python:: Implementing new commands in Python. | 4955 * Commands In Python:: Implementing new commands in Python. |
4034 * Parameters In Python:: Adding new GDB parameters. | 4956 * Parameters In Python:: Adding new GDB parameters. |
4035 * Functions In Python:: Writing new convenience functions. | 4957 * Functions In Python:: Writing new convenience functions. |
4036 * Progspaces In Python:: Program spaces. | 4958 * Progspaces In Python:: Program spaces. |
4037 * Objfiles In Python:: Object files. | 4959 * Objfiles In Python:: Object files. |
4038 * Frames In Python:: Accessing inferior stack frames from Python. | 4960 * Frames In Python:: Accessing inferior stack frames from Python. |
4039 * Blocks In Python:: Accessing frame blocks from Python. | 4961 * Blocks In Python:: Accessing frame blocks from Python. |
4040 * Symbols In Python:: Python representation of symbols. | 4962 * Symbols In Python:: Python representation of symbols. |
4041 * Symbol Tables In Python:: Python representation of symbol tables. | 4963 * Symbol Tables In Python:: Python representation of symbol tables. |
4042 * Lazy Strings In Python:: Python representation of lazy strings. | |
4043 * Breakpoints In Python:: Manipulating breakpoints using Python. | 4964 * Breakpoints In Python:: Manipulating breakpoints using Python. |
4044 * Finish Breakpoints in Python:: Setting Breakpoints on function return | 4965 * Finish Breakpoints in Python:: Setting Breakpoints on function return |
4045 using Python. | 4966 using Python. |
| 4967 * Lazy Strings In Python:: Python representation of lazy strings. |
4046 | 4968 |
4047 | 4969 |
4048 File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API | 4970 File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API |
4049 | 4971 |
4050 23.2.2.1 Basic Python | 4972 23.2.2.1 Basic Python |
4051 ..................... | 4973 ..................... |
4052 | 4974 |
4053 GDB introduces a new Python module, named `gdb'. All methods and | 4975 GDB introduces a new Python module, named `gdb'. All methods and |
4054 classes added by GDB are placed in this module. GDB automatically | 4976 classes added by GDB are placed in this module. GDB automatically |
4055 `import's the `gdb' module for use in all scripts evaluated by the | 4977 `import's the `gdb' module for use in all scripts evaluated by the |
(...skipping 50 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4106 Parse EXPRESSION as an expression in the current language, | 5028 Parse EXPRESSION as an expression in the current language, |
4107 evaluate it, and return the result as a `gdb.Value'. EXPRESSION | 5029 evaluate it, and return the result as a `gdb.Value'. EXPRESSION |
4108 must be a string. | 5030 must be a string. |
4109 | 5031 |
4110 This function can be useful when implementing a new command (*note | 5032 This function can be useful when implementing a new command (*note |
4111 Commands In Python::), as it provides a way to parse the command's | 5033 Commands In Python::), as it provides a way to parse the command's |
4112 argument as an expression. It is also useful simply to compute | 5034 argument as an expression. It is also useful simply to compute |
4113 values, for example, it is the only way to get the value of a | 5035 values, for example, it is the only way to get the value of a |
4114 convenience variable (*note Convenience Vars::) as a `gdb.Value'. | 5036 convenience variable (*note Convenience Vars::) as a `gdb.Value'. |
4115 | 5037 |
| 5038 -- Function: gdb.find_pc_line (pc) |
| 5039 Return the `gdb.Symtab_and_line' object corresponding to the PC |
| 5040 value. *Note Symbol Tables In Python::. If an invalid value of |
| 5041 PC is passed as an argument, then the `symtab' and `line' |
| 5042 attributes of the returned `gdb.Symtab_and_line' object will be |
| 5043 `None' and 0 respectively. |
| 5044 |
4116 -- Function: gdb.post_event (event) | 5045 -- Function: gdb.post_event (event) |
4117 Put EVENT, a callable object taking no arguments, into GDB's | 5046 Put EVENT, a callable object taking no arguments, into GDB's |
4118 internal event queue. This callable will be invoked at some later | 5047 internal event queue. This callable will be invoked at some later |
4119 point, during GDB's event processing. Events posted using | 5048 point, during GDB's event processing. Events posted using |
4120 `post_event' will be run in the order in which they were posted; | 5049 `post_event' will be run in the order in which they were posted; |
4121 however, there is no way to know when they will be processed | 5050 however, there is no way to know when they will be processed |
4122 relative to other events inside GDB. | 5051 relative to other events inside GDB. |
4123 | 5052 |
4124 GDB is not thread-safe. If your Python program uses multiple | 5053 GDB is not thread-safe. If your Python program uses multiple |
4125 threads, you must be careful to only call GDB-specific functions | 5054 threads, you must be careful to only call GDB-specific functions |
(...skipping 145 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4271 When implementing GDB commands in Python via `gdb.Command', it is | 5200 When implementing GDB commands in Python via `gdb.Command', it is |
4272 useful to be able to throw an exception that doesn't cause a traceback | 5201 useful to be able to throw an exception that doesn't cause a traceback |
4273 to be printed. For example, the user may have invoked the command | 5202 to be printed. For example, the user may have invoked the command |
4274 incorrectly. Use the `gdb.GdbError' exception to handle this case. | 5203 incorrectly. Use the `gdb.GdbError' exception to handle this case. |
4275 Example: | 5204 Example: |
4276 | 5205 |
4277 (gdb) python | 5206 (gdb) python |
4278 >class HelloWorld (gdb.Command): | 5207 >class HelloWorld (gdb.Command): |
4279 > """Greet the whole world.""" | 5208 > """Greet the whole world.""" |
4280 > def __init__ (self): | 5209 > def __init__ (self): |
4281 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) | 5210 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) |
4282 > def invoke (self, args, from_tty): | 5211 > def invoke (self, args, from_tty): |
4283 > argv = gdb.string_to_argv (args) | 5212 > argv = gdb.string_to_argv (args) |
4284 > if len (argv) != 0: | 5213 > if len (argv) != 0: |
4285 > raise gdb.GdbError ("hello-world takes no arguments") | 5214 > raise gdb.GdbError ("hello-world takes no arguments") |
4286 > print "Hello, World!" | 5215 > print "Hello, World!" |
4287 >HelloWorld () | 5216 >HelloWorld () |
4288 >end | 5217 >end |
4289 (gdb) hello-world 42 | 5218 (gdb) hello-world 42 |
4290 hello-world takes no arguments | 5219 hello-world takes no arguments |
4291 | 5220 |
(...skipping 132 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4424 int *foo; | 5353 int *foo; |
4425 | 5354 |
4426 then you can use the corresponding `gdb.Value' to access what | 5355 then you can use the corresponding `gdb.Value' to access what |
4427 `foo' points to like this: | 5356 `foo' points to like this: |
4428 | 5357 |
4429 bar = foo.dereference () | 5358 bar = foo.dereference () |
4430 | 5359 |
4431 The result `bar' will be a `gdb.Value' object holding the | 5360 The result `bar' will be a `gdb.Value' object holding the |
4432 value pointed to by `foo'. | 5361 value pointed to by `foo'. |
4433 | 5362 |
| 5363 A similar function `Value.referenced_value' exists which also |
| 5364 returns `gdb.Value' objects corresonding to the values |
| 5365 pointed to by pointer values (and additionally, values |
| 5366 referenced by reference values). However, the behavior of |
| 5367 `Value.dereference' differs from `Value.referenced_value' by |
| 5368 the fact that the behavior of `Value.dereference' is |
| 5369 identical to applying the C unary operator `*' on a given |
| 5370 value. For example, consider a reference to a pointer |
| 5371 `ptrref', declared in your C++ program as |
| 5372 |
| 5373 typedef int *intptr; |
| 5374 ... |
| 5375 int val = 10; |
| 5376 intptr ptr = &val; |
| 5377 intptr &ptrref = ptr; |
| 5378 |
| 5379 Though `ptrref' is a reference value, one can apply the method |
| 5380 `Value.dereference' to the `gdb.Value' object corresponding |
| 5381 to it and obtain a `gdb.Value' which is identical to that |
| 5382 corresponding to `val'. However, if you apply the method |
| 5383 `Value.referenced_value', the result would be a `gdb.Value' |
| 5384 object identical to that corresponding to `ptr'. |
| 5385 |
| 5386 py_ptrref = gdb.parse_and_eval ("ptrref") |
| 5387 py_val = py_ptrref.dereference () |
| 5388 py_ptr = py_ptrref.referenced_value () |
| 5389 |
| 5390 The `gdb.Value' object `py_val' is identical to that |
| 5391 corresponding to `val', and `py_ptr' is identical to that |
| 5392 corresponding to `ptr'. In general, `Value.dereference' can |
| 5393 be applied whenever the C unary operator `*' can be applied |
| 5394 to the corresponding C value. For those cases where applying |
| 5395 both `Value.dereference' and `Value.referenced_value' is |
| 5396 allowed, the results obtained need not be identical (as we |
| 5397 have seen in the above example). The results are however |
| 5398 identical when applied on `gdb.Value' objects corresponding |
| 5399 to pointers (`gdb.Value' objects with type code |
| 5400 `TYPE_CODE_PTR') in a C/C++ program. |
| 5401 |
| 5402 -- Function: Value.referenced_value () |
| 5403 For pointer or reference data types, this method returns a new |
| 5404 `gdb.Value' object corresponding to the value referenced by |
| 5405 the pointer/reference value. For pointer data types, |
| 5406 `Value.dereference' and `Value.referenced_value' produce |
| 5407 identical results. The difference between these methods is |
| 5408 that `Value.dereference' cannot get the values referenced by |
| 5409 reference values. For example, consider a reference to an |
| 5410 `int', declared in your C++ program as |
| 5411 |
| 5412 int val = 10; |
| 5413 int &ref = val; |
| 5414 |
| 5415 then applying `Value.dereference' to the `gdb.Value' object |
| 5416 corresponding to `ref' will result in an error, while applying |
| 5417 `Value.referenced_value' will result in a `gdb.Value' object |
| 5418 identical to that corresponding to `val'. |
| 5419 |
| 5420 py_ref = gdb.parse_and_eval ("ref") |
| 5421 er_ref = py_ref.dereference () # Results in error |
| 5422 py_val = py_ref.referenced_value () # Returns the referenced val
ue |
| 5423 |
| 5424 The `gdb.Value' object `py_val' is identical to that |
| 5425 corresponding to `val'. |
| 5426 |
4434 -- Function: Value.dynamic_cast (type) | 5427 -- Function: Value.dynamic_cast (type) |
4435 Like `Value.cast', but works as if the C++ `dynamic_cast' | 5428 Like `Value.cast', but works as if the C++ `dynamic_cast' |
4436 operator were used. Consult a C++ reference for details. | 5429 operator were used. Consult a C++ reference for details. |
4437 | 5430 |
4438 -- Function: Value.reinterpret_cast (type) | 5431 -- Function: Value.reinterpret_cast (type) |
4439 Like `Value.cast', but works as if the C++ `reinterpret_cast' | 5432 Like `Value.cast', but works as if the C++ `reinterpret_cast' |
4440 operator were used. Consult a C++ reference for details. | 5433 operator were used. Consult a C++ reference for details. |
4441 | 5434 |
4442 -- Function: Value.string ([encoding[, errors[, length]]]) | 5435 -- Function: Value.string ([encoding[, errors[, length]]]) |
4443 If this `gdb.Value' represents a string, then this method | 5436 If this `gdb.Value' represents a string, then this method |
(...skipping 492 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4936 printer can pretty-print, it will return a printer object. If not, it | 5929 printer can pretty-print, it will return a printer object. If not, it |
4937 returns `None'. | 5930 returns `None'. |
4938 | 5931 |
4939 We recommend that you put your core pretty-printers into a Python | 5932 We recommend that you put your core pretty-printers into a Python |
4940 package. If your pretty-printers are for use with a library, we | 5933 package. If your pretty-printers are for use with a library, we |
4941 further recommend embedding a version number into the package name. | 5934 further recommend embedding a version number into the package name. |
4942 This practice will enable GDB to load multiple versions of your | 5935 This practice will enable GDB to load multiple versions of your |
4943 pretty-printers at the same time, because they will have different | 5936 pretty-printers at the same time, because they will have different |
4944 names. | 5937 names. |
4945 | 5938 |
4946 You should write auto-loaded code (*note Auto-loading::) such that it | 5939 You should write auto-loaded code (*note Python Auto-loading::) such |
4947 can be evaluated multiple times without changing its meaning. An ideal | 5940 that it can be evaluated multiple times without changing its meaning. |
4948 auto-load file will consist solely of `import's of your printer | 5941 An ideal auto-load file will consist solely of `import's of your |
4949 modules, followed by a call to a register pretty-printers with the | 5942 printer modules, followed by a call to a register pretty-printers with |
4950 current objfile. | 5943 the current objfile. |
4951 | 5944 |
4952 Taken as a whole, this approach will scale nicely to multiple | 5945 Taken as a whole, this approach will scale nicely to multiple |
4953 inferiors, each potentially using a different library version. | 5946 inferiors, each potentially using a different library version. |
4954 Embedding a version number in the Python package name will ensure that | 5947 Embedding a version number in the Python package name will ensure that |
4955 GDB is able to load both sets of printers simultaneously. Then, | 5948 GDB is able to load both sets of printers simultaneously. Then, |
4956 because the search for pretty-printers is done by objfile, and because | 5949 because the search for pretty-printers is done by objfile, and because |
4957 your auto-loaded code took care to register your library's printers | 5950 your auto-loaded code took care to register your library's printers |
4958 with a specific objfile, GDB will find the correct printers for the | 5951 with a specific objfile, GDB will find the correct printers for the |
4959 specific version of the library used by each inferior. | 5952 specific version of the library used by each inferior. |
4960 | 5953 |
(...skipping 127 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5088 | 6081 |
5089 -- Function: Inferior.threads () | 6082 -- Function: Inferior.threads () |
5090 This method returns a tuple holding all the threads which are | 6083 This method returns a tuple holding all the threads which are |
5091 valid when it is called. If there are no valid threads, the | 6084 valid when it is called. If there are no valid threads, the |
5092 method will return an empty tuple. | 6085 method will return an empty tuple. |
5093 | 6086 |
5094 -- Function: Inferior.read_memory (address, length) | 6087 -- Function: Inferior.read_memory (address, length) |
5095 Read LENGTH bytes of memory from the inferior, starting at | 6088 Read LENGTH bytes of memory from the inferior, starting at |
5096 ADDRESS. Returns a buffer object, which behaves much like an | 6089 ADDRESS. Returns a buffer object, which behaves much like an |
5097 array or a string. It can be modified and given to the | 6090 array or a string. It can be modified and given to the |
5098 `gdb.write_memory' function. | 6091 `Inferior.write_memory' function. |
5099 | 6092 |
5100 -- Function: Inferior.write_memory (address, buffer [, length]) | 6093 -- Function: Inferior.write_memory (address, buffer [, length]) |
5101 Write the contents of BUFFER to the inferior, starting at | 6094 Write the contents of BUFFER to the inferior, starting at |
5102 ADDRESS. The BUFFER parameter must be a Python object which | 6095 ADDRESS. The BUFFER parameter must be a Python object which |
5103 supports the buffer protocol, i.e., a string, an array or the | 6096 supports the buffer protocol, i.e., a string, an array or the |
5104 object returned from `gdb.read_memory'. If given, LENGTH | 6097 object returned from `Inferior.read_memory'. If given, LENGTH |
5105 determines the number of bytes from BUFFER to be written. | 6098 determines the number of bytes from BUFFER to be written. |
5106 | 6099 |
5107 -- Function: Inferior.search_memory (address, length, pattern) | 6100 -- Function: Inferior.search_memory (address, length, pattern) |
5108 Search a region of the inferior memory starting at ADDRESS | 6101 Search a region of the inferior memory starting at ADDRESS |
5109 with the given LENGTH using the search pattern supplied in | 6102 with the given LENGTH using the search pattern supplied in |
5110 PATTERN. The PATTERN parameter must be a Python object which | 6103 PATTERN. The PATTERN parameter must be a Python object which |
5111 supports the buffer protocol, i.e., a string, an array or the | 6104 supports the buffer protocol, i.e., a string, an array or the |
5112 object returned from `gdb.read_memory'. Returns a Python | 6105 object returned from `gdb.read_memory'. Returns a Python |
5113 `Long' containing the address where the pattern was found, or | 6106 `Long' containing the address where the pattern was found, or |
5114 `None' if the pattern could not be found. | 6107 `None' if the pattern could not be found. |
(...skipping 339 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5454 `clear', and `delete' are in this category. Type `help | 6447 `clear', and `delete' are in this category. Type `help |
5455 breakpoints' at the GDB prompt to see a list of commands in this | 6448 breakpoints' at the GDB prompt to see a list of commands in this |
5456 category. | 6449 category. |
5457 | 6450 |
5458 `gdb.COMMAND_TRACEPOINTS' | 6451 `gdb.COMMAND_TRACEPOINTS' |
5459 The command has to do with tracepoints. For example, `trace', | 6452 The command has to do with tracepoints. For example, `trace', |
5460 `actions', and `tfind' are in this category. Type `help | 6453 `actions', and `tfind' are in this category. Type `help |
5461 tracepoints' at the GDB prompt to see a list of commands in this | 6454 tracepoints' at the GDB prompt to see a list of commands in this |
5462 category. | 6455 category. |
5463 | 6456 |
| 6457 `gdb.COMMAND_USER' |
| 6458 The command is a general purpose command for the user, and |
| 6459 typically does not fit in one of the other categories. Type `help |
| 6460 user-defined' at the GDB prompt to see a list of commands in this |
| 6461 category, as well as the list of gdb macros (*note Sequences::). |
| 6462 |
5464 `gdb.COMMAND_OBSCURE' | 6463 `gdb.COMMAND_OBSCURE' |
5465 The command is only used in unusual circumstances, or is not of | 6464 The command is only used in unusual circumstances, or is not of |
5466 general interest to users. For example, `checkpoint', `fork', and | 6465 general interest to users. For example, `checkpoint', `fork', and |
5467 `stop' are in this category. Type `help obscure' at the GDB | 6466 `stop' are in this category. Type `help obscure' at the GDB |
5468 prompt to see a list of commands in this category. | 6467 prompt to see a list of commands in this category. |
5469 | 6468 |
5470 `gdb.COMMAND_MAINTENANCE' | 6469 `gdb.COMMAND_MAINTENANCE' |
5471 The command is only useful to GDB maintainers. The `maintenance' | 6470 The command is only useful to GDB maintainers. The `maintenance' |
5472 and `flushregs' commands are in this category. Type `help | 6471 and `flushregs' commands are in this category. Type `help |
5473 internals' at the GDB prompt to see a list of commands in this | 6472 internals' at the GDB prompt to see a list of commands in this |
(...skipping 22 matching lines...) Expand all Loading... |
5496 This constant means that completion should be done using symbol | 6495 This constant means that completion should be done using symbol |
5497 names as the source. | 6496 names as the source. |
5498 | 6497 |
5499 The following code snippet shows how a trivial CLI command can be | 6498 The following code snippet shows how a trivial CLI command can be |
5500 implemented in Python: | 6499 implemented in Python: |
5501 | 6500 |
5502 class HelloWorld (gdb.Command): | 6501 class HelloWorld (gdb.Command): |
5503 """Greet the whole world.""" | 6502 """Greet the whole world.""" |
5504 | 6503 |
5505 def __init__ (self): | 6504 def __init__ (self): |
5506 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) | 6505 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) |
5507 | 6506 |
5508 def invoke (self, arg, from_tty): | 6507 def invoke (self, arg, from_tty): |
5509 print "Hello, World!" | 6508 print "Hello, World!" |
5510 | 6509 |
5511 HelloWorld () | 6510 HelloWorld () |
5512 | 6511 |
5513 The last line instantiates the class, and is necessary to trigger the | 6512 The last line instantiates the class, and is necessary to trigger the |
5514 registration of the command with GDB. Depending on how the Python code | 6513 registration of the command with GDB. Depending on how the Python code |
5515 is read into GDB, you may need to import the `gdb' module explicitly. | 6514 is read into GDB, you may need to import the `gdb' module explicitly. |
5516 | 6515 |
(...skipping 225 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5742 GDB loads symbols for an inferior from various symbol-containing files | 6741 GDB loads symbols for an inferior from various symbol-containing files |
5743 (*note Files::). These include the primary executable file, any shared | 6742 (*note Files::). These include the primary executable file, any shared |
5744 libraries used by the inferior, and any separate debug info files | 6743 libraries used by the inferior, and any separate debug info files |
5745 (*note Separate Debug Files::). GDB calls these symbol-containing | 6744 (*note Separate Debug Files::). GDB calls these symbol-containing |
5746 files "objfiles". | 6745 files "objfiles". |
5747 | 6746 |
5748 The following objfile-related functions are available in the `gdb' | 6747 The following objfile-related functions are available in the `gdb' |
5749 module: | 6748 module: |
5750 | 6749 |
5751 -- Function: gdb.current_objfile () | 6750 -- Function: gdb.current_objfile () |
5752 When auto-loading a Python script (*note Auto-loading::), GDB sets | 6751 When auto-loading a Python script (*note Python Auto-loading::), |
5753 the "current objfile" to the corresponding objfile. This function | 6752 GDB sets the "current objfile" to the corresponding objfile. This |
5754 returns the current objfile. If there is no current objfile, this | 6753 function returns the current objfile. If there is no current |
5755 function returns `None'. | 6754 objfile, this function returns `None'. |
5756 | 6755 |
5757 -- Function: gdb.objfiles () | 6756 -- Function: gdb.objfiles () |
5758 Return a sequence of all the objfiles current known to GDB. *Note | 6757 Return a sequence of all the objfiles current known to GDB. *Note |
5759 Objfiles In Python::. | 6758 Objfiles In Python::. |
5760 | 6759 |
5761 Each objfile is represented by an instance of the `gdb.Objfile' | 6760 Each objfile is represented by an instance of the `gdb.Objfile' |
5762 class. | 6761 class. |
5763 | 6762 |
5764 -- Variable: Objfile.filename | 6763 -- Variable: Objfile.filename |
5765 The file name of the objfile as a string. | 6764 The file name of the objfile as a string. |
(...skipping 180 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5946 23.2.2.17 Accessing frame blocks from Python. | 6945 23.2.2.17 Accessing frame blocks from Python. |
5947 ............................................. | 6946 ............................................. |
5948 | 6947 |
5949 Within each frame, GDB maintains information on each block stored in | 6948 Within each frame, GDB maintains information on each block stored in |
5950 that frame. These blocks are organized hierarchically, and are | 6949 that frame. These blocks are organized hierarchically, and are |
5951 represented individually in Python as a `gdb.Block'. Please see *Note | 6950 represented individually in Python as a `gdb.Block'. Please see *Note |
5952 Frames In Python::, for a more in-depth discussion on frames. | 6951 Frames In Python::, for a more in-depth discussion on frames. |
5953 Furthermore, see *Note Examining the Stack: Stack, for more detailed | 6952 Furthermore, see *Note Examining the Stack: Stack, for more detailed |
5954 technical information on GDB's book-keeping of the stack. | 6953 technical information on GDB's book-keeping of the stack. |
5955 | 6954 |
| 6955 A `gdb.Block' is iterable. The iterator returns the symbols (*note |
| 6956 Symbols In Python::) local to the block. Python programs should not |
| 6957 assume that a specific block object will always contain a given symbol, |
| 6958 since changes in GDB features and infrastructure may cause symbols move |
| 6959 across blocks in a symbol table. |
| 6960 |
5956 The following block-related functions are available in the `gdb' | 6961 The following block-related functions are available in the `gdb' |
5957 module: | 6962 module: |
5958 | 6963 |
5959 -- Function: gdb.block_for_pc (pc) | 6964 -- Function: gdb.block_for_pc (pc) |
5960 Return the `gdb.Block' containing the given PC value. If the | 6965 Return the `gdb.Block' containing the given PC value. If the |
5961 block cannot be found for the PC value specified, the function | 6966 block cannot be found for the PC value specified, the function |
5962 will return `None'. | 6967 will return `None'. |
5963 | 6968 |
5964 A `gdb.Block' object has the following methods: | 6969 A `gdb.Block' object has the following methods: |
5965 | 6970 |
5966 -- Function: Block.is_valid () | 6971 -- Function: Block.is_valid () |
5967 Returns `True' if the `gdb.Block' object is valid, `False' if | 6972 Returns `True' if the `gdb.Block' object is valid, `False' if |
5968 not. A block object can become invalid if the block it | 6973 not. A block object can become invalid if the block it |
5969 refers to doesn't exist anymore in the inferior. All other | 6974 refers to doesn't exist anymore in the inferior. All other |
5970 `gdb.Block' methods will throw an exception if it is invalid | 6975 `gdb.Block' methods will throw an exception if it is invalid |
5971 at the time the method is called. This method is also made | 6976 at the time the method is called. The block's validity is |
5972 available to the Python iterator object that `gdb.Block' | 6977 also checked during iteration over symbols of the block. |
5973 provides in an iteration context and via the Python `iter' | |
5974 built-in function. | |
5975 | 6978 |
5976 A `gdb.Block' object has the following attributes: | 6979 A `gdb.Block' object has the following attributes: |
5977 | 6980 |
5978 -- Variable: Block.start | 6981 -- Variable: Block.start |
5979 The start address of the block. This attribute is not | 6982 The start address of the block. This attribute is not |
5980 writable. | 6983 writable. |
5981 | 6984 |
5982 -- Variable: Block.end | 6985 -- Variable: Block.end |
5983 The end address of the block. This attribute is not writable. | 6986 The end address of the block. This attribute is not writable. |
5984 | 6987 |
(...skipping 73 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6058 -- Variable: Symbol.type | 7061 -- Variable: Symbol.type |
6059 The type of the symbol or `None' if no type is recorded. | 7062 The type of the symbol or `None' if no type is recorded. |
6060 This attribute is represented as a `gdb.Type' object. *Note | 7063 This attribute is represented as a `gdb.Type' object. *Note |
6061 Types In Python::. This attribute is not writable. | 7064 Types In Python::. This attribute is not writable. |
6062 | 7065 |
6063 -- Variable: Symbol.symtab | 7066 -- Variable: Symbol.symtab |
6064 The symbol table in which the symbol appears. This attribute | 7067 The symbol table in which the symbol appears. This attribute |
6065 is represented as a `gdb.Symtab' object. *Note Symbol Tables | 7068 is represented as a `gdb.Symtab' object. *Note Symbol Tables |
6066 In Python::. This attribute is not writable. | 7069 In Python::. This attribute is not writable. |
6067 | 7070 |
| 7071 -- Variable: Symbol.line |
| 7072 The line number in the source code at which the symbol was |
| 7073 defined. This is an integer. |
| 7074 |
6068 -- Variable: Symbol.name | 7075 -- Variable: Symbol.name |
6069 The name of the symbol as a string. This attribute is not | 7076 The name of the symbol as a string. This attribute is not |
6070 writable. | 7077 writable. |
6071 | 7078 |
6072 -- Variable: Symbol.linkage_name | 7079 -- Variable: Symbol.linkage_name |
6073 The name of the symbol, as used by the linker (i.e., may be | 7080 The name of the symbol, as used by the linker (i.e., may be |
6074 mangled). This attribute is not writable. | 7081 mangled). This attribute is not writable. |
6075 | 7082 |
6076 -- Variable: Symbol.print_name | 7083 -- Variable: Symbol.print_name |
6077 The name of the symbol in a form suitable for output. This | 7084 The name of the symbol in a form suitable for output. This |
6078 is either `name' or `linkage_name', depending on whether the | 7085 is either `name' or `linkage_name', depending on whether the |
6079 user asked GDB to display demangled or mangled names. | 7086 user asked GDB to display demangled or mangled names. |
6080 | 7087 |
6081 -- Variable: Symbol.addr_class | 7088 -- Variable: Symbol.addr_class |
6082 The address class of the symbol. This classifies how to find | 7089 The address class of the symbol. This classifies how to find |
6083 the value of a symbol. Each address class is a constant | 7090 the value of a symbol. Each address class is a constant |
6084 defined in the `gdb' module and described later in this | 7091 defined in the `gdb' module and described later in this |
6085 chapter. | 7092 chapter. |
6086 | 7093 |
| 7094 -- Variable: Symbol.needs_frame |
| 7095 This is `True' if evaluating this symbol's value requires a |
| 7096 frame (*note Frames In Python::) and `False' otherwise. |
| 7097 Typically, local variables will require a frame, but other |
| 7098 symbols will not. |
| 7099 |
6087 -- Variable: Symbol.is_argument | 7100 -- Variable: Symbol.is_argument |
6088 `True' if the symbol is an argument of a function. | 7101 `True' if the symbol is an argument of a function. |
6089 | 7102 |
6090 -- Variable: Symbol.is_constant | 7103 -- Variable: Symbol.is_constant |
6091 `True' if the symbol is a constant. | 7104 `True' if the symbol is a constant. |
6092 | 7105 |
6093 -- Variable: Symbol.is_function | 7106 -- Variable: Symbol.is_function |
6094 `True' if the symbol is a function or a method. | 7107 `True' if the symbol is a function or a method. |
6095 | 7108 |
6096 -- Variable: Symbol.is_variable | 7109 -- Variable: Symbol.is_variable |
6097 `True' if the symbol is a variable. | 7110 `True' if the symbol is a variable. |
6098 | 7111 |
6099 A `gdb.Symbol' object has the following methods: | 7112 A `gdb.Symbol' object has the following methods: |
6100 | 7113 |
6101 -- Function: Symbol.is_valid () | 7114 -- Function: Symbol.is_valid () |
6102 Returns `True' if the `gdb.Symbol' object is valid, `False' | 7115 Returns `True' if the `gdb.Symbol' object is valid, `False' |
6103 if not. A `gdb.Symbol' object can become invalid if the | 7116 if not. A `gdb.Symbol' object can become invalid if the |
6104 symbol it refers to does not exist in GDB any longer. All | 7117 symbol it refers to does not exist in GDB any longer. All |
6105 other `gdb.Symbol' methods will throw an exception if it is | 7118 other `gdb.Symbol' methods will throw an exception if it is |
6106 invalid at the time the method is called. | 7119 invalid at the time the method is called. |
6107 | 7120 |
| 7121 -- Function: Symbol.value ([frame]) |
| 7122 Compute the value of the symbol, as a `gdb.Value'. For |
| 7123 functions, this computes the address of the function, cast to |
| 7124 the appropriate type. If the symbol requires a frame in |
| 7125 order to compute its value, then FRAME must be given. If |
| 7126 FRAME is not given, or if FRAME is invalid, then this method |
| 7127 will throw an exception. |
| 7128 |
6108 The available domain categories in `gdb.Symbol' are represented as | 7129 The available domain categories in `gdb.Symbol' are represented as |
6109 constants in the `gdb' module: | 7130 constants in the `gdb' module: |
6110 | 7131 |
6111 `gdb.SYMBOL_UNDEF_DOMAIN' | 7132 `gdb.SYMBOL_UNDEF_DOMAIN' |
6112 This is used when a domain has not been discovered or none of the | 7133 This is used when a domain has not been discovered or none of the |
6113 following domains apply. This usually indicates an error either | 7134 following domains apply. This usually indicates an error either |
6114 in the symbol information or in GDB's handling of symbols. | 7135 in the symbol information or in GDB's handling of symbols. |
6115 | 7136 |
6116 `gdb.SYMBOL_VAR_DOMAIN' | 7137 `gdb.SYMBOL_VAR_DOMAIN' |
6117 This domain contains variables, function names, typedef names and | 7138 This domain contains variables, function names, typedef names and |
(...skipping 63 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6181 to be determined from the minimal symbol table whenever the | 7202 to be determined from the minimal symbol table whenever the |
6182 variable is referenced. | 7203 variable is referenced. |
6183 | 7204 |
6184 `gdb.SYMBOL_LOC_OPTIMIZED_OUT' | 7205 `gdb.SYMBOL_LOC_OPTIMIZED_OUT' |
6185 The value does not actually exist in the program. | 7206 The value does not actually exist in the program. |
6186 | 7207 |
6187 `gdb.SYMBOL_LOC_COMPUTED' | 7208 `gdb.SYMBOL_LOC_COMPUTED' |
6188 The value's address is a computed location. | 7209 The value's address is a computed location. |
6189 | 7210 |
6190 | 7211 |
6191 File: gdb.info, Node: Symbol Tables In Python, Next: Lazy Strings In Python,
Prev: Symbols In Python, Up: Python API | 7212 File: gdb.info, Node: Symbol Tables In Python, Next: Breakpoints In Python, P
rev: Symbols In Python, Up: Python API |
6192 | 7213 |
6193 23.2.2.19 Symbol table representation in Python. | 7214 23.2.2.19 Symbol table representation in Python. |
6194 ................................................ | 7215 ................................................ |
6195 | 7216 |
6196 Access to symbol table data maintained by GDB on the inferior is | 7217 Access to symbol table data maintained by GDB on the inferior is |
6197 exposed to Python via two objects: `gdb.Symtab_and_line' and | 7218 exposed to Python via two objects: `gdb.Symtab_and_line' and |
6198 `gdb.Symtab'. Symbol table and line data for a frame is returned from | 7219 `gdb.Symtab'. Symbol table and line data for a frame is returned from |
6199 the `find_sal' method in `gdb.Frame' object. *Note Frames In Python::. | 7220 the `find_sal' method in `gdb.Frame' object. *Note Frames In Python::. |
6200 | 7221 |
6201 For more information on GDB's symbol table management, see *Note | 7222 For more information on GDB's symbol table management, see *Note |
6202 Examining the Symbol Table: Symbols, for more information. | 7223 Examining the Symbol Table: Symbols, for more information. |
6203 | 7224 |
6204 A `gdb.Symtab_and_line' object has the following attributes: | 7225 A `gdb.Symtab_and_line' object has the following attributes: |
6205 | 7226 |
6206 -- Variable: Symtab_and_line.symtab | 7227 -- Variable: Symtab_and_line.symtab |
6207 The symbol table object (`gdb.Symtab') for this frame. This | 7228 The symbol table object (`gdb.Symtab') for this frame. This |
6208 attribute is not writable. | 7229 attribute is not writable. |
6209 | 7230 |
6210 -- Variable: Symtab_and_line.pc | 7231 -- Variable: Symtab_and_line.pc |
6211 Indicates the current program counter address. This | 7232 Indicates the start of the address range occupied by code for |
6212 attribute is not writable. | 7233 the current source line. This attribute is not writable. |
| 7234 |
| 7235 -- Variable: Symtab_and_line.last |
| 7236 Indicates the end of the address range occupied by code for |
| 7237 the current source line. This attribute is not writable. |
6213 | 7238 |
6214 -- Variable: Symtab_and_line.line | 7239 -- Variable: Symtab_and_line.line |
6215 Indicates the current line number for this object. This | 7240 Indicates the current line number for this object. This |
6216 attribute is not writable. | 7241 attribute is not writable. |
6217 | 7242 |
6218 A `gdb.Symtab_and_line' object has the following methods: | 7243 A `gdb.Symtab_and_line' object has the following methods: |
6219 | 7244 |
6220 -- Function: Symtab_and_line.is_valid () | 7245 -- Function: Symtab_and_line.is_valid () |
6221 Returns `True' if the `gdb.Symtab_and_line' object is valid, | 7246 Returns `True' if the `gdb.Symtab_and_line' object is valid, |
6222 `False' if not. A `gdb.Symtab_and_line' object can become | 7247 `False' if not. A `gdb.Symtab_and_line' object can become |
(...skipping 17 matching lines...) Expand all Loading... |
6240 -- Function: Symtab.is_valid () | 7265 -- Function: Symtab.is_valid () |
6241 Returns `True' if the `gdb.Symtab' object is valid, `False' | 7266 Returns `True' if the `gdb.Symtab' object is valid, `False' |
6242 if not. A `gdb.Symtab' object can become invalid if the | 7267 if not. A `gdb.Symtab' object can become invalid if the |
6243 symbol table it refers to does not exist in GDB any longer. | 7268 symbol table it refers to does not exist in GDB any longer. |
6244 All other `gdb.Symtab' methods will throw an exception if it | 7269 All other `gdb.Symtab' methods will throw an exception if it |
6245 is invalid at the time the method is called. | 7270 is invalid at the time the method is called. |
6246 | 7271 |
6247 -- Function: Symtab.fullname () | 7272 -- Function: Symtab.fullname () |
6248 Return the symbol table's source absolute file name. | 7273 Return the symbol table's source absolute file name. |
6249 | 7274 |
| 7275 -- Function: Symtab.global_block () |
| 7276 Return the global block of the underlying symbol table. |
| 7277 *Note Blocks In Python::. |
| 7278 |
| 7279 -- Function: Symtab.static_block () |
| 7280 Return the static block of the underlying symbol table. |
| 7281 *Note Blocks In Python::. |
| 7282 |
6250 | 7283 |
6251 File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Pytho
n, Prev: Lazy Strings In Python, Up: Python API | 7284 File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Pytho
n, Prev: Symbol Tables In Python, Up: Python API |
6252 | 7285 |
6253 23.2.2.20 Manipulating breakpoints using Python | 7286 23.2.2.20 Manipulating breakpoints using Python |
6254 ............................................... | 7287 ............................................... |
6255 | 7288 |
6256 Python code can manipulate breakpoints via the `gdb.Breakpoint' class. | 7289 Python code can manipulate breakpoints via the `gdb.Breakpoint' class. |
6257 | 7290 |
6258 -- Function: Breakpoint.__init__ (spec [, type [, wp_class | 7291 -- Function: Breakpoint.__init__ (spec [, type [, wp_class |
6259 [,internal]]]) | 7292 [,internal]]]) |
6260 Create a new breakpoint. SPEC is a string naming the location of | 7293 Create a new breakpoint. SPEC is a string naming the location of |
6261 the breakpoint, or an expression that defines a watchpoint. The | 7294 the breakpoint, or an expression that defines a watchpoint. The |
(...skipping 149 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6411 by the user. It is a string. If there is no condition, this | 7444 by the user. It is a string. If there is no condition, this |
6412 attribute's value is `None'. This attribute is writable. | 7445 attribute's value is `None'. This attribute is writable. |
6413 | 7446 |
6414 -- Variable: Breakpoint.commands | 7447 -- Variable: Breakpoint.commands |
6415 This attribute holds the commands attached to the breakpoint. If | 7448 This attribute holds the commands attached to the breakpoint. If |
6416 there are commands, this attribute's value is a string holding all | 7449 there are commands, this attribute's value is a string holding all |
6417 the commands, separated by newlines. If there are no commands, | 7450 the commands, separated by newlines. If there are no commands, |
6418 this attribute is `None'. This attribute is not writable. | 7451 this attribute is `None'. This attribute is not writable. |
6419 | 7452 |
6420 | 7453 |
6421 File: gdb.info, Node: Finish Breakpoints in Python, Prev: Breakpoints In Pytho
n, Up: Python API | 7454 File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Pyth
on, Prev: Breakpoints In Python, Up: Python API |
6422 | 7455 |
6423 23.2.2.21 Finish Breakpoints | 7456 23.2.2.21 Finish Breakpoints |
6424 ............................ | 7457 ............................ |
6425 | 7458 |
6426 A finish breakpoint is a temporary breakpoint set at the return address | 7459 A finish breakpoint is a temporary breakpoint set at the return address |
6427 of a frame, based on the `finish' command. `gdb.FinishBreakpoint' | 7460 of a frame, based on the `finish' command. `gdb.FinishBreakpoint' |
6428 extends `gdb.Breakpoint'. The underlying breakpoint will be disabled | 7461 extends `gdb.Breakpoint'. The underlying breakpoint will be disabled |
6429 and deleted when the execution will run out of the breakpoint scope | 7462 and deleted when the execution will run out of the breakpoint scope |
6430 (i.e. `Breakpoint.stop' or `FinishBreakpoint.out_of_scope' triggered). | 7463 (i.e. `Breakpoint.stop' or `FinishBreakpoint.out_of_scope' triggered). |
6431 Finish breakpoints are thread specific and must be create with the right | 7464 Finish breakpoints are thread specific and must be create with the right |
(...skipping 25 matching lines...) Expand all Loading... |
6457 | 7490 |
6458 -- Variable: FinishBreakpoint.return_value | 7491 -- Variable: FinishBreakpoint.return_value |
6459 When GDB is stopped at a finish breakpoint and the frame used to | 7492 When GDB is stopped at a finish breakpoint and the frame used to |
6460 build the `gdb.FinishBreakpoint' object had debug symbols, this | 7493 build the `gdb.FinishBreakpoint' object had debug symbols, this |
6461 attribute will contain a `gdb.Value' object corresponding to the | 7494 attribute will contain a `gdb.Value' object corresponding to the |
6462 return value of the function. The value will be `None' if the | 7495 return value of the function. The value will be `None' if the |
6463 function return type is `void' or if the return value was not | 7496 function return type is `void' or if the return value was not |
6464 computable. This attribute is not writable. | 7497 computable. This attribute is not writable. |
6465 | 7498 |
6466 | 7499 |
6467 File: gdb.info, Node: Lazy Strings In Python, Next: Breakpoints In Python, Pr
ev: Symbol Tables In Python, Up: Python API | 7500 File: gdb.info, Node: Lazy Strings In Python, Prev: Finish Breakpoints in Pyth
on, Up: Python API |
6468 | 7501 |
6469 23.2.2.22 Python representation of lazy strings. | 7502 23.2.2.22 Python representation of lazy strings. |
6470 ................................................ | 7503 ................................................ |
6471 | 7504 |
6472 A "lazy string" is a string whose contents is not retrieved or encoded | 7505 A "lazy string" is a string whose contents is not retrieved or encoded |
6473 until it is needed. | 7506 until it is needed. |
6474 | 7507 |
6475 A `gdb.LazyString' is represented in GDB as an `address' that points | 7508 A `gdb.LazyString' is represented in GDB as an `address' that points |
6476 to a region of memory, an `encoding' that will be used to encode that | 7509 to a region of memory, an `encoding' that will be used to encode that |
6477 region of memory, and a `length' to delimit the region of memory that | 7510 region of memory, and a `length' to delimit the region of memory that |
(...skipping 29 matching lines...) Expand all Loading... |
6507 is not writable. | 7540 is not writable. |
6508 | 7541 |
6509 -- Variable: LazyString.type | 7542 -- Variable: LazyString.type |
6510 This attribute holds the type that is represented by the lazy | 7543 This attribute holds the type that is represented by the lazy |
6511 string's type. For a lazy string this will always be a pointer | 7544 string's type. For a lazy string this will always be a pointer |
6512 type. To resolve this to the lazy string's character type, use | 7545 type. To resolve this to the lazy string's character type, use |
6513 the type's `target' method. *Note Types In Python::. This | 7546 the type's `target' method. *Note Types In Python::. This |
6514 attribute is not writable. | 7547 attribute is not writable. |
6515 | 7548 |
6516 | 7549 |
6517 File: gdb.info, Node: Auto-loading, Next: Python modules, Prev: Python API,
Up: Python | 7550 File: gdb.info, Node: Python Auto-loading, Next: Python modules, Prev: Python
API, Up: Python |
6518 | 7551 |
6519 23.2.3 Auto-loading | 7552 23.2.3 Python Auto-loading |
6520 ------------------- | 7553 -------------------------- |
6521 | 7554 |
6522 When a new object file is read (for example, due to the `file' command, | 7555 When a new object file is read (for example, due to the `file' command, |
6523 or because the inferior has loaded a shared library), GDB will look for | 7556 or because the inferior has loaded a shared library), GDB will look for |
6524 Python support scripts in several ways: `OBJFILE-gdb.py' and | 7557 Python support scripts in several ways: `OBJFILE-gdb.py' (*note |
6525 `.debug_gdb_scripts' section. | 7558 objfile-gdb.py file::) and `.debug_gdb_scripts' section (*note |
6526 | 7559 dotdebug_gdb_scripts section::). |
6527 * Menu: | |
6528 | |
6529 * objfile-gdb.py file:: The `OBJFILE-gdb.py' file | |
6530 * .debug_gdb_scripts section:: The `.debug_gdb_scripts' section | |
6531 * Which flavor to choose?:: | |
6532 | 7560 |
6533 The auto-loading feature is useful for supplying application-specific | 7561 The auto-loading feature is useful for supplying application-specific |
6534 debugging commands and scripts. | 7562 debugging commands and scripts. |
6535 | 7563 |
6536 Auto-loading can be enabled or disabled, and the list of auto-loaded | 7564 Auto-loading can be enabled or disabled, and the list of auto-loaded |
6537 scripts can be printed. | 7565 scripts can be printed. |
6538 | 7566 |
6539 `set auto-load-scripts [yes|no]' | 7567 `set auto-load python-scripts [on|off]' |
6540 Enable or disable the auto-loading of Python scripts. | 7568 Enable or disable the auto-loading of Python scripts. |
6541 | 7569 |
6542 `show auto-load-scripts' | 7570 `show auto-load python-scripts' |
6543 Show whether auto-loading of Python scripts is enabled or disabled. | 7571 Show whether auto-loading of Python scripts is enabled or disabled. |
6544 | 7572 |
6545 `info auto-load-scripts [REGEXP]' | 7573 `info auto-load python-scripts [REGEXP]' |
6546 Print the list of all scripts that GDB auto-loaded. | 7574 Print the list of all Python scripts that GDB auto-loaded. |
6547 | 7575 |
6548 Also printed is the list of scripts that were mentioned in the | 7576 Also printed is the list of Python scripts that were mentioned in |
6549 `.debug_gdb_scripts' section and were not found (*note | 7577 the `.debug_gdb_scripts' section and were not found (*note |
6550 .debug_gdb_scripts section::). This is useful because their names | 7578 dotdebug_gdb_scripts section::). This is useful because their |
6551 are not printed when GDB tries to load them and fails. There may | 7579 names are not printed when GDB tries to load them and fails. |
6552 be many of them, and printing an error message for each one is | 7580 There may be many of them, and printing an error message for each |
6553 problematic. | 7581 one is problematic. |
6554 | 7582 |
6555 If REGEXP is supplied only scripts with matching names are printed. | 7583 If REGEXP is supplied only Python scripts with matching names are |
| 7584 printed. |
6556 | 7585 |
6557 Example: | 7586 Example: |
6558 | 7587 |
6559 (gdb) info auto-load-scripts | 7588 (gdb) info auto-load python-scripts |
6560 Loaded Script | 7589 Loaded Script |
6561 Yes py-section-script.py | 7590 Yes py-section-script.py |
6562 full name: /tmp/py-section-script.py | 7591 full name: /tmp/py-section-script.py |
6563 Missing my-foo-pretty-printers.py | 7592 No my-foo-pretty-printers.py |
6564 | 7593 |
6565 When reading an auto-loaded file, GDB sets the "current objfile". | 7594 When reading an auto-loaded file, GDB sets the "current objfile". |
6566 This is available via the `gdb.current_objfile' function (*note | 7595 This is available via the `gdb.current_objfile' function (*note |
6567 Objfiles In Python::). This can be useful for registering | 7596 Objfiles In Python::). This can be useful for registering |
6568 objfile-specific pretty-printers. | 7597 objfile-specific pretty-printers. |
6569 | 7598 |
6570 | |
6571 File: gdb.info, Node: objfile-gdb.py file, Next: .debug_gdb_scripts section,
Up: Auto-loading | |
6572 | |
6573 23.2.3.1 The `OBJFILE-gdb.py' file | |
6574 .................................. | |
6575 | |
6576 When a new object file is read, GDB looks for a file named | |
6577 `OBJFILE-gdb.py', where OBJFILE is the object file's real name, formed | |
6578 by ensuring that the file name is absolute, following all symlinks, and | |
6579 resolving `.' and `..' components. If this file exists and is | |
6580 readable, GDB will evaluate it as a Python script. | |
6581 | |
6582 If this file does not exist, and if the parameter | |
6583 `debug-file-directory' is set (*note Separate Debug Files::), then GDB | |
6584 will look for REAL-NAME in all of the directories mentioned in the | |
6585 value of `debug-file-directory'. | |
6586 | |
6587 Finally, if this file does not exist, then GDB will look for a file | |
6588 named `DATA-DIRECTORY/python/auto-load/REAL-NAME', where DATA-DIRECTORY | |
6589 is GDB's data directory (available via `show data-directory', *note | |
6590 Data Files::), and REAL-NAME is the object file's real name, as | |
6591 described above. | |
6592 | |
6593 GDB does not track which files it has already auto-loaded this way. | |
6594 GDB will load the associated script every time the corresponding | |
6595 OBJFILE is opened. So your `-gdb.py' file should be careful to avoid | |
6596 errors if it is evaluated more than once. | |
6597 | |
6598 | |
6599 File: gdb.info, Node: .debug_gdb_scripts section, Next: Which flavor to choose
?, Prev: objfile-gdb.py file, Up: Auto-loading | |
6600 | |
6601 23.2.3.2 The `.debug_gdb_scripts' section | |
6602 ......................................... | |
6603 | |
6604 For systems using file formats like ELF and COFF, when GDB loads a new | |
6605 object file it will look for a special section named | |
6606 `.debug_gdb_scripts'. If this section exists, its contents is a list | |
6607 of names of scripts to load. | |
6608 | |
6609 GDB will look for each specified script file first in the current | |
6610 directory and then along the source search path (*note Specifying | |
6611 Source Directories: Source Path.), except that `$cdir' is not searched, | |
6612 since the compilation directory is not relevant to scripts. | |
6613 | |
6614 Entries can be placed in section `.debug_gdb_scripts' with, for | |
6615 example, this GCC macro: | |
6616 | |
6617 /* Note: The "MS" section flags are to remove duplicates. */ | |
6618 #define DEFINE_GDB_SCRIPT(script_name) \ | |
6619 asm("\ | |
6620 .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ | |
6621 .byte 1\n\ | |
6622 .asciz \"" script_name "\"\n\ | |
6623 .popsection \n\ | |
6624 "); | |
6625 | |
6626 Then one can reference the macro in a header or source file like this: | |
6627 | |
6628 DEFINE_GDB_SCRIPT ("my-app-scripts.py") | |
6629 | |
6630 The script name may include directories if desired. | |
6631 | |
6632 If the macro is put in a header, any application or library using | |
6633 this header will get a reference to the specified script. | |
6634 | |
6635 | |
6636 File: gdb.info, Node: Which flavor to choose?, Prev: .debug_gdb_scripts sectio
n, Up: Auto-loading | |
6637 | |
6638 23.2.3.3 Which flavor to choose? | |
6639 ................................ | |
6640 | |
6641 Given the multiple ways of auto-loading Python scripts, it might not | |
6642 always be clear which one to choose. This section provides some | |
6643 guidance. | |
6644 | |
6645 Benefits of the `-gdb.py' way: | |
6646 | |
6647 * Can be used with file formats that don't support multiple sections. | |
6648 | |
6649 * Ease of finding scripts for public libraries. | |
6650 | |
6651 Scripts specified in the `.debug_gdb_scripts' section are searched | |
6652 for in the source search path. For publicly installed libraries, | |
6653 e.g., `libstdc++', there typically isn't a source directory in | |
6654 which to find the script. | |
6655 | |
6656 * Doesn't require source code additions. | |
6657 | |
6658 Benefits of the `.debug_gdb_scripts' way: | |
6659 | |
6660 * Works with static linking. | |
6661 | |
6662 Scripts for libraries done the `-gdb.py' way require an objfile to | |
6663 trigger their loading. When an application is statically linked | |
6664 the only objfile available is the executable, and it is cumbersome | |
6665 to attach all the scripts from all the input libraries to the | |
6666 executable's `-gdb.py' script. | |
6667 | |
6668 * Works with classes that are entirely inlined. | |
6669 | |
6670 Some classes can be entirely inlined, and thus there may not be an | |
6671 associated shared library to attach a `-gdb.py' script to. | |
6672 | |
6673 * Scripts needn't be copied out of the source tree. | |
6674 | |
6675 In some circumstances, apps can be built out of large collections | |
6676 of internal libraries, and the build infrastructure necessary to | |
6677 install the `-gdb.py' scripts in a place where GDB can find them is | |
6678 cumbersome. It may be easier to specify the scripts in the | |
6679 `.debug_gdb_scripts' section as relative paths, and add a path to | |
6680 the top of the source tree to the source search path. | |
6681 | |
6682 | |
6683 File: gdb.info, Node: Python modules, Prev: Auto-loading, Up: Python | |
6684 | |
6685 23.2.4 Python modules | |
6686 --------------------- | |
6687 | |
6688 GDB comes with several modules to assist writing Python code. | |
6689 | |
6690 * Menu: | 7599 * Menu: |
6691 | 7600 |
6692 * gdb.printing:: Building and registering pretty-printers. | 7601 * objfile-gdb.py file:: The `OBJFILE-gdb.py' file |
6693 * gdb.types:: Utilities for working with types. | 7602 * dotdebug_gdb_scripts section:: The `.debug_gdb_scripts' section |
6694 * gdb.prompt:: Utilities for prompt value substitution. | 7603 * Which flavor to choose?:: |
6695 | 7604 |
6696 | |
6697 File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules | |
6698 | |
6699 23.2.4.1 gdb.printing | |
6700 ..................... | |
6701 | |
6702 This module provides a collection of utilities for working with | |
6703 pretty-printers. | |
6704 | |
6705 `PrettyPrinter (NAME, SUBPRINTERS=None)' | |
6706 This class specifies the API that makes `info pretty-printer', | |
6707 `enable pretty-printer' and `disable pretty-printer' work. | |
6708 Pretty-printers should generally inherit from this class. | |
6709 | |
6710 `SubPrettyPrinter (NAME)' | |
6711 For printers that handle multiple types, this class specifies the | |
6712 corresponding API for the subprinters. | |
6713 | |
6714 `RegexpCollectionPrettyPrinter (NAME)' | |
6715 Utility class for handling multiple printers, all recognized via | |
6716 regular expressions. *Note Writing a Pretty-Printer::, for an | |
6717 example. | |
6718 | |
6719 `register_pretty_printer (OBJ, PRINTER, REPLACE=False)' | |
6720 Register PRINTER with the pretty-printer list of OBJ. If REPLACE | |
6721 is `True' then any existing copy of the printer is replaced. | |
6722 Otherwise a `RuntimeError' exception is raised if a printer with | |
6723 the same name already exists. | |
6724 | |
6725 | |
6726 File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: P
ython modules | |
6727 | |
6728 23.2.4.2 gdb.types | |
6729 .................. | |
6730 | |
6731 This module provides a collection of utilities for working with | |
6732 `gdb.Types' objects. | |
6733 | |
6734 `get_basic_type (TYPE)' | |
6735 Return TYPE with const and volatile qualifiers stripped, and with | |
6736 typedefs and C++ references converted to the underlying type. | |
6737 | |
6738 C++ example: | |
6739 | |
6740 typedef const int const_int; | |
6741 const_int foo (3); | |
6742 const_int& foo_ref (foo); | |
6743 int main () { return 0; } | |
6744 | |
6745 Then in gdb: | |
6746 | |
6747 (gdb) start | |
6748 (gdb) python import gdb.types | |
6749 (gdb) python foo_ref = gdb.parse_and_eval("foo_ref") | |
6750 (gdb) python print gdb.types.get_basic_type(foo_ref.type) | |
6751 int | |
6752 | |
6753 `has_field (TYPE, FIELD)' | |
6754 Return `True' if TYPE, assumed to be a type with fields (e.g., a | |
6755 structure or union), has field FIELD. | |
6756 | |
6757 `make_enum_dict (ENUM_TYPE)' | |
6758 Return a Python `dictionary' type produced from ENUM_TYPE. | |
6759 | |
6760 `deep_items (TYPE)' | |
6761 Returns a Python iterator similar to the standard | |
6762 `gdb.Type.iteritems' method, except that the iterator returned by | |
6763 `deep_items' will recursively traverse anonymous struct or union | |
6764 fields. For example: | |
6765 | |
6766 struct A | |
6767 { | |
6768 int a; | |
6769 union { | |
6770 int b0; | |
6771 int b1; | |
6772 }; | |
6773 }; | |
6774 | |
6775 Then in GDB: | |
6776 (gdb) python import gdb.types | |
6777 (gdb) python struct_a = gdb.lookup_type("struct A") | |
6778 (gdb) python print struct_a.keys () | |
6779 {['a', '']} | |
6780 (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)] | |
6781 {['a', 'b0', 'b1']} | |
6782 | |
6783 | |
6784 | |
6785 File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules | |
6786 | |
6787 23.2.4.3 gdb.prompt | |
6788 ................... | |
6789 | |
6790 This module provides a method for prompt value-substitution. | |
6791 | |
6792 `substitute_prompt (STRING)' | |
6793 Return STRING with escape sequences substituted by values. Some | |
6794 escape sequences take arguments. You can specify arguments inside | |
6795 "{}" immediately following the escape sequence. | |
6796 | |
6797 The escape sequences you can pass to this function are: | |
6798 | |
6799 `\\' | |
6800 Substitute a backslash. | |
6801 | |
6802 `\e' | |
6803 Substitute an ESC character. | |
6804 | |
6805 `\f' | |
6806 Substitute the selected frame; an argument names a frame | |
6807 parameter. | |
6808 | |
6809 `\n' | |
6810 Substitute a newline. | |
6811 | |
6812 `\p' | |
6813 Substitute a parameter's value; the argument names the | |
6814 parameter. | |
6815 | |
6816 `\r' | |
6817 Substitute a carriage return. | |
6818 | |
6819 `\t' | |
6820 Substitute the selected thread; an argument names a thread | |
6821 parameter. | |
6822 | |
6823 `\v' | |
6824 Substitute the version of GDB. | |
6825 | |
6826 `\w' | |
6827 Substitute the current working directory. | |
6828 | |
6829 `\[' | |
6830 Begin a sequence of non-printing characters. These sequences | |
6831 are typically used with the ESC character, and are not | |
6832 counted in the string length. Example: | |
6833 "\[\e[0;34m\](gdb)\[\e[0m\]" will return a blue-colored | |
6834 "(gdb)" prompt where the length is five. | |
6835 | |
6836 `\]' | |
6837 End a sequence of non-printing characters. | |
6838 | |
6839 For example: | |
6840 | |
6841 substitute_prompt (``frame: \f, | |
6842 print arguments: \p{print frame-arguments}'') | |
6843 | |
6844 will return the string: | |
6845 | |
6846 | |
6847 "frame: main, print arguments: scalars" | |
6848 | |
6849 | |
6850 File: gdb.info, Node: Aliases, Prev: Python, Up: Extending GDB | |
6851 | |
6852 23.3 Creating new spellings of existing commands | |
6853 ================================================ | |
6854 | |
6855 It is often useful to define alternate spellings of existing commands. | |
6856 For example, if a new GDB command defined in Python has a long name to | |
6857 type, it is handy to have an abbreviated version of it that involves | |
6858 less typing. | |
6859 | |
6860 GDB itself uses aliases. For example `s' is an alias of the `step' | |
6861 command even though it is otherwise an ambiguous abbreviation of other | |
6862 commands like `set' and `show'. | |
6863 | |
6864 Aliases are also used to provide shortened or more common versions | |
6865 of multi-word commands. For example, GDB provides the `tty' alias of | |
6866 the `set inferior-tty' command. | |
6867 | |
6868 You can define a new alias with the `alias' command. | |
6869 | |
6870 `alias [-a] [--] ALIAS = COMMAND' | |
6871 | |
6872 ALIAS specifies the name of the new alias. Each word of ALIAS must | |
6873 consist of letters, numbers, dashes and underscores. | |
6874 | |
6875 COMMAND specifies the name of an existing command that is being | |
6876 aliased. | |
6877 | |
6878 The `-a' option specifies that the new alias is an abbreviation of | |
6879 the command. Abbreviations are not shown in command lists displayed by | |
6880 the `help' command. | |
6881 | |
6882 The `--' option specifies the end of options, and is useful when | |
6883 ALIAS begins with a dash. | |
6884 | |
6885 Here is a simple example showing how to make an abbreviation of a | |
6886 command so that there is less to type. Suppose you were tired of | |
6887 typing `disas', the current shortest unambiguous abbreviation of the | |
6888 `disassemble' command and you wanted an even shorter version named `di'. | |
6889 The following will accomplish this. | |
6890 | |
6891 (gdb) alias -a di = disas | |
6892 | |
6893 Note that aliases are different from user-defined commands. With a | |
6894 user-defined command, you also need to write documentation for it with | |
6895 the `document' command. An alias automatically picks up the | |
6896 documentation of the existing command. | |
6897 | |
6898 Here is an example where we make `elms' an abbreviation of | |
6899 `elements' in the `set print elements' command. This is to show that | |
6900 you can make an abbreviation of any part of a command. | |
6901 | |
6902 (gdb) alias -a set print elms = set print elements | |
6903 (gdb) alias -a show print elms = show print elements | |
6904 (gdb) set p elms 20 | |
6905 (gdb) show p elms | |
6906 Limit on string chars or array elements to print is 200. | |
6907 | |
6908 Note that if you are defining an alias of a `set' command, and you | |
6909 want to have an alias for the corresponding `show' command, then you | |
6910 need to define the latter separately. | |
6911 | |
6912 Unambiguously abbreviated commands are allowed in COMMAND and ALIAS, | |
6913 just as they are normally. | |
6914 | |
6915 (gdb) alias -a set pr elms = set p ele | |
6916 | |
6917 Finally, here is an example showing the creation of a one word alias | |
6918 for a more complex command. This creates alias `spe' of the command | |
6919 `set print elements'. | |
6920 | |
6921 (gdb) alias spe = set print elements | |
6922 (gdb) spe 20 | |
6923 | |
6924 | |
6925 File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top | |
6926 | |
6927 24 Command Interpreters | |
6928 *********************** | |
6929 | |
6930 GDB supports multiple command interpreters, and some command | |
6931 infrastructure to allow users or user interface writers to switch | |
6932 between interpreters or run commands in other interpreters. | |
6933 | |
6934 GDB currently supports two command interpreters, the console | |
6935 interpreter (sometimes called the command-line interpreter or CLI) and | |
6936 the machine interface interpreter (or GDB/MI). This manual describes | |
6937 both of these interfaces in great detail. | |
6938 | |
6939 By default, GDB will start with the console interpreter. However, | |
6940 the user may choose to start GDB with another interpreter by specifying | |
6941 the `-i' or `--interpreter' startup options. Defined interpreters | |
6942 include: | |
6943 | |
6944 `console' | |
6945 The traditional console or command-line interpreter. This is the | |
6946 most often used interpreter with GDB. With no interpreter | |
6947 specified at runtime, GDB will use this interpreter. | |
6948 | |
6949 `mi' | |
6950 The newest GDB/MI interface (currently `mi2'). Used primarily by | |
6951 programs wishing to use GDB as a backend for a debugger GUI or an | |
6952 IDE. For more information, see *Note The GDB/MI Interface: GDB/MI. | |
6953 | |
6954 `mi2' | |
6955 The current GDB/MI interface. | |
6956 | |
6957 `mi1' | |
6958 The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. | |
6959 | |
6960 | |
6961 The interpreter being used by GDB may not be dynamically switched at | |
6962 runtime. Although possible, this could lead to a very precarious | |
6963 situation. Consider an IDE using GDB/MI. If a user enters the command | |
6964 "interpreter-set console" in a console view, GDB would switch to using | |
6965 the console interpreter, rendering the IDE inoperable! | |
6966 | |
6967 Although you may only choose a single interpreter at startup, you | |
6968 may execute commands in any interpreter from the current interpreter | |
6969 using the appropriate command. If you are running the console | |
6970 interpreter, simply use the `interpreter-exec' command: | |
6971 | |
6972 interpreter-exec mi "-data-list-register-names" | |
6973 | |
6974 GDB/MI has a similar command, although it is only available in | |
6975 versions of GDB which support GDB/MI version 2 (or greater). | |
6976 | |
6977 | |
6978 File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top | |
6979 | |
6980 25 GDB Text User Interface | |
6981 ************************** | |
6982 | |
6983 * Menu: | |
6984 | |
6985 * TUI Overview:: TUI overview | |
6986 * TUI Keys:: TUI key bindings | |
6987 * TUI Single Key Mode:: TUI single key mode | |
6988 * TUI Commands:: TUI-specific commands | |
6989 * TUI Configuration:: TUI configuration variables | |
6990 | |
6991 The GDB Text User Interface (TUI) is a terminal interface which uses | |
6992 the `curses' library to show the source file, the assembly output, the | |
6993 program registers and GDB commands in separate text windows. The TUI | |
6994 mode is supported only on platforms where a suitable version of the | |
6995 `curses' library is available. | |
6996 | |
6997 The TUI mode is enabled by default when you invoke GDB as either | |
6998 `gdbtui' or `gdb -tui'. You can also switch in and out of TUI mode | |
6999 while GDB runs by using various TUI commands and key bindings, such as | |
7000 `C-x C-a'. *Note TUI Key Bindings: TUI Keys. | |
7001 | |
7002 | |
7003 File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI | |
7004 | |
7005 25.1 TUI Overview | |
7006 ================= | |
7007 | |
7008 In TUI mode, GDB can display several text windows: | |
7009 | |
7010 _command_ | |
7011 This window is the GDB command window with the GDB prompt and the | |
7012 GDB output. The GDB input is still managed using readline. | |
7013 | |
7014 _source_ | |
7015 The source window shows the source file of the program. The | |
7016 current line and active breakpoints are displayed in this window. | |
7017 | |
7018 _assembly_ | |
7019 The assembly window shows the disassembly output of the program. | |
7020 | |
7021 _register_ | |
7022 This window shows the processor registers. Registers are | |
7023 highlighted when their values change. | |
7024 | |
7025 The source and assembly windows show the current program position by | |
7026 highlighting the current line and marking it with a `>' marker. | |
7027 Breakpoints are indicated with two markers. The first marker indicates | |
7028 the breakpoint type: | |
7029 | |
7030 `B' | |
7031 Breakpoint which was hit at least once. | |
7032 | |
7033 `b' | |
7034 Breakpoint which was never hit. | |
7035 | |
7036 `H' | |
7037 Hardware breakpoint which was hit at least once. | |
7038 | |
7039 `h' | |
7040 Hardware breakpoint which was never hit. | |
7041 | |
7042 The second marker indicates whether the breakpoint is enabled or not: | |
7043 | |
7044 `+' | |
7045 Breakpoint is enabled. | |
7046 | |
7047 `-' | |
7048 Breakpoint is disabled. | |
7049 | |
7050 The source, assembly and register windows are updated when the | |
7051 current thread changes, when the frame changes, or when the program | |
7052 counter changes. | |
7053 | |
7054 These windows are not all visible at the same time. The command | |
7055 window is always visible. The others can be arranged in several | |
7056 layouts: | |
7057 | |
7058 * source only, | |
7059 | |
7060 * assembly only, | |
7061 | |
7062 * source and assembly, | |
7063 | |
7064 * source and registers, or | |
7065 | |
7066 * assembly and registers. | |
7067 | |
7068 A status line above the command window shows the following | |
7069 information: | |
7070 | |
7071 _target_ | |
7072 Indicates the current GDB target. (*note Specifying a Debugging | |
7073 Target: Targets.). | |
7074 | |
7075 _process_ | |
7076 Gives the current process or thread number. When no process is | |
7077 being debugged, this field is set to `No process'. | |
7078 | |
7079 _function_ | |
7080 Gives the current function name for the selected frame. The name | |
7081 is demangled if demangling is turned on (*note Print Settings::). | |
7082 When there is no symbol corresponding to the current program | |
7083 counter, the string `??' is displayed. | |
7084 | |
7085 _line_ | |
7086 Indicates the current line number for the selected frame. When | |
7087 the current line number is not known, the string `??' is displayed. | |
7088 | |
7089 _pc_ | |
7090 Indicates the current program counter address. | |
7091 | |
7092 | |
7093 File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview
, Up: TUI | |
7094 | |
7095 25.2 TUI Key Bindings | |
7096 ===================== | |
7097 | |
7098 The TUI installs several key bindings in the readline keymaps (*note | |
7099 Command Line Editing::). The following key bindings are installed for | |
7100 both TUI mode and the GDB standard mode. | |
7101 | |
7102 `C-x C-a' | |
7103 `C-x a' | |
7104 `C-x A' | |
7105 Enter or leave the TUI mode. When leaving the TUI mode, the | |
7106 curses window management stops and GDB operates using its standard | |
7107 mode, writing on the terminal directly. When reentering the TUI | |
7108 mode, control is given back to the curses windows. The screen is | |
7109 then refreshed. | |
7110 | |
7111 `C-x 1' | |
7112 Use a TUI layout with only one window. The layout will either be | |
7113 `source' or `assembly'. When the TUI mode is not active, it will | |
7114 switch to the TUI mode. | |
7115 | |
7116 Think of this key binding as the Emacs `C-x 1' binding. | |
7117 | |
7118 `C-x 2' | |
7119 Use a TUI layout with at least two windows. When the current | |
7120 layout already has two windows, the next layout with two windows | |
7121 is used. When a new layout is chosen, one window will always be | |
7122 common to the previous layout and the new one. | |
7123 | |
7124 Think of it as the Emacs `C-x 2' binding. | |
7125 | |
7126 `C-x o' | |
7127 Change the active window. The TUI associates several key bindings | |
7128 (like scrolling and arrow keys) with the active window. This | |
7129 command gives the focus to the next TUI window. | |
7130 | |
7131 Think of it as the Emacs `C-x o' binding. | |
7132 | |
7133 `C-x s' | |
7134 Switch in and out of the TUI SingleKey mode that binds single keys | |
7135 to GDB commands (*note TUI Single Key Mode::). | |
7136 | |
7137 The following key bindings only work in the TUI mode: | |
7138 | |
7139 <PgUp> | |
7140 Scroll the active window one page up. | |
7141 | |
7142 <PgDn> | |
7143 Scroll the active window one page down. | |
7144 | |
7145 <Up> | |
7146 Scroll the active window one line up. | |
7147 | |
7148 <Down> | |
7149 Scroll the active window one line down. | |
7150 | |
7151 <Left> | |
7152 Scroll the active window one column left. | |
7153 | |
7154 <Right> | |
7155 Scroll the active window one column right. | |
7156 | |
7157 `C-L' | |
7158 Refresh the screen. | |
7159 | |
7160 Because the arrow keys scroll the active window in the TUI mode, they | |
7161 are not available for their normal use by readline unless the command | |
7162 window has the focus. When another window is active, you must use | |
7163 other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to | |
7164 control the command window. | |
7165 | |
7166 | |
7167 File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys
, Up: TUI | |
7168 | |
7169 25.3 TUI Single Key Mode | |
7170 ======================== | |
7171 | |
7172 The TUI also provides a "SingleKey" mode, which binds several | |
7173 frequently used GDB commands to single keys. Type `C-x s' to switch | |
7174 into this mode, where the following key bindings are used: | |
7175 | |
7176 `c' | |
7177 continue | |
7178 | |
7179 `d' | |
7180 down | |
7181 | |
7182 `f' | |
7183 finish | |
7184 | |
7185 `n' | |
7186 next | |
7187 | |
7188 `q' | |
7189 exit the SingleKey mode. | |
7190 | |
7191 `r' | |
7192 run | |
7193 | |
7194 `s' | |
7195 step | |
7196 | |
7197 `u' | |
7198 up | |
7199 | |
7200 `v' | |
7201 info locals | |
7202 | |
7203 `w' | |
7204 where | |
7205 | |
7206 Other keys temporarily switch to the GDB command prompt. The key | |
7207 that was pressed is inserted in the editing buffer so that it is | |
7208 possible to type most GDB commands without interaction with the TUI | |
7209 SingleKey mode. Once the command is entered the TUI SingleKey mode is | |
7210 restored. The only way to permanently leave this mode is by typing `q' | |
7211 or `C-x s'. | |
7212 | |
7213 | |
7214 File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single
Key Mode, Up: TUI | |
7215 | |
7216 25.4 TUI-specific Commands | |
7217 ========================== | |
7218 | |
7219 The TUI has specific commands to control the text windows. These | |
7220 commands are always available, even when GDB is not in the TUI mode. | |
7221 When GDB is in the standard mode, most of these commands will | |
7222 automatically switch to the TUI mode. | |
7223 | |
7224 Note that if GDB's `stdout' is not connected to a terminal, or GDB | |
7225 has been started with the machine interface interpreter (*note The | |
7226 GDB/MI Interface: GDB/MI.), most of these commands will fail with an | |
7227 error, because it would not be possible or desirable to enable curses | |
7228 window management. | |
7229 | |
7230 `info win' | |
7231 List and give the size of all displayed windows. | |
7232 | |
7233 `layout next' | |
7234 Display the next layout. | |
7235 | |
7236 `layout prev' | |
7237 Display the previous layout. | |
7238 | |
7239 `layout src' | |
7240 Display the source window only. | |
7241 | |
7242 `layout asm' | |
7243 Display the assembly window only. | |
7244 | |
7245 `layout split' | |
7246 Display the source and assembly window. | |
7247 | |
7248 `layout regs' | |
7249 Display the register window together with the source or assembly | |
7250 window. | |
7251 | |
7252 `focus next' | |
7253 Make the next window active for scrolling. | |
7254 | |
7255 `focus prev' | |
7256 Make the previous window active for scrolling. | |
7257 | |
7258 `focus src' | |
7259 Make the source window active for scrolling. | |
7260 | |
7261 `focus asm' | |
7262 Make the assembly window active for scrolling. | |
7263 | |
7264 `focus regs' | |
7265 Make the register window active for scrolling. | |
7266 | |
7267 `focus cmd' | |
7268 Make the command window active for scrolling. | |
7269 | |
7270 `refresh' | |
7271 Refresh the screen. This is similar to typing `C-L'. | |
7272 | |
7273 `tui reg float' | |
7274 Show the floating point registers in the register window. | |
7275 | |
7276 `tui reg general' | |
7277 Show the general registers in the register window. | |
7278 | |
7279 `tui reg next' | |
7280 Show the next register group. The list of register groups as well | |
7281 as their order is target specific. The predefined register groups | |
7282 are the following: `general', `float', `system', `vector', `all', | |
7283 `save', `restore'. | |
7284 | |
7285 `tui reg system' | |
7286 Show the system registers in the register window. | |
7287 | |
7288 `update' | |
7289 Update the source window and the current execution point. | |
7290 | |
7291 `winheight NAME +COUNT' | |
7292 `winheight NAME -COUNT' | |
7293 Change the height of the window NAME by COUNT lines. Positive | |
7294 counts increase the height, while negative counts decrease it. | |
7295 | |
7296 `tabset NCHARS' | |
7297 Set the width of tab stops to be NCHARS characters. | |
7298 | |
7299 | |
7300 File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI | |
7301 | |
7302 25.5 TUI Configuration Variables | |
7303 ================================ | |
7304 | |
7305 Several configuration variables control the appearance of TUI windows. | |
7306 | |
7307 `set tui border-kind KIND' | |
7308 Select the border appearance for the source, assembly and register | |
7309 windows. The possible values are the following: | |
7310 `space' | |
7311 Use a space character to draw the border. | |
7312 | |
7313 `ascii' | |
7314 Use ASCII characters `+', `-' and `|' to draw the border. | |
7315 | |
7316 `acs' | |
7317 Use the Alternate Character Set to draw the border. The | |
7318 border is drawn using character line graphics if the terminal | |
7319 supports them. | |
7320 | |
7321 `set tui border-mode MODE' | |
7322 `set tui active-border-mode MODE' | |
7323 Select the display attributes for the borders of the inactive | |
7324 windows or the active window. The MODE can be one of the | |
7325 following: | |
7326 `normal' | |
7327 Use normal attributes to display the border. | |
7328 | |
7329 `standout' | |
7330 Use standout mode. | |
7331 | |
7332 `reverse' | |
7333 Use reverse video mode. | |
7334 | |
7335 `half' | |
7336 Use half bright mode. | |
7337 | |
7338 `half-standout' | |
7339 Use half bright and standout mode. | |
7340 | |
7341 `bold' | |
7342 Use extra bright or bold mode. | |
7343 | |
7344 `bold-standout' | |
7345 Use extra bright or bold and standout mode. | |
7346 | |
7347 | |
7348 File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top | |
7349 | |
7350 26 Using GDB under GNU Emacs | |
7351 **************************** | |
7352 | |
7353 A special interface allows you to use GNU Emacs to view (and edit) the | |
7354 source files for the program you are debugging with GDB. | |
7355 | |
7356 To use this interface, use the command `M-x gdb' in Emacs. Give the | |
7357 executable file you want to debug as an argument. This command starts | |
7358 GDB as a subprocess of Emacs, with input and output through a newly | |
7359 created Emacs buffer. | |
7360 | |
7361 Running GDB under Emacs can be just like running GDB normally except | |
7362 for two things: | |
7363 | |
7364 * All "terminal" input and output goes through an Emacs buffer, | |
7365 called the GUD buffer. | |
7366 | |
7367 This applies both to GDB commands and their output, and to the | |
7368 input and output done by the program you are debugging. | |
7369 | |
7370 This is useful because it means that you can copy the text of | |
7371 previous commands and input them again; you can even use parts of | |
7372 the output in this way. | |
7373 | |
7374 All the facilities of Emacs' Shell mode are available for | |
7375 interacting with your program. In particular, you can send | |
7376 signals the usual way--for example, `C-c C-c' for an interrupt, | |
7377 `C-c C-z' for a stop. | |
7378 | |
7379 * GDB displays source code through Emacs. | |
7380 | |
7381 Each time GDB displays a stack frame, Emacs automatically finds the | |
7382 source file for that frame and puts an arrow (`=>') at the left | |
7383 margin of the current line. Emacs uses a separate buffer for | |
7384 source display, and splits the screen to show both your GDB session | |
7385 and the source. | |
7386 | |
7387 Explicit GDB `list' or search commands still produce output as | |
7388 usual, but you probably have no reason to use them from Emacs. | |
7389 | |
7390 We call this "text command mode". Emacs 22.1, and later, also uses | |
7391 a graphical mode, enabled by default, which provides further buffers | |
7392 that can control the execution and describe the state of your program. | |
7393 *Note GDB Graphical Interface: (Emacs)GDB Graphical Interface. | |
7394 | |
7395 If you specify an absolute file name when prompted for the `M-x gdb' | |
7396 argument, then Emacs sets your current working directory to where your | |
7397 program resides. If you only specify the file name, then Emacs sets | |
7398 your current working directory to the directory associated with the | |
7399 previous buffer. In this case, GDB may find your program by searching | |
7400 your environment's `PATH' variable, but on some operating systems it | |
7401 might not find the source. So, although the GDB input and output | |
7402 session proceeds normally, the auxiliary buffer does not display the | |
7403 current source and line of execution. | |
7404 | |
7405 The initial working directory of GDB is printed on the top line of | |
7406 the GUD buffer and this serves as a default for the commands that | |
7407 specify files for GDB to operate on. *Note Commands to Specify Files: | |
7408 Files. | |
7409 | |
7410 By default, `M-x gdb' calls the program called `gdb'. If you need | |
7411 to call GDB by a different name (for example, if you keep several | |
7412 configurations around, with different names) you can customize the | |
7413 Emacs variable `gud-gdb-command-name' to run the one you want. | |
7414 | |
7415 In the GUD buffer, you can use these special Emacs commands in | |
7416 addition to the standard Shell mode commands: | |
7417 | |
7418 `C-h m' | |
7419 Describe the features of Emacs' GUD Mode. | |
7420 | |
7421 `C-c C-s' | |
7422 Execute to another source line, like the GDB `step' command; also | |
7423 update the display window to show the current file and location. | |
7424 | |
7425 `C-c C-n' | |
7426 Execute to next source line in this function, skipping all function | |
7427 calls, like the GDB `next' command. Then update the display window | |
7428 to show the current file and location. | |
7429 | |
7430 `C-c C-i' | |
7431 Execute one instruction, like the GDB `stepi' command; update | |
7432 display window accordingly. | |
7433 | |
7434 `C-c C-f' | |
7435 Execute until exit from the selected stack frame, like the GDB | |
7436 `finish' command. | |
7437 | |
7438 `C-c C-r' | |
7439 Continue execution of your program, like the GDB `continue' | |
7440 command. | |
7441 | |
7442 `C-c <' | |
7443 Go up the number of frames indicated by the numeric argument | |
7444 (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' | |
7445 command. | |
7446 | |
7447 `C-c >' | |
7448 Go down the number of frames indicated by the numeric argument, | |
7449 like the GDB `down' command. | |
7450 | |
7451 In any source file, the Emacs command `C-x <SPC>' (`gud-break') | |
7452 tells GDB to set a breakpoint on the source line point is on. | |
7453 | |
7454 In text command mode, if you type `M-x speedbar', Emacs displays a | |
7455 separate frame which shows a backtrace when the GUD buffer is current. | |
7456 Move point to any frame in the stack and type <RET> to make it become | |
7457 the current frame and display the associated source in the source | |
7458 buffer. Alternatively, click `Mouse-2' to make the selected frame | |
7459 become the current one. In graphical mode, the speedbar displays watch | |
7460 expressions. | |
7461 | |
7462 If you accidentally delete the source-display buffer, an easy way to | |
7463 get it back is to type the command `f' in the GDB buffer, to request a | |
7464 frame display; when you run under Emacs, this recreates the source | |
7465 buffer if necessary to show you the context of the current frame. | |
7466 | |
7467 The source files displayed in Emacs are in ordinary Emacs buffers | |
7468 which are visiting the source files in the usual way. You can edit the | |
7469 files with these buffers if you wish; but keep in mind that GDB | |
7470 communicates with Emacs in terms of line numbers. If you add or delete | |
7471 lines from the text, the line numbers that GDB knows cease to | |
7472 correspond properly with the code. | |
7473 | |
7474 A more detailed description of Emacs' interaction with GDB is given | |
7475 in the Emacs manual (*note Debuggers: (Emacs)Debuggers.). | |
7476 | |
7477 | |
7478 File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top | |
7479 | |
7480 27 The GDB/MI Interface | |
7481 *********************** | |
7482 | |
7483 Function and Purpose | |
7484 ==================== | |
7485 | |
7486 GDB/MI is a line based machine oriented text interface to GDB and is | |
7487 activated by specifying using the `--interpreter' command line option | |
7488 (*note Mode Options::). It is specifically intended to support the | |
7489 development of systems which use the debugger as just one small | |
7490 component of a larger system. | |
7491 | |
7492 This chapter is a specification of the GDB/MI interface. It is | |
7493 written in the form of a reference manual. | |
7494 | |
7495 Note that GDB/MI is still under construction, so some of the | |
7496 features described below are incomplete and subject to change (*note | |
7497 GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.). | |
7498 | |
7499 Notation and Terminology | |
7500 ======================== | |
7501 | |
7502 This chapter uses the following notation: | |
7503 | |
7504 * `|' separates two alternatives. | |
7505 | |
7506 * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or | |
7507 may not be given. | |
7508 | |
7509 * `( GROUP )*' means that GROUP inside the parentheses may repeat | |
7510 zero or more times. | |
7511 | |
7512 * `( GROUP )+' means that GROUP inside the parentheses may repeat | |
7513 one or more times. | |
7514 | |
7515 * `"STRING"' means a literal STRING. | |
7516 | |
7517 * Menu: | |
7518 | |
7519 * GDB/MI General Design:: | |
7520 * GDB/MI Command Syntax:: | |
7521 * GDB/MI Compatibility with CLI:: | |
7522 * GDB/MI Development and Front Ends:: | |
7523 * GDB/MI Output Records:: | |
7524 * GDB/MI Simple Examples:: | |
7525 * GDB/MI Command Description Format:: | |
7526 * GDB/MI Breakpoint Commands:: | |
7527 * GDB/MI Program Context:: | |
7528 * GDB/MI Thread Commands:: | |
7529 * GDB/MI Ada Tasking Commands:: | |
7530 * GDB/MI Program Execution:: | |
7531 * GDB/MI Stack Manipulation:: | |
7532 * GDB/MI Variable Objects:: | |
7533 * GDB/MI Data Manipulation:: | |
7534 * GDB/MI Tracepoint Commands:: | |
7535 * GDB/MI Symbol Query:: | |
7536 * GDB/MI File Commands:: | |
7537 * GDB/MI Target Manipulation:: | |
7538 * GDB/MI File Transfer Commands:: | |
7539 * GDB/MI Miscellaneous Commands:: | |
7540 | |
7541 | |
7542 File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up:
GDB/MI | |
7543 | |
7544 27.1 GDB/MI General Design | |
7545 ========================== | |
7546 | |
7547 Interaction of a GDB/MI frontend with GDB involves three | |
7548 parts--commands sent to GDB, responses to those commands and | |
7549 notifications. Each command results in exactly one response, | |
7550 indicating either successful completion of the command, or an error. | |
7551 For the commands that do not resume the target, the response contains | |
7552 the requested information. For the commands that resume the target, the | |
7553 response only indicates whether the target was successfully resumed. | |
7554 Notifications is the mechanism for reporting changes in the state of the | |
7555 target, or in GDB state, that cannot conveniently be associated with a | |
7556 command and reported as part of that command response. | |
7557 | |
7558 The important examples of notifications are: | |
7559 * Exec notifications. These are used to report changes in target | |
7560 state--when a target is resumed, or stopped. It would not be | |
7561 feasible to include this information in response of resuming | |
7562 commands, because one resume commands can result in multiple | |
7563 events in different threads. Also, quite some time may pass | |
7564 before any event happens in the target, while a frontend needs to | |
7565 know whether the resuming command itself was successfully executed. | |
7566 | |
7567 * Console output, and status notifications. Console output | |
7568 notifications are used to report output of CLI commands, as well as | |
7569 diagnostics for other commands. Status notifications are used to | |
7570 report the progress of a long-running operation. Naturally, | |
7571 including this information in command response would mean no | |
7572 output is produced until the command is finished, which is | |
7573 undesirable. | |
7574 | |
7575 * General notifications. Commands may have various side effects on | |
7576 the GDB or target state beyond their official purpose. For | |
7577 example, a command may change the selected thread. Although such | |
7578 changes can be included in command response, using notification | |
7579 allows for more orthogonal frontend design. | |
7580 | |
7581 | |
7582 There's no guarantee that whenever an MI command reports an error, | |
7583 GDB or the target are in any specific state, and especially, the state | |
7584 is not reverted to the state before the MI command was processed. | |
7585 Therefore, whenever an MI command results in an error, we recommend | |
7586 that the frontend refreshes all the information shown in the user | |
7587 interface. | |
7588 | |
7589 * Menu: | |
7590 | |
7591 * Context management:: | |
7592 * Asynchronous and non-stop modes:: | |
7593 * Thread groups:: | |
7594 | |
7595 | |
7596 File: gdb.info, Node: Context management, Next: Asynchronous and non-stop mode
s, Up: GDB/MI General Design | |
7597 | |
7598 27.1.1 Context management | |
7599 ------------------------- | |
7600 | |
7601 In most cases when GDB accesses the target, this access is done in | |
7602 context of a specific thread and frame (*note Frames::). Often, even | |
7603 when accessing global data, the target requires that a thread be | |
7604 specified. The CLI interface maintains the selected thread and frame, | |
7605 and supplies them to target on each command. This is convenient, | |
7606 because a command line user would not want to specify that information | |
7607 explicitly on each command, and because user interacts with GDB via a | |
7608 single terminal, so no confusion is possible as to what thread and | |
7609 frame are the current ones. | |
7610 | |
7611 In the case of MI, the concept of selected thread and frame is less | |
7612 useful. First, a frontend can easily remember this information itself. | |
7613 Second, a graphical frontend can have more than one window, each one | |
7614 used for debugging a different thread, and the frontend might want to | |
7615 access additional threads for internal purposes. This increases the | |
7616 risk that by relying on implicitly selected thread, the frontend may be | |
7617 operating on a wrong one. Therefore, each MI command should explicitly | |
7618 specify which thread and frame to operate on. To make it possible, | |
7619 each MI command accepts the `--thread' and `--frame' options, the value | |
7620 to each is GDB identifier for thread and frame to operate on. | |
7621 | |
7622 Usually, each top-level window in a frontend allows the user to | |
7623 select a thread and a frame, and remembers the user selection for | |
7624 further operations. However, in some cases GDB may suggest that the | |
7625 current thread be changed. For example, when stopping on a breakpoint | |
7626 it is reasonable to switch to the thread where breakpoint is hit. For | |
7627 another example, if the user issues the CLI `thread' command via the | |
7628 frontend, it is desirable to change the frontend's selected thread to | |
7629 the one specified by user. GDB communicates the suggestion to change | |
7630 current thread using the `=thread-selected' notification. No such | |
7631 notification is available for the selected frame at the moment. | |
7632 | |
7633 Note that historically, MI shares the selected thread with CLI, so | |
7634 frontends used the `-thread-select' to execute commands in the right | |
7635 context. However, getting this to work right is cumbersome. The | |
7636 simplest way is for frontend to emit `-thread-select' command before | |
7637 every command. This doubles the number of commands that need to be | |
7638 sent. The alternative approach is to suppress `-thread-select' if the | |
7639 selected thread in GDB is supposed to be identical to the thread the | |
7640 frontend wants to operate on. However, getting this optimization right | |
7641 can be tricky. In particular, if the frontend sends several commands | |
7642 to GDB, and one of the commands changes the selected thread, then the | |
7643 behaviour of subsequent commands will change. So, a frontend should | |
7644 either wait for response from such problematic commands, or explicitly | |
7645 add `-thread-select' for all subsequent commands. No frontend is known | |
7646 to do this exactly right, so it is suggested to just always pass the | |
7647 `--thread' and `--frame' options. | |
7648 | |
7649 | |
7650 File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, P
rev: Context management, Up: GDB/MI General Design | |
7651 | |
7652 27.1.2 Asynchronous command execution and non-stop mode | |
7653 ------------------------------------------------------- | |
7654 | |
7655 On some targets, GDB is capable of processing MI commands even while | |
7656 the target is running. This is called "asynchronous command execution" | |
7657 (*note Background Execution::). The frontend may specify a preferrence | |
7658 for asynchronous execution using the `-gdb-set target-async 1' command, | |
7659 which should be emitted before either running the executable or | |
7660 attaching to the target. After the frontend has started the executable | |
7661 or attached to the target, it can find if asynchronous execution is | |
7662 enabled using the `-list-target-features' command. | |
7663 | |
7664 Even if GDB can accept a command while target is running, many | |
7665 commands that access the target do not work when the target is running. | |
7666 Therefore, asynchronous command execution is most useful when combined | |
7667 with non-stop mode (*note Non-Stop Mode::). Then, it is possible to | |
7668 examine the state of one thread, while other threads are running. | |
7669 | |
7670 When a given thread is running, MI commands that try to access the | |
7671 target in the context of that thread may not work, or may work only on | |
7672 some targets. In particular, commands that try to operate on thread's | |
7673 stack will not work, on any target. Commands that read memory, or | |
7674 modify breakpoints, may work or not work, depending on the target. Note | |
7675 that even commands that operate on global state, such as `print', | |
7676 `set', and breakpoint commands, still access the target in the context | |
7677 of a specific thread, so frontend should try to find a stopped thread | |
7678 and perform the operation on that thread (using the `--thread' option). | |
7679 | |
7680 Which commands will work in the context of a running thread is | |
7681 highly target dependent. However, the two commands `-exec-interrupt', | |
7682 to stop a thread, and `-thread-info', to find the state of a thread, | |
7683 will always work. | |
7684 | |
7685 | |
7686 File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, U
p: GDB/MI General Design | |
7687 | |
7688 27.1.3 Thread groups | |
7689 -------------------- | |
7690 | |
7691 GDB may be used to debug several processes at the same time. On some | |
7692 platfroms, GDB may support debugging of several hardware systems, each | |
7693 one having several cores with several different processes running on | |
7694 each core. This section describes the MI mechanism to support such | |
7695 debugging scenarios. | |
7696 | |
7697 The key observation is that regardless of the structure of the | |
7698 target, MI can have a global list of threads, because most commands that | |
7699 accept the `--thread' option do not need to know what process that | |
7700 thread belongs to. Therefore, it is not necessary to introduce neither | |
7701 additional `--process' option, nor an notion of the current process in | |
7702 the MI interface. The only strictly new feature that is required is | |
7703 the ability to find how the threads are grouped into processes. | |
7704 | |
7705 To allow the user to discover such grouping, and to support arbitrary | |
7706 hierarchy of machines/cores/processes, MI introduces the concept of a | |
7707 "thread group". Thread group is a collection of threads and other | |
7708 thread groups. A thread group always has a string identifier, a type, | |
7709 and may have additional attributes specific to the type. A new | |
7710 command, `-list-thread-groups', returns the list of top-level thread | |
7711 groups, which correspond to processes that GDB is debugging at the | |
7712 moment. By passing an identifier of a thread group to the | |
7713 `-list-thread-groups' command, it is possible to obtain the members of | |
7714 specific thread group. | |
7715 | |
7716 To allow the user to easily discover processes, and other objects, he | |
7717 wishes to debug, a concept of "available thread group" is introduced. | |
7718 Available thread group is an thread group that GDB is not debugging, | |
7719 but that can be attached to, using the `-target-attach' command. The | |
7720 list of available top-level thread groups can be obtained using | |
7721 `-list-thread-groups --available'. In general, the content of a thread | |
7722 group may be only retrieved only after attaching to that thread group. | |
7723 | |
7724 Thread groups are related to inferiors (*note Inferiors and | |
7725 Programs::). Each inferior corresponds to a thread group of a special | |
7726 type `process', and some additional operations are permitted on such | |
7727 thread groups. | |
7728 | |
7729 | |
7730 File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with C
LI, Prev: GDB/MI General Design, Up: GDB/MI | |
7731 | |
7732 27.2 GDB/MI Command Syntax | |
7733 ========================== | |
7734 | |
7735 * Menu: | |
7736 | |
7737 * GDB/MI Input Syntax:: | |
7738 * GDB/MI Output Syntax:: | |
7739 | |
7740 | |
7741 File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GD
B/MI Command Syntax | |
7742 | |
7743 27.2.1 GDB/MI Input Syntax | |
7744 -------------------------- | |
7745 | |
7746 `COMMAND ==>' | |
7747 `CLI-COMMAND | MI-COMMAND' | |
7748 | |
7749 `CLI-COMMAND ==>' | |
7750 `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB | |
7751 CLI command. | |
7752 | |
7753 `MI-COMMAND ==>' | |
7754 `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " | |
7755 PARAMETER )* NL' | |
7756 | |
7757 `TOKEN ==>' | |
7758 "any sequence of digits" | |
7759 | |
7760 `OPTION ==>' | |
7761 `"-" PARAMETER [ " " PARAMETER ]' | |
7762 | |
7763 `PARAMETER ==>' | |
7764 `NON-BLANK-SEQUENCE | C-STRING' | |
7765 | |
7766 `OPERATION ==>' | |
7767 _any of the operations described in this chapter_ | |
7768 | |
7769 `NON-BLANK-SEQUENCE ==>' | |
7770 _anything, provided it doesn't contain special characters such as | |
7771 "-", NL, """ and of course " "_ | |
7772 | |
7773 `C-STRING ==>' | |
7774 `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' | |
7775 | |
7776 `NL ==>' | |
7777 `CR | CR-LF' | |
7778 | |
7779 Notes: | |
7780 | |
7781 * The CLI commands are still handled by the MI interpreter; their | |
7782 output is described below. | |
7783 | |
7784 * The `TOKEN', when present, is passed back when the command | |
7785 finishes. | |
7786 | |
7787 * Some MI commands accept optional arguments as part of the parameter | |
7788 list. Each option is identified by a leading `-' (dash) and may be | |
7789 followed by an optional argument parameter. Options occur first | |
7790 in the parameter list and can be delimited from normal parameters | |
7791 using `--' (this is useful when some parameters begin with a dash). | |
7792 | |
7793 Pragmatics: | |
7794 | |
7795 * We want easy access to the existing CLI syntax (for debugging). | |
7796 | |
7797 * We want it to be easy to spot a MI operation. | |
7798 | |
OLD | NEW |