1 This is gdb.info, produced by makeinfo version 4.8 from 2 /Volumes/project-jingyu/android_toolchain/build/../gdb/gdb-7.1.x/gdb/doc/gdb.texinfo. 3 4 INFO-DIR-SECTION Software development 5 START-INFO-DIR-ENTRY 6 * Gdb: (gdb). The GNU debugger. 7 END-INFO-DIR-ENTRY 8 9 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 10 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 11 2010 Free Software Foundation, Inc. 12 13 Permission is granted to copy, distribute and/or modify this document 14 under the terms of the GNU Free Documentation License, Version 1.1 or 15 any later version published by the Free Software Foundation; with the 16 Invariant Sections being "Free Software" and "Free Software Needs Free 17 Documentation", with the Front-Cover Texts being "A GNU Manual," and 18 with the Back-Cover Texts as in (a) below. 19 20 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 21 this GNU Manual. Buying copies from GNU Press supports the FSF in 22 developing GNU and promoting software freedom." 23 24 This file documents the GNU debugger GDB. 25 26 This is the Ninth Edition, of `Debugging with GDB: the GNU 27 Source-Level Debugger' for GDB (GDB) Version 7.1-android-gg2. 28 29 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 30 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 31 2010 Free Software Foundation, Inc. 32 33 Permission is granted to copy, distribute and/or modify this document 34 under the terms of the GNU Free Documentation License, Version 1.1 or 35 any later version published by the Free Software Foundation; with the 36 Invariant Sections being "Free Software" and "Free Software Needs Free 37 Documentation", with the Front-Cover Texts being "A GNU Manual," and 38 with the Back-Cover Texts as in (a) below. 39 40 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 41 this GNU Manual. Buying copies from GNU Press supports the FSF in 42 developing GNU and promoting software freedom." 43 44 45 File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) 46 47 Debugging with GDB 48 ****************** 49 50 This file describes GDB, the GNU symbolic debugger. 51 52 This is the Ninth Edition, for GDB (GDB) Version 7.1-android-gg2. 53 54 Copyright (C) 1988-2010 Free Software Foundation, Inc. 55 56 This edition of the GDB manual is dedicated to the memory of Fred 57 Fish. Fred was a long-standing contributor to GDB and to Free software 58 in general. We will miss him. 59 60 * Menu: 61 62 * Summary:: Summary of GDB 63 * Sample Session:: A sample GDB session 64 65 * Invocation:: Getting in and out of GDB 66 * Commands:: GDB commands 67 * Running:: Running programs under GDB 68 * Stopping:: Stopping and continuing 69 * Reverse Execution:: Running programs backward 70 * Process Record and Replay:: Recording inferior's execution and replaying it 71 * Stack:: Examining the stack 72 * Source:: Examining source files 73 * Data:: Examining data 74 * Optimized Code:: Debugging optimized code 75 * Macros:: Preprocessor Macros 76 * Tracepoints:: Debugging remote targets non-intrusively 77 * Overlays:: Debugging programs that use overlays 78 79 * Languages:: Using GDB with different languages 80 81 * Symbols:: Examining the symbol table 82 * Altering:: Altering execution 83 * GDB Files:: GDB files 84 * Targets:: Specifying a debugging target 85 * Remote Debugging:: Debugging remote programs 86 * Configurations:: Configuration-specific information 87 * Controlling GDB:: Controlling GDB 88 * Extending GDB:: Extending GDB 89 * Interpreters:: Command Interpreters 90 * TUI:: GDB Text User Interface 91 * Emacs:: Using GDB under GNU Emacs 92 * GDB/MI:: GDB's Machine Interface. 93 * Annotations:: GDB's annotation interface. 94 * JIT Interface:: Using the JIT debugging interface. 95 96 * GDB Bugs:: Reporting bugs in GDB 97 98 * Command Line Editing:: Command Line Editing 99 * Using History Interactively:: Using History Interactively 100 * Formatting Documentation:: How to format and print GDB documentation 101 * Installing GDB:: Installing GDB 102 * Maintenance Commands:: Maintenance Commands 103 * Remote Protocol:: GDB Remote Serial Protocol 104 * Agent Expressions:: The GDB Agent Expression Mechanism 105 * Target Descriptions:: How targets can describe themselves to 106 GDB 107 * Operating System Information:: Getting additional information from 108 the operating system 109 * Trace File Format:: GDB trace file format 110 * Copying:: GNU General Public License says 111 how you can copy and share GDB 112 * GNU Free Documentation License:: The license for this documentation 113 * Index:: Index 114 115 116 File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top 117 118 Summary of GDB 119 ************** 120 121 The purpose of a debugger such as GDB is to allow you to see what is 122 going on "inside" another program while it executes--or what another 123 program was doing at the moment it crashed. 124 125 GDB can do four main kinds of things (plus other things in support of 126 these) to help you catch bugs in the act: 127 128 * Start your program, specifying anything that might affect its 129 behavior. 130 131 * Make your program stop on specified conditions. 132 133 * Examine what has happened, when your program has stopped. 134 135 * Change things in your program, so you can experiment with 136 correcting the effects of one bug and go on to learn about another. 137 138 You can use GDB to debug programs written in C and C++. For more 139 information, see *Note Supported Languages: Supported Languages. For 140 more information, see *Note C and C++: C. 141 142 Support for Modula-2 is partial. For information on Modula-2, see 143 *Note Modula-2: Modula-2. 144 145 Debugging Pascal programs which use sets, subranges, file variables, 146 or nested functions does not currently work. GDB does not support 147 entering expressions, printing values, or similar features using Pascal 148 syntax. 149 150 GDB can be used to debug programs written in Fortran, although it 151 may be necessary to refer to some variables with a trailing underscore. 152 153 GDB can be used to debug programs written in Objective-C, using 154 either the Apple/NeXT or the GNU Objective-C runtime. 155 156 * Menu: 157 158 * Free Software:: Freely redistributable software 159 * Contributors:: Contributors to GDB 160 161 162 File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary 163 164 Free Software 165 ============= 166 167 GDB is "free software", protected by the GNU General Public License 168 (GPL). The GPL gives you the freedom to copy or adapt a licensed 169 program--but every person getting a copy also gets with it the freedom 170 to modify that copy (which means that they must get access to the 171 source code), and the freedom to distribute further copies. Typical 172 software companies use copyrights to limit your freedoms; the Free 173 Software Foundation uses the GPL to preserve these freedoms. 174 175 Fundamentally, the General Public License is a license which says 176 that you have these freedoms and that you cannot take these freedoms 177 away from anyone else. 178 179 Free Software Needs Free Documentation 180 ====================================== 181 182 The biggest deficiency in the free software community today is not in 183 the software--it is the lack of good free documentation that we can 184 include with the free software. Many of our most important programs do 185 not come with free reference manuals and free introductory texts. 186 Documentation is an essential part of any software package; when an 187 important free software package does not come with a free manual and a 188 free tutorial, that is a major gap. We have many such gaps today. 189 190 Consider Perl, for instance. The tutorial manuals that people 191 normally use are non-free. How did this come about? Because the 192 authors of those manuals published them with restrictive terms--no 193 copying, no modification, source files not available--which exclude 194 them from the free software world. 195 196 That wasn't the first time this sort of thing happened, and it was 197 far from the last. Many times we have heard a GNU user eagerly 198 describe a manual that he is writing, his intended contribution to the 199 community, only to learn that he had ruined everything by signing a 200 publication contract to make it non-free. 201 202 Free documentation, like free software, is a matter of freedom, not 203 price. The problem with the non-free manual is not that publishers 204 charge a price for printed copies--that in itself is fine. (The Free 205 Software Foundation sells printed copies of manuals, too.) The problem 206 is the restrictions on the use of the manual. Free manuals are 207 available in source code form, and give you permission to copy and 208 modify. Non-free manuals do not allow this. 209 210 The criteria of freedom for a free manual are roughly the same as for 211 free software. Redistribution (including the normal kinds of 212 commercial redistribution) must be permitted, so that the manual can 213 accompany every copy of the program, both on-line and on paper. 214 215 Permission for modification of the technical content is crucial too. 216 When people modify the software, adding or changing features, if they 217 are conscientious they will change the manual too--so they can provide 218 accurate and clear documentation for the modified program. A manual 219 that leaves you no choice but to write a new manual to document a 220 changed version of the program is not really available to our community. 221 222 Some kinds of limits on the way modification is handled are 223 acceptable. For example, requirements to preserve the original 224 author's copyright notice, the distribution terms, or the list of 225 authors, are ok. It is also no problem to require modified versions to 226 include notice that they were modified. Even entire sections that may 227 not be deleted or changed are acceptable, as long as they deal with 228 nontechnical topics (like this one). These kinds of restrictions are 229 acceptable because they don't obstruct the community's normal use of 230 the manual. 231 232 However, it must be possible to modify all the _technical_ content 233 of the manual, and then distribute the result in all the usual media, 234 through all the usual channels. Otherwise, the restrictions obstruct 235 the use of the manual, it is not free, and we need another manual to 236 replace it. 237 238 Please spread the word about this issue. Our community continues to 239 lose manuals to proprietary publishing. If we spread the word that 240 free software needs free reference manuals and free tutorials, perhaps 241 the next person who wants to contribute by writing documentation will 242 realize, before it is too late, that only free manuals contribute to 243 the free software community. 244 245 If you are writing documentation, please insist on publishing it 246 under the GNU Free Documentation License or another free documentation 247 license. Remember that this decision requires your approval--you don't 248 have to let the publisher decide. Some commercial publishers will use 249 a free license if you insist, but they will not propose the option; it 250 is up to you to raise the issue and say firmly that this is what you 251 want. If the publisher you are dealing with refuses, please try other 252 publishers. If you're not sure whether a proposed license is free, 253 write to <licensing (a] gnu.org>. 254 255 You can encourage commercial publishers to sell more free, copylefted 256 manuals and tutorials by buying them, and particularly by buying copies 257 from the publishers that paid for their writing or for major 258 improvements. Meanwhile, try to avoid buying non-free documentation at 259 all. Check the distribution terms of a manual before you buy it, and 260 insist that whoever seeks your business must respect your freedom. 261 Check the history of the book, and try to reward the publishers that 262 have paid or pay the authors to work on it. 263 264 The Free Software Foundation maintains a list of free documentation 265 published by other publishers, at 266 `http://www.fsf.org/doc/other-free-books.html'. 267 268 269 File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary 270 271 Contributors to GDB 272 =================== 273 274 Richard Stallman was the original author of GDB, and of many other GNU 275 programs. Many others have contributed to its development. This 276 section attempts to credit major contributors. One of the virtues of 277 free software is that everyone is free to contribute to it; with 278 regret, we cannot actually acknowledge everyone here. The file 279 `ChangeLog' in the GDB distribution approximates a blow-by-blow account. 280 281 Changes much prior to version 2.0 are lost in the mists of time. 282 283 _Plea:_ Additions to this section are particularly welcome. If you 284 or your friends (or enemies, to be evenhanded) have been unfairly 285 omitted from this list, we would like to add your names! 286 287 So that they may not regard their many labors as thankless, we 288 particularly thank those who shepherded GDB through major releases: 289 Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim 290 Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs 291 (release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, 292 and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, 293 and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim 294 Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 295 3.1, and 3.0). 296 297 Richard Stallman, assisted at various times by Peter TerMaat, Chris 298 Hanson, and Richard Mlynarik, handled releases through 2.8. 299 300 Michael Tiemann is the author of most of the GNU C++ support in GDB, 301 with significant additional contributions from Per Bothner and Daniel 302 Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ 303 was by Peter TerMaat (who also did much general update work leading to 304 release 3.0). 305 306 GDB uses the BFD subroutine library to examine multiple object-file 307 formats; BFD was a joint project of David V. Henkel-Wallace, Rich 308 Pixley, Steve Chamberlain, and John Gilmore. 309 310 David Johnson wrote the original COFF support; Pace Willison did the 311 original support for encapsulated COFF. 312 313 Brent Benson of Harris Computer Systems contributed DWARF 2 support. 314 315 Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 316 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 317 support. Jean-Daniel Fekete contributed Sun 386i support. Chris 318 Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki 319 Hasei contributed Sony/News OS 3 support. David Johnson contributed 320 Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. 321 Jeff Law contributed HP PA and SOM support. Keith Packard contributed 322 NS32K support. Doug Rabson contributed Acorn Risc Machine support. 323 Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith 324 contributed Convex support (and Fortran debugging). Jonathan Stone 325 contributed Pyramid support. Michael Tiemann contributed SPARC support. 326 Tim Tucker contributed support for the Gould NP1 and Gould Powernode. 327 Pace Willison contributed Intel 386 support. Jay Vosburgh contributed 328 Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. 329 330 Andreas Schwab contributed M68K GNU/Linux support. 331 332 Rich Schaefer and Peter Schauer helped with support of SunOS shared 333 libraries. 334 335 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about 336 several machine instruction sets. 337 338 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped 339 develop remote debugging. Intel Corporation, Wind River Systems, AMD, 340 and ARM contributed remote debugging modules for the i960, VxWorks, 341 A29K UDI, and RDI targets, respectively. 342 343 Brian Fox is the author of the readline libraries providing 344 command-line editing and command history. 345 346 Andrew Beers of SUNY Buffalo wrote the language-switching code, the 347 Modula-2 support, and contributed the Languages chapter of this manual. 348 349 Fred Fish wrote most of the support for Unix System Vr4. He also 350 enhanced the command-completion support to cover C++ overloaded symbols. 351 352 Hitachi America (now Renesas America), Ltd. sponsored the support for 353 H8/300, H8/500, and Super-H processors. 354 355 NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx 356 processors. 357 358 Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and 359 M32R/D processors. 360 361 Toshiba sponsored the support for the TX39 Mips processor. 362 363 Matsushita sponsored the support for the MN10200 and MN10300 364 processors. 365 366 Fujitsu sponsored the support for SPARClite and FR30 processors. 367 368 Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 369 watchpoints. 370 371 Michael Snyder added support for tracepoints. 372 373 Stu Grossman wrote gdbserver. 374 375 Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly 376 innumerable bug fixes and cleanups throughout GDB. 377 378 The following people at the Hewlett-Packard Company contributed 379 support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 380 (narrow mode), HP's implementation of kernel threads, HP's aC++ 381 compiler, and the Text User Interface (nee Terminal User Interface): 382 Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, 383 Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase 384 provided HP-specific information in this manual. 385 386 DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert 387 Hoehne made significant contributions to the DJGPP port. 388 389 Cygnus Solutions has sponsored GDB maintenance and much of its 390 development since 1991. Cygnus engineers who have worked on GDB 391 fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 392 Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 393 Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 394 Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 395 Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 396 addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 397 JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 398 Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 399 Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 400 Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 401 Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 402 Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 403 Zuhn have made contributions both large and small. 404 405 Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for 406 Cygnus Solutions, implemented the original GDB/MI interface. 407 408 Jim Blandy added support for preprocessor macros, while working for 409 Red Hat. 410 411 Andrew Cagney designed GDB's architecture vector. Many people 412 including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, 413 Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, 414 Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna 415 Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration 416 of old architectures to this new framework. 417 418 Andrew Cagney completely re-designed and re-implemented GDB's 419 unwinder framework, this consisting of a fresh new design featuring 420 frame IDs, independent frame sniffers, and the sentinel frame. Mark 421 Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind 422 unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad 423 unwinders. The architecture-specific changes, each involving a 424 complete rewrite of the architecture's frame code, were carried out by 425 Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane 426 Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel 427 Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei 428 Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich 429 Weigand. 430 431 Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from 432 Tensilica, Inc. contributed support for Xtensa processors. Others who 433 have worked on the Xtensa port of GDB in the past include Steve Tjiang, 434 John Newlin, and Scott Foehner. 435 436 Michael Eager and staff of Xilinx, Inc., contributed support for the 437 Xilinx MicroBlaze architecture. 438 439 440 File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top 441 442 1 A Sample GDB Session 443 ********************** 444 445 You can use this manual at your leisure to read all about GDB. 446 However, a handful of commands are enough to get started using the 447 debugger. This chapter illustrates those commands. 448 449 One of the preliminary versions of GNU `m4' (a generic macro 450 processor) exhibits the following bug: sometimes, when we change its 451 quote strings from the default, the commands used to capture one macro 452 definition within another stop working. In the following short `m4' 453 session, we define a macro `foo' which expands to `0000'; we then use 454 the `m4' built-in `defn' to define `bar' as the same thing. However, 455 when we change the open quote string to `<QUOTE>' and the close quote 456 string to `<UNQUOTE>', the same procedure fails to define a new synonym 457 `baz': 458 459 $ cd gnu/m4 460 $ ./m4 461 define(foo,0000) 462 463 foo 464 0000 465 define(bar,defn(`foo')) 466 467 bar 468 0000 469 changequote(<QUOTE>,<UNQUOTE>) 470 471 define(baz,defn(<QUOTE>foo<UNQUOTE>)) 472 baz 473 Ctrl-d 474 m4: End of input: 0: fatal error: EOF in string 475 476 Let us use GDB to try to see what is going on. 477 478 $ gdb m4 479 GDB is free software and you are welcome to distribute copies 480 of it under certain conditions; type "show copying" to see 481 the conditions. 482 There is absolutely no warranty for GDB; type "show warranty" 483 for details. 484 485 GDB 7.1-android-gg2, Copyright 1999 Free Software Foundation, Inc... 486 (gdb) 487 488 GDB reads only enough symbol data to know where to find the rest when 489 needed; as a result, the first prompt comes up very quickly. We now 490 tell GDB to use a narrower display width than usual, so that examples 491 fit in this manual. 492 493 (gdb) set width 70 494 495 We need to see how the `m4' built-in `changequote' works. Having 496 looked at the source, we know the relevant subroutine is 497 `m4_changequote', so we set a breakpoint there with the GDB `break' 498 command. 499 500 (gdb) break m4_changequote 501 Breakpoint 1 at 0x62f4: file builtin.c, line 879. 502 503 Using the `run' command, we start `m4' running under GDB control; as 504 long as control does not reach the `m4_changequote' subroutine, the 505 program runs as usual: 506 507 (gdb) run 508 Starting program: /work/Editorial/gdb/gnu/m4/m4 509 define(foo,0000) 510 511 foo 512 0000 513 514 To trigger the breakpoint, we call `changequote'. GDB suspends 515 execution of `m4', displaying information about the context where it 516 stops. 517 518 changequote(<QUOTE>,<UNQUOTE>) 519 520 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 521 at builtin.c:879 522 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 523 524 Now we use the command `n' (`next') to advance execution to the next 525 line of the current function. 526 527 (gdb) n 528 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ 529 : nil, 530 531 `set_quotes' looks like a promising subroutine. We can go into it by 532 using the command `s' (`step') instead of `next'. `step' goes to the 533 next line to be executed in _any_ subroutine, so it steps into 534 `set_quotes'. 535 536 (gdb) s 537 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 538 at input.c:530 539 530 if (lquote != def_lquote) 540 541 The display that shows the subroutine where `m4' is now suspended (and 542 its arguments) is called a stack frame display. It shows a summary of 543 the stack. We can use the `backtrace' command (which can also be 544 spelled `bt'), to see where we are in the stack as a whole: the 545 `backtrace' command displays a stack frame for each active subroutine. 546 547 (gdb) bt 548 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 549 at input.c:530 550 #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) 551 at builtin.c:882 552 #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 553 #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 554 at macro.c:71 555 #4 0x79dc in expand_input () at macro.c:40 556 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 557 558 We step through a few more lines to see what happens. The first two 559 times, we can use `s'; the next two times we use `n' to avoid falling 560 into the `xstrdup' subroutine. 561 562 (gdb) s 563 0x3b5c 532 if (rquote != def_rquote) 564 (gdb) s 565 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ 566 def_lquote : xstrdup(lq); 567 (gdb) n 568 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 569 : xstrdup(rq); 570 (gdb) n 571 538 len_lquote = strlen(rquote); 572 573 The last line displayed looks a little odd; we can examine the variables 574 `lquote' and `rquote' to see if they are in fact the new left and right 575 quotes we specified. We use the command `p' (`print') to see their 576 values. 577 578 (gdb) p lquote 579 $1 = 0x35d40 "<QUOTE>" 580 (gdb) p rquote 581 $2 = 0x35d50 "<UNQUOTE>" 582 583 `lquote' and `rquote' are indeed the new left and right quotes. To 584 look at some context, we can display ten lines of source surrounding 585 the current line with the `l' (`list') command. 586 587 (gdb) l 588 533 xfree(rquote); 589 534 590 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ 591 : xstrdup (lq); 592 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 593 : xstrdup (rq); 594 537 595 538 len_lquote = strlen(rquote); 596 539 len_rquote = strlen(lquote); 597 540 } 598 541 599 542 void 600 601 Let us step past the two lines that set `len_lquote' and `len_rquote', 602 and then examine the values of those variables. 603 604 (gdb) n 605 539 len_rquote = strlen(lquote); 606 (gdb) n 607 540 } 608 (gdb) p len_lquote 609 $3 = 9 610 (gdb) p len_rquote 611 $4 = 7 612 613 That certainly looks wrong, assuming `len_lquote' and `len_rquote' are 614 meant to be the lengths of `lquote' and `rquote' respectively. We can 615 set them to better values using the `p' command, since it can print the 616 value of any expression--and that expression can include subroutine 617 calls and assignments. 618 619 (gdb) p len_lquote=strlen(lquote) 620 $5 = 7 621 (gdb) p len_rquote=strlen(rquote) 622 $6 = 9 623 624 Is that enough to fix the problem of using the new quotes with the `m4' 625 built-in `defn'? We can allow `m4' to continue executing with the `c' 626 (`continue') command, and then try the example that caused trouble 627 initially: 628 629 (gdb) c 630 Continuing. 631 632 define(baz,defn(<QUOTE>foo<UNQUOTE>)) 633 634 baz 635 0000 636 637 Success! The new quotes now work just as well as the default ones. The 638 problem seems to have been just the two typos defining the wrong 639 lengths. We allow `m4' exit by giving it an EOF as input: 640 641 Ctrl-d 642 Program exited normally. 643 644 The message `Program exited normally.' is from GDB; it indicates `m4' 645 has finished executing. We can end our GDB session with the GDB `quit' 646 command. 647 648 (gdb) quit 649 650 651 File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top 652 653 2 Getting In and Out of GDB 654 *************************** 655 656 This chapter discusses how to start GDB, and how to get out of it. The 657 essentials are: 658 * type `gdb' to start GDB. 659 660 * type `quit' or `Ctrl-d' to exit. 661 662 * Menu: 663 664 * Invoking GDB:: How to start GDB 665 * Quitting GDB:: How to quit GDB 666 * Shell Commands:: How to use shell commands inside GDB 667 * Logging Output:: How to log GDB's output to a file 668 669 670 File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation 671 672 2.1 Invoking GDB 673 ================ 674 675 Invoke GDB by running the program `gdb'. Once started, GDB reads 676 commands from the terminal until you tell it to exit. 677 678 You can also run `gdb' with a variety of arguments and options, to 679 specify more of your debugging environment at the outset. 680 681 The command-line options described here are designed to cover a 682 variety of situations; in some environments, some of these options may 683 effectively be unavailable. 684 685 The most usual way to start GDB is with one argument, specifying an 686 executable program: 687 688 gdb PROGRAM 689 690 You can also start with both an executable program and a core file 691 specified: 692 693 gdb PROGRAM CORE 694 695 You can, instead, specify a process ID as a second argument, if you 696 want to debug a running process: 697 698 gdb PROGRAM 1234 699 700 would attach GDB to process `1234' (unless you also have a file named 701 `1234'; GDB does check for a core file first). 702 703 Taking advantage of the second command-line argument requires a 704 fairly complete operating system; when you use GDB as a remote debugger 705 attached to a bare board, there may not be any notion of "process", and 706 there is often no way to get a core dump. GDB will warn you if it is 707 unable to attach or to read core dumps. 708 709 You can optionally have `gdb' pass any arguments after the 710 executable file to the inferior using `--args'. This option stops 711 option processing. 712 gdb --args gcc -O2 -c foo.c 713 This will cause `gdb' to debug `gcc', and to set `gcc''s 714 command-line arguments (*note Arguments::) to `-O2 -c foo.c'. 715 716 You can run `gdb' without printing the front material, which 717 describes GDB's non-warranty, by specifying `-silent': 718 719 gdb -silent 720 721 You can further control how GDB starts up by using command-line 722 options. GDB itself can remind you of the options available. 723 724 Type 725 726 gdb -help 727 728 to display all available options and briefly describe their use (`gdb 729 -h' is a shorter equivalent). 730 731 All options and command line arguments you give are processed in 732 sequential order. The order makes a difference when the `-x' option is 733 used. 734 735 * Menu: 736 737 * File Options:: Choosing files 738 * Mode Options:: Choosing modes 739 * Startup:: What GDB does during startup 740 741 742 File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB 743 744 2.1.1 Choosing Files 745 -------------------- 746 747 When GDB starts, it reads any arguments other than options as 748 specifying an executable file and core file (or process ID). This is 749 the same as if the arguments were specified by the `-se' and `-c' (or 750 `-p') options respectively. (GDB reads the first argument that does 751 not have an associated option flag as equivalent to the `-se' option 752 followed by that argument; and the second argument that does not have 753 an associated option flag, if any, as equivalent to the `-c'/`-p' 754 option followed by that argument.) If the second argument begins with 755 a decimal digit, GDB will first attempt to attach to it as a process, 756 and if that fails, attempt to open it as a corefile. If you have a 757 corefile whose name begins with a digit, you can prevent GDB from 758 treating it as a pid by prefixing it with `./', e.g. `./12345'. 759 760 If GDB has not been configured to included core file support, such 761 as for most embedded targets, then it will complain about a second 762 argument and ignore it. 763 764 Many options have both long and short forms; both are shown in the 765 following list. GDB also recognizes the long forms if you truncate 766 them, so long as enough of the option is present to be unambiguous. 767 (If you prefer, you can flag option arguments with `--' rather than 768 `-', though we illustrate the more usual convention.) 769 770 `-symbols FILE' 771 `-s FILE' 772 Read symbol table from file FILE. 773 774 `-exec FILE' 775 `-e FILE' 776 Use file FILE as the executable file to execute when appropriate, 777 and for examining pure data in conjunction with a core dump. 778 779 `-se FILE' 780 Read symbol table from file FILE and use it as the executable file. 781 782 `-core FILE' 783 `-c FILE' 784 Use file FILE as a core dump to examine. 785 786 `-pid NUMBER' 787 `-p NUMBER' 788 Connect to process ID NUMBER, as with the `attach' command. 789 790 `-command FILE' 791 `-x FILE' 792 Execute commands from file FILE. The contents of this file is 793 evaluated exactly as the `source' command would. *Note Command 794 files: Command Files. 795 796 `-eval-command COMMAND' 797 `-ex COMMAND' 798 Execute a single GDB command. 799 800 This option may be used multiple times to call multiple commands. 801 It may also be interleaved with `-command' as required. 802 803 gdb -ex 'target sim' -ex 'load' \ 804 -x setbreakpoints -ex 'run' a.out 805 806 `-directory DIRECTORY' 807 `-d DIRECTORY' 808 Add DIRECTORY to the path to search for source and script files. 809 810 `-r' 811 `-readnow' 812 Read each symbol file's entire symbol table immediately, rather 813 than the default, which is to read it incrementally as it is 814 needed. This makes startup slower, but makes future operations 815 faster. 816 817 818 819 File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB 820 821 2.1.2 Choosing Modes 822 -------------------- 823 824 You can run GDB in various alternative modes--for example, in batch 825 mode or quiet mode. 826 827 `-nx' 828 `-n' 829 Do not execute commands found in any initialization files. 830 Normally, GDB executes the commands in these files after all the 831 command options and arguments have been processed. *Note Command 832 Files: Command Files. 833 834 `-quiet' 835 `-silent' 836 `-q' 837 "Quiet". Do not print the introductory and copyright messages. 838 These messages are also suppressed in batch mode. 839 840 `-batch' 841 Run in batch mode. Exit with status `0' after processing all the 842 command files specified with `-x' (and all commands from 843 initialization files, if not inhibited with `-n'). Exit with 844 nonzero status if an error occurs in executing the GDB commands in 845 the command files. 846 847 Batch mode may be useful for running GDB as a filter, for example 848 to download and run a program on another computer; in order to 849 make this more useful, the message 850 851 Program exited normally. 852 853 (which is ordinarily issued whenever a program running under GDB 854 control terminates) is not issued when running in batch mode. 855 856 `-batch-silent' 857 Run in batch mode exactly like `-batch', but totally silently. All 858 GDB output to `stdout' is prevented (`stderr' is unaffected). 859 This is much quieter than `-silent' and would be useless for an 860 interactive session. 861 862 This is particularly useful when using targets that give `Loading 863 section' messages, for example. 864 865 Note that targets that give their output via GDB, as opposed to 866 writing directly to `stdout', will also be made silent. 867 868 `-return-child-result' 869 The return code from GDB will be the return code from the child 870 process (the process being debugged), with the following 871 exceptions: 872 873 * GDB exits abnormally. E.g., due to an incorrect argument or 874 an internal error. In this case the exit code is the same as 875 it would have been without `-return-child-result'. 876 877 * The user quits with an explicit value. E.g., `quit 1'. 878 879 * The child process never runs, or is not allowed to terminate, 880 in which case the exit code will be -1. 881 882 This option is useful in conjunction with `-batch' or 883 `-batch-silent', when GDB is being used as a remote program loader 884 or simulator interface. 885 886 `-nowindows' 887 `-nw' 888 "No windows". If GDB comes with a graphical user interface (GUI) 889 built in, then this option tells GDB to only use the command-line 890 interface. If no GUI is available, this option has no effect. 891 892 `-windows' 893 `-w' 894 If GDB includes a GUI, then this option requires it to be used if 895 possible. 896 897 `-cd DIRECTORY' 898 Run GDB using DIRECTORY as its working directory, instead of the 899 current directory. 900 901 `-fullname' 902 `-f' 903 GNU Emacs sets this option when it runs GDB as a subprocess. It 904 tells GDB to output the full file name and line number in a 905 standard, recognizable fashion each time a stack frame is 906 displayed (which includes each time your program stops). This 907 recognizable format looks like two `\032' characters, followed by 908 the file name, line number and character position separated by 909 colons, and a newline. The Emacs-to-GDB interface program uses 910 the two `\032' characters as a signal to display the source code 911 for the frame. 912 913 `-epoch' 914 The Epoch Emacs-GDB interface sets this option when it runs GDB as 915 a subprocess. It tells GDB to modify its print routines so as to 916 allow Epoch to display values of expressions in a separate window. 917 918 `-annotate LEVEL' 919 This option sets the "annotation level" inside GDB. Its effect is 920 identical to using `set annotate LEVEL' (*note Annotations::). 921 The annotation LEVEL controls how much information GDB prints 922 together with its prompt, values of expressions, source lines, and 923 other types of output. Level 0 is the normal, level 1 is for use 924 when GDB is run as a subprocess of GNU Emacs, level 3 is the 925 maximum annotation suitable for programs that control GDB, and 926 level 2 has been deprecated. 927 928 The annotation mechanism has largely been superseded by GDB/MI 929 (*note GDB/MI::). 930 931 `--args' 932 Change interpretation of command line so that arguments following 933 the executable file are passed as command line arguments to the 934 inferior. This option stops option processing. 935 936 `-baud BPS' 937 `-b BPS' 938 Set the line speed (baud rate or bits per second) of any serial 939 interface used by GDB for remote debugging. 940 941 `-l TIMEOUT' 942 Set the timeout (in seconds) of any communication used by GDB for 943 remote debugging. 944 945 `-tty DEVICE' 946 `-t DEVICE' 947 Run using DEVICE for your program's standard input and output. 948 949 `-tui' 950 Activate the "Text User Interface" when starting. The Text User 951 Interface manages several text windows on the terminal, showing 952 source, assembly, registers and GDB command outputs (*note GDB 953 Text User Interface: TUI.). Alternatively, the Text User 954 Interface can be enabled by invoking the program `gdbtui'. Do not 955 use this option if you run GDB from Emacs (*note Using GDB under 956 GNU Emacs: Emacs.). 957 958 `-interpreter INTERP' 959 Use the interpreter INTERP for interface with the controlling 960 program or device. This option is meant to be set by programs 961 which communicate with GDB using it as a back end. *Note Command 962 Interpreters: Interpreters. 963 964 `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the 965 "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included 966 since GDB version 6.0. The previous GDB/MI interface, included in 967 GDB version 5.3 and selected with `--interpreter=mi1', is 968 deprecated. Earlier GDB/MI interfaces are no longer supported. 969 970 `-write' 971 Open the executable and core files for both reading and writing. 972 This is equivalent to the `set write on' command inside GDB (*note 973 Patching::). 974 975 `-statistics' 976 This option causes GDB to print statistics about time and memory 977 usage after it completes each command and returns to the prompt. 978 979 `-version' 980 This option causes GDB to print its version number and no-warranty 981 blurb, and exit. 982 983 984 985 File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB 986 987 2.1.3 What GDB Does During Startup 988 ---------------------------------- 989 990 Here's the description of what GDB does during session startup: 991 992 1. Sets up the command interpreter as specified by the command line 993 (*note interpreter: Mode Options.). 994 995 2. Reads the system-wide "init file" (if `--with-system-gdbinit' was 996 used when building GDB; *note System-wide configuration and 997 settings: System-wide configuration.) and executes all the 998 commands in that file. 999 1000 3. Reads the init file (if any) in your home directory(1) and 1001 executes all the commands in that file. 1002 1003 4. Processes command line options and operands. 1004 1005 5. Reads and executes the commands from init file (if any) in the 1006 current working directory. This is only done if the current 1007 directory is different from your home directory. Thus, you can 1008 have more than one init file, one generic in your home directory, 1009 and another, specific to the program you are debugging, in the 1010 directory where you invoke GDB. 1011 1012 6. Reads command files specified by the `-x' option. *Note Command 1013 Files::, for more details about GDB command files. 1014 1015 7. Reads the command history recorded in the "history file". *Note 1016 Command History::, for more details about the command history and 1017 the files where GDB records it. 1018 1019 Init files use the same syntax as "command files" (*note Command 1020 Files::) and are processed by GDB in the same way. The init file in 1021 your home directory can set options (such as `set complaints') that 1022 affect subsequent processing of command line options and operands. 1023 Init files are not executed if you use the `-nx' option (*note Choosing 1024 Modes: Mode Options.). 1025 1026 To display the list of init files loaded by gdb at startup, you can 1027 use `gdb --help'. 1028 1029 The GDB init files are normally called `.gdbinit'. The DJGPP port 1030 of GDB uses the name `gdb.ini', due to the limitations of file names 1031 imposed by DOS filesystems. The Windows ports of GDB use the standard 1032 name, but if they find a `gdb.ini' file, they warn you about that and 1033 suggest to rename the file to the standard name. 1034 1035 ---------- Footnotes ---------- 1036 1037 (1) On DOS/Windows systems, the home directory is the one pointed to 1038 by the `HOME' environment variable. 1039 1040 1041 File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation 1042 1043 2.2 Quitting GDB 1044 ================ 1045 1046 `quit [EXPRESSION]' 1047 `q' 1048 To exit GDB, use the `quit' command (abbreviated `q'), or type an 1049 end-of-file character (usually `Ctrl-d'). If you do not supply 1050 EXPRESSION, GDB will terminate normally; otherwise it will 1051 terminate using the result of EXPRESSION as the error code. 1052 1053 An interrupt (often `Ctrl-c') does not exit from GDB, but rather 1054 terminates the action of any GDB command that is in progress and 1055 returns to GDB command level. It is safe to type the interrupt 1056 character at any time because GDB does not allow it to take effect 1057 until a time when it is safe. 1058 1059 If you have been using GDB to control an attached process or device, 1060 you can release it with the `detach' command (*note Debugging an 1061 Already-running Process: Attach.). 1062 1063 1064 File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation 1065 1066 2.3 Shell Commands 1067 ================== 1068 1069 If you need to execute occasional shell commands during your debugging 1070 session, there is no need to leave or suspend GDB; you can just use the 1071 `shell' command. 1072 1073 `shell COMMAND STRING' 1074 Invoke a standard shell to execute COMMAND STRING. If it exists, 1075 the environment variable `SHELL' determines which shell to run. 1076 Otherwise GDB uses the default shell (`/bin/sh' on Unix systems, 1077 `COMMAND.COM' on MS-DOS, etc.). 1078 1079 The utility `make' is often needed in development environments. You 1080 do not have to use the `shell' command for this purpose in GDB: 1081 1082 `make MAKE-ARGS' 1083 Execute the `make' program with the specified arguments. This is 1084 equivalent to `shell make MAKE-ARGS'. 1085 1086 1087 File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation 1088 1089 2.4 Logging Output 1090 ================== 1091 1092 You may want to save the output of GDB commands to a file. There are 1093 several commands to control GDB's logging. 1094 1095 `set logging on' 1096 Enable logging. 1097 1098 `set logging off' 1099 Disable logging. 1100 1101 `set logging file FILE' 1102 Change the name of the current logfile. The default logfile is 1103 `gdb.txt'. 1104 1105 `set logging overwrite [on|off]' 1106 By default, GDB will append to the logfile. Set `overwrite' if 1107 you want `set logging on' to overwrite the logfile instead. 1108 1109 `set logging redirect [on|off]' 1110 By default, GDB output will go to both the terminal and the 1111 logfile. Set `redirect' if you want output to go only to the log 1112 file. 1113 1114 `show logging' 1115 Show the current values of the logging settings. 1116 1117 1118 File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top 1119 1120 3 GDB Commands 1121 ************** 1122 1123 You can abbreviate a GDB command to the first few letters of the command 1124 name, if that abbreviation is unambiguous; and you can repeat certain 1125 GDB commands by typing just <RET>. You can also use the <TAB> key to 1126 get GDB to fill out the rest of a word in a command (or to show you the 1127 alternatives available, if there is more than one possibility). 1128 1129 * Menu: 1130 1131 * Command Syntax:: How to give commands to GDB 1132 * Completion:: Command completion 1133 * Help:: How to ask GDB for help 1134 1135 1136 File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands 1137 1138 3.1 Command Syntax 1139 ================== 1140 1141 A GDB command is a single line of input. There is no limit on how long 1142 it can be. It starts with a command name, which is followed by 1143 arguments whose meaning depends on the command name. For example, the 1144 command `step' accepts an argument which is the number of times to 1145 step, as in `step 5'. You can also use the `step' command with no 1146 arguments. Some commands do not allow any arguments. 1147 1148 GDB command names may always be truncated if that abbreviation is 1149 unambiguous. Other possible command abbreviations are listed in the 1150 documentation for individual commands. In some cases, even ambiguous 1151 abbreviations are allowed; for example, `s' is specially defined as 1152 equivalent to `step' even though there are other commands whose names 1153 start with `s'. You can test abbreviations by using them as arguments 1154 to the `help' command. 1155 1156 A blank line as input to GDB (typing just <RET>) means to repeat the 1157 previous command. Certain commands (for example, `run') will not 1158 repeat this way; these are commands whose unintentional repetition 1159 might cause trouble and which you are unlikely to want to repeat. 1160 User-defined commands can disable this feature; see *Note dont-repeat: 1161 Define. 1162 1163 The `list' and `x' commands, when you repeat them with <RET>, 1164 construct new arguments rather than repeating exactly as typed. This 1165 permits easy scanning of source or memory. 1166 1167 GDB can also use <RET> in another way: to partition lengthy output, 1168 in a way similar to the common utility `more' (*note Screen Size: 1169 Screen Size.). Since it is easy to press one <RET> too many in this 1170 situation, GDB disables command repetition after any command that 1171 generates this sort of display. 1172 1173 Any text from a `#' to the end of the line is a comment; it does 1174 nothing. This is useful mainly in command files (*note Command Files: 1175 Command Files.). 1176 1177 The `Ctrl-o' binding is useful for repeating a complex sequence of 1178 commands. This command accepts the current line, like <RET>, and then 1179 fetches the next line relative to the current line from the history for 1180 editing. 1181 1182 1183 File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands 1184 1185 3.2 Command Completion 1186 ====================== 1187 1188 GDB can fill in the rest of a word in a command for you, if there is 1189 only one possibility; it can also show you what the valid possibilities 1190 are for the next word in a command, at any time. This works for GDB 1191 commands, GDB subcommands, and the names of symbols in your program. 1192 1193 Press the <TAB> key whenever you want GDB to fill out the rest of a 1194 word. If there is only one possibility, GDB fills in the word, and 1195 waits for you to finish the command (or press <RET> to enter it). For 1196 example, if you type 1197 1198 (gdb) info bre <TAB> 1199 1200 GDB fills in the rest of the word `breakpoints', since that is the only 1201 `info' subcommand beginning with `bre': 1202 1203 (gdb) info breakpoints 1204 1205 You can either press <RET> at this point, to run the `info breakpoints' 1206 command, or backspace and enter something else, if `breakpoints' does 1207 not look like the command you expected. (If you were sure you wanted 1208 `info breakpoints' in the first place, you might as well just type 1209 <RET> immediately after `info bre', to exploit command abbreviations 1210 rather than command completion). 1211 1212 If there is more than one possibility for the next word when you 1213 press <TAB>, GDB sounds a bell. You can either supply more characters 1214 and try again, or just press <TAB> a second time; GDB displays all the 1215 possible completions for that word. For example, you might want to set 1216 a breakpoint on a subroutine whose name begins with `make_', but when 1217 you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again 1218 displays all the function names in your program that begin with those 1219 characters, for example: 1220 1221 (gdb) b make_ <TAB> 1222 GDB sounds bell; press <TAB> again, to see: 1223 make_a_section_from_file make_environ 1224 make_abs_section make_function_type 1225 make_blockvector make_pointer_type 1226 make_cleanup make_reference_type 1227 make_command make_symbol_completion_list 1228 (gdb) b make_ 1229 1230 After displaying the available possibilities, GDB copies your partial 1231 input (`b make_' in the example) so you can finish the command. 1232 1233 If you just want to see the list of alternatives in the first place, 1234 you can press `M-?' rather than pressing <TAB> twice. `M-?' means 1235 `<META> ?'. You can type this either by holding down a key designated 1236 as the <META> shift on your keyboard (if there is one) while typing 1237 `?', or as <ESC> followed by `?'. 1238 1239 Sometimes the string you need, while logically a "word", may contain 1240 parentheses or other characters that GDB normally excludes from its 1241 notion of a word. To permit word completion to work in this situation, 1242 you may enclose words in `'' (single quote marks) in GDB commands. 1243 1244 The most likely situation where you might need this is in typing the 1245 name of a C++ function. This is because C++ allows function 1246 overloading (multiple definitions of the same function, distinguished 1247 by argument type). For example, when you want to set a breakpoint you 1248 may need to distinguish whether you mean the version of `name' that 1249 takes an `int' parameter, `name(int)', or the version that takes a 1250 `float' parameter, `name(float)'. To use the word-completion 1251 facilities in this situation, type a single quote `'' at the beginning 1252 of the function name. This alerts GDB that it may need to consider 1253 more information than usual when you press <TAB> or `M-?' to request 1254 word completion: 1255 1256 (gdb) b 'bubble( M-? 1257 bubble(double,double) bubble(int,int) 1258 (gdb) b 'bubble( 1259 1260 In some cases, GDB can tell that completing a name requires using 1261 quotes. When this happens, GDB inserts the quote for you (while 1262 completing as much as it can) if you do not type the quote in the first 1263 place: 1264 1265 (gdb) b bub <TAB> 1266 GDB alters your input line to the following, and rings a bell: 1267 (gdb) b 'bubble( 1268 1269 In general, GDB can tell that a quote is needed (and inserts it) if you 1270 have not yet started typing the argument list when you ask for 1271 completion on an overloaded symbol. 1272 1273 For more information about overloaded functions, see *Note C++ 1274 Expressions: C Plus Plus Expressions. You can use the command `set 1275 overload-resolution off' to disable overload resolution; see *Note GDB 1276 Features for C++: Debugging C Plus Plus. 1277 1278 When completing in an expression which looks up a field in a 1279 structure, GDB also tries(1) to limit completions to the field names 1280 available in the type of the left-hand-side: 1281 1282 (gdb) p gdb_stdout.M-? 1283 magic to_delete to_fputs to_put to_rewind 1284 to_data to_flush to_isatty to_read to_write 1285 1286 This is because the `gdb_stdout' is a variable of the type `struct 1287 ui_file' that is defined in GDB sources as follows: 1288 1289 struct ui_file 1290 { 1291 int *magic; 1292 ui_file_flush_ftype *to_flush; 1293 ui_file_write_ftype *to_write; 1294 ui_file_fputs_ftype *to_fputs; 1295 ui_file_read_ftype *to_read; 1296 ui_file_delete_ftype *to_delete; 1297 ui_file_isatty_ftype *to_isatty; 1298 ui_file_rewind_ftype *to_rewind; 1299 ui_file_put_ftype *to_put; 1300 void *to_data; 1301 } 1302 1303 ---------- Footnotes ---------- 1304 1305 (1) The completer can be confused by certain kinds of invalid 1306 expressions. Also, it only examines the static type of the expression, 1307 not the dynamic type. 1308 1309 1310 File: gdb.info, Node: Help, Prev: Completion, Up: Commands 1311 1312 3.3 Getting Help 1313 ================ 1314 1315 You can always ask GDB itself for information on its commands, using 1316 the command `help'. 1317 1318 `help' 1319 `h' 1320 You can use `help' (abbreviated `h') with no arguments to display 1321 a short list of named classes of commands: 1322 1323 (gdb) help 1324 List of classes of commands: 1325 1326 aliases -- Aliases of other commands 1327 breakpoints -- Making program stop at certain points 1328 data -- Examining data 1329 files -- Specifying and examining files 1330 internals -- Maintenance commands 1331 obscure -- Obscure features 1332 running -- Running the program 1333 stack -- Examining the stack 1334 status -- Status inquiries 1335 support -- Support facilities 1336 tracepoints -- Tracing of program execution without 1337 stopping the program 1338 user-defined -- User-defined commands 1339 1340 Type "help" followed by a class name for a list of 1341 commands in that class. 1342 Type "help" followed by command name for full 1343 documentation. 1344 Command name abbreviations are allowed if unambiguous. 1345 (gdb) 1346 1347 `help CLASS' 1348 Using one of the general help classes as an argument, you can get a 1349 list of the individual commands in that class. For example, here 1350 is the help display for the class `status': 1351 1352 (gdb) help status 1353 Status inquiries. 1354 1355 List of commands: 1356 1357 info -- Generic command for showing things 1358 about the program being debugged 1359 show -- Generic command for showing things 1360 about the debugger 1361 1362 Type "help" followed by command name for full 1363 documentation. 1364 Command name abbreviations are allowed if unambiguous. 1365 (gdb) 1366 1367 `help COMMAND' 1368 With a command name as `help' argument, GDB displays a short 1369 paragraph on how to use that command. 1370 1371 `apropos ARGS' 1372 The `apropos' command searches through all of the GDB commands, 1373 and their documentation, for the regular expression specified in 1374 ARGS. It prints out all matches found. For example: 1375 1376 apropos reload 1377 1378 results in: 1379 1380 set symbol-reloading -- Set dynamic symbol table reloading 1381 multiple times in one run 1382 show symbol-reloading -- Show dynamic symbol table reloading 1383 multiple times in one run 1384 1385 `complete ARGS' 1386 The `complete ARGS' command lists all the possible completions for 1387 the beginning of a command. Use ARGS to specify the beginning of 1388 the command you want completed. For example: 1389 1390 complete i 1391 1392 results in: 1393 1394 if 1395 ignore 1396 info 1397 inspect 1398 1399 This is intended for use by GNU Emacs. 1400 1401 In addition to `help', you can use the GDB commands `info' and 1402 `show' to inquire about the state of your program, or the state of GDB 1403 itself. Each command supports many topics of inquiry; this manual 1404 introduces each of them in the appropriate context. The listings under 1405 `info' and under `show' in the Index point to all the sub-commands. 1406 *Note Index::. 1407 1408 `info' 1409 This command (abbreviated `i') is for describing the state of your 1410 program. For example, you can show the arguments passed to a 1411 function with `info args', list the registers currently in use 1412 with `info registers', or list the breakpoints you have set with 1413 `info breakpoints'. You can get a complete list of the `info' 1414 sub-commands with `help info'. 1415 1416 `set' 1417 You can assign the result of an expression to an environment 1418 variable with `set'. For example, you can set the GDB prompt to a 1419 $-sign with `set prompt $'. 1420 1421 `show' 1422 In contrast to `info', `show' is for describing the state of GDB 1423 itself. You can change most of the things you can `show', by 1424 using the related command `set'; for example, you can control what 1425 number system is used for displays with `set radix', or simply 1426 inquire which is currently in use with `show radix'. 1427 1428 To display all the settable parameters and their current values, 1429 you can use `show' with no arguments; you may also use `info set'. 1430 Both commands produce the same display. 1431 1432 Here are three miscellaneous `show' subcommands, all of which are 1433 exceptional in lacking corresponding `set' commands: 1434 1435 `show version' 1436 Show what version of GDB is running. You should include this 1437 information in GDB bug-reports. If multiple versions of GDB are 1438 in use at your site, you may need to determine which version of 1439 GDB you are running; as GDB evolves, new commands are introduced, 1440 and old ones may wither away. Also, many system vendors ship 1441 variant versions of GDB, and there are variant versions of GDB in 1442 GNU/Linux distributions as well. The version number is the same 1443 as the one announced when you start GDB. 1444 1445 `show copying' 1446 `info copying' 1447 Display information about permission for copying GDB. 1448 1449 `show warranty' 1450 `info warranty' 1451 Display the GNU "NO WARRANTY" statement, or a warranty, if your 1452 version of GDB comes with one. 1453 1454 1455 1456 File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top 1457 1458 4 Running Programs Under GDB 1459 **************************** 1460 1461 When you run a program under GDB, you must first generate debugging 1462 information when you compile it. 1463 1464 You may start GDB with its arguments, if any, in an environment of 1465 your choice. If you are doing native debugging, you may redirect your 1466 program's input and output, debug an already running process, or kill a 1467 child process. 1468 1469 * Menu: 1470 1471 * Compilation:: Compiling for debugging 1472 * Starting:: Starting your program 1473 * Arguments:: Your program's arguments 1474 * Environment:: Your program's environment 1475 1476 * Working Directory:: Your program's working directory 1477 * Input/Output:: Your program's input and output 1478 * Attach:: Debugging an already-running process 1479 * Kill Process:: Killing the child process 1480 1481 * Inferiors and Programs:: Debugging multiple inferiors and programs 1482 * Threads:: Debugging programs with multiple threads 1483 * Forks:: Debugging forks 1484 * Checkpoint/Restart:: Setting a _bookmark_ to return to later 1485 1486 1487 File: gdb.info, Node: Compilation, Next: Starting, Up: Running 1488 1489 4.1 Compiling for Debugging 1490 =========================== 1491 1492 In order to debug a program effectively, you need to generate debugging 1493 information when you compile it. This debugging information is stored 1494 in the object file; it describes the data type of each variable or 1495 function and the correspondence between source line numbers and 1496 addresses in the executable code. 1497 1498 To request debugging information, specify the `-g' option when you 1499 run the compiler. 1500 1501 Programs that are to be shipped to your customers are compiled with 1502 optimizations, using the `-O' compiler option. However, some compilers 1503 are unable to handle the `-g' and `-O' options together. Using those 1504 compilers, you cannot generate optimized executables containing 1505 debugging information. 1506 1507 GCC, the GNU C/C++ compiler, supports `-g' with or without `-O', 1508 making it possible to debug optimized code. We recommend that you 1509 _always_ use `-g' whenever you compile a program. You may think your 1510 program is correct, but there is no sense in pushing your luck. For 1511 more information, see *Note Optimized Code::. 1512 1513 Older versions of the GNU C compiler permitted a variant option 1514 `-gg' for debugging information. GDB no longer supports this format; 1515 if your GNU C compiler has this option, do not use it. 1516 1517 GDB knows about preprocessor macros and can show you their expansion 1518 (*note Macros::). Most compilers do not include information about 1519 preprocessor macros in the debugging information if you specify the 1520 `-g' flag alone, because this information is rather large. Version 3.1 1521 and later of GCC, the GNU C compiler, provides macro information if you 1522 specify the options `-gdwarf-2' and `-g3'; the former option requests 1523 debugging information in the Dwarf 2 format, and the latter requests 1524 "extra information". In the future, we hope to find more compact ways 1525 to represent macro information, so that it can be included with `-g' 1526 alone. 1527 1528 1529 File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running 1530 1531 4.2 Starting your Program 1532 ========================= 1533 1534 `run' 1535 `r' 1536 Use the `run' command to start your program under GDB. You must 1537 first specify the program name (except on VxWorks) with an 1538 argument to GDB (*note Getting In and Out of GDB: Invocation.), or 1539 by using the `file' or `exec-file' command (*note Commands to 1540 Specify Files: Files.). 1541 1542 1543 If you are running your program in an execution environment that 1544 supports processes, `run' creates an inferior process and makes that 1545 process run your program. In some environments without processes, 1546 `run' jumps to the start of your program. Other targets, like 1547 `remote', are always running. If you get an error message like this 1548 one: 1549 1550 The "remote" target does not support "run". 1551 Try "help target" or "continue". 1552 1553 then use `continue' to run your program. You may need `load' first 1554 (*note load::). 1555 1556 The execution of a program is affected by certain information it 1557 receives from its superior. GDB provides ways to specify this 1558 information, which you must do _before_ starting your program. (You 1559 can change it after starting your program, but such changes only affect 1560 your program the next time you start it.) This information may be 1561 divided into four categories: 1562 1563 The _arguments._ 1564 Specify the arguments to give your program as the arguments of the 1565 `run' command. If a shell is available on your target, the shell 1566 is used to pass the arguments, so that you may use normal 1567 conventions (such as wildcard expansion or variable substitution) 1568 in describing the arguments. In Unix systems, you can control 1569 which shell is used with the `SHELL' environment variable. *Note 1570 Your Program's Arguments: Arguments. 1571 1572 The _environment._ 1573 Your program normally inherits its environment from GDB, but you 1574 can use the GDB commands `set environment' and `unset environment' 1575 to change parts of the environment that affect your program. 1576 *Note Your Program's Environment: Environment. 1577 1578 The _working directory._ 1579 Your program inherits its working directory from GDB. You can set 1580 the GDB working directory with the `cd' command in GDB. *Note 1581 Your Program's Working Directory: Working Directory. 1582 1583 The _standard input and output._ 1584 Your program normally uses the same device for standard input and 1585 standard output as GDB is using. You can redirect input and output 1586 in the `run' command line, or you can use the `tty' command to set 1587 a different device for your program. *Note Your Program's Input 1588 and Output: Input/Output. 1589 1590 _Warning:_ While input and output redirection work, you cannot use 1591 pipes to pass the output of the program you are debugging to 1592 another program; if you attempt this, GDB is likely to wind up 1593 debugging the wrong program. 1594 1595 When you issue the `run' command, your program begins to execute 1596 immediately. *Note Stopping and Continuing: Stopping, for discussion 1597 of how to arrange for your program to stop. Once your program has 1598 stopped, you may call functions in your program, using the `print' or 1599 `call' commands. *Note Examining Data: Data. 1600 1601 If the modification time of your symbol file has changed since the 1602 last time GDB read its symbols, GDB discards its symbol table, and 1603 reads it again. When it does this, GDB tries to retain your current 1604 breakpoints. 1605 1606 `start' 1607 The name of the main procedure can vary from language to language. 1608 With C or C++, the main procedure name is always `main', but other 1609 languages such as Ada do not require a specific name for their 1610 main procedure. The debugger provides a convenient way to start 1611 the execution of the program and to stop at the beginning of the 1612 main procedure, depending on the language used. 1613 1614 The `start' command does the equivalent of setting a temporary 1615 breakpoint at the beginning of the main procedure and then invoking 1616 the `run' command. 1617 1618 Some programs contain an "elaboration" phase where some startup 1619 code is executed before the main procedure is called. This 1620 depends on the languages used to write your program. In C++, for 1621 instance, constructors for static and global objects are executed 1622 before `main' is called. It is therefore possible that the 1623 debugger stops before reaching the main procedure. However, the 1624 temporary breakpoint will remain to halt execution. 1625 1626 Specify the arguments to give to your program as arguments to the 1627 `start' command. These arguments will be given verbatim to the 1628 underlying `run' command. Note that the same arguments will be 1629 reused if no argument is provided during subsequent calls to 1630 `start' or `run'. 1631 1632 It is sometimes necessary to debug the program during elaboration. 1633 In these cases, using the `start' command would stop the 1634 execution of your program too late, as the program would have 1635 already completed the elaboration phase. Under these 1636 circumstances, insert breakpoints in your elaboration code before 1637 running your program. 1638 1639 `set exec-wrapper WRAPPER' 1640 `show exec-wrapper' 1641 `unset exec-wrapper' 1642 When `exec-wrapper' is set, the specified wrapper is used to 1643 launch programs for debugging. GDB starts your program with a 1644 shell command of the form `exec WRAPPER PROGRAM'. Quoting is 1645 added to PROGRAM and its arguments, but not to WRAPPER, so you 1646 should add quotes if appropriate for your shell. The wrapper runs 1647 until it executes your program, and then GDB takes control. 1648 1649 You can use any program that eventually calls `execve' with its 1650 arguments as a wrapper. Several standard Unix utilities do this, 1651 e.g. `env' and `nohup'. Any Unix shell script ending with `exec 1652 "$@"' will also work. 1653 1654 For example, you can use `env' to pass an environment variable to 1655 the debugged program, without setting the variable in your shell's 1656 environment: 1657 1658 (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so' 1659 (gdb) run 1660 1661 This command is available when debugging locally on most targets, 1662 excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino. 1663 1664 `set disable-randomization' 1665 `set disable-randomization on' 1666 This option (enabled by default in GDB) will turn off the native 1667 randomization of the virtual address space of the started program. 1668 This option is useful for multiple debugging sessions to make the 1669 execution better reproducible and memory addresses reusable across 1670 debugging sessions. 1671 1672 This feature is implemented only on GNU/Linux. You can get the 1673 same behavior using 1674 1675 (gdb) set exec-wrapper setarch `uname -m` -R 1676 1677 `set disable-randomization off' 1678 Leave the behavior of the started executable unchanged. Some bugs 1679 rear their ugly heads only when the program is loaded at certain 1680 addresses. If your bug disappears when you run the program under 1681 GDB, that might be because GDB by default disables the address 1682 randomization on platforms, such as GNU/Linux, which do that for 1683 stand-alone programs. Use `set disable-randomization off' to try 1684 to reproduce such elusive bugs. 1685 1686 The virtual address space randomization is implemented only on 1687 GNU/Linux. It protects the programs against some kinds of 1688 security attacks. In these cases the attacker needs to know the 1689 exact location of a concrete executable code. Randomizing its 1690 location makes it impossible to inject jumps misusing a code at 1691 its expected addresses. 1692 1693 Prelinking shared libraries provides a startup performance 1694 advantage but it makes addresses in these libraries predictable 1695 for privileged processes by having just unprivileged access at the 1696 target system. Reading the shared library binary gives enough 1697 information for assembling the malicious code misusing it. Still 1698 even a prelinked shared library can get loaded at a new random 1699 address just requiring the regular relocation process during the 1700 startup. Shared libraries not already prelinked are always loaded 1701 at a randomly chosen address. 1702 1703 Position independent executables (PIE) contain position 1704 independent code similar to the shared libraries and therefore 1705 such executables get loaded at a randomly chosen address upon 1706 startup. PIE executables always load even already prelinked 1707 shared libraries at a random address. You can build such 1708 executable using `gcc -fPIE -pie'. 1709 1710 Heap (malloc storage), stack and custom mmap areas are always 1711 placed randomly (as long as the randomization is enabled). 1712 1713 `show disable-randomization' 1714 Show the current setting of the explicit disable of the native 1715 randomization of the virtual address space of the started program. 1716 1717 1718 1719 File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running 1720 1721 4.3 Your Program's Arguments 1722 ============================ 1723 1724 The arguments to your program can be specified by the arguments of the 1725 `run' command. They are passed to a shell, which expands wildcard 1726 characters and performs redirection of I/O, and thence to your program. 1727 Your `SHELL' environment variable (if it exists) specifies what shell 1728 GDB uses. If you do not define `SHELL', GDB uses the default shell 1729 (`/bin/sh' on Unix). 1730 1731 On non-Unix systems, the program is usually invoked directly by GDB, 1732 which emulates I/O redirection via the appropriate system calls, and 1733 the wildcard characters are expanded by the startup code of the 1734 program, not by the shell. 1735 1736 `run' with no arguments uses the same arguments used by the previous 1737 `run', or those set by the `set args' command. 1738 1739 `set args' 1740 Specify the arguments to be used the next time your program is 1741 run. If `set args' has no arguments, `run' executes your program 1742 with no arguments. Once you have run your program with arguments, 1743 using `set args' before the next `run' is the only way to run it 1744 again without arguments. 1745 1746 `show args' 1747 Show the arguments to give your program when it is started. 1748 1749 1750 File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running 1751 1752 4.4 Your Program's Environment 1753 ============================== 1754 1755 The "environment" consists of a set of environment variables and their 1756 values. Environment variables conventionally record such things as 1757 your user name, your home directory, your terminal type, and your search 1758 path for programs to run. Usually you set up environment variables with 1759 the shell and they are inherited by all the other programs you run. 1760 When debugging, it can be useful to try running your program with a 1761 modified environment without having to start GDB over again. 1762 1763 `path DIRECTORY' 1764 Add DIRECTORY to the front of the `PATH' environment variable (the 1765 search path for executables) that will be passed to your program. 1766 The value of `PATH' used by GDB does not change. You may specify 1767 several directory names, separated by whitespace or by a 1768 system-dependent separator character (`:' on Unix, `;' on MS-DOS 1769 and MS-Windows). If DIRECTORY is already in the path, it is moved 1770 to the front, so it is searched sooner. 1771 1772 You can use the string `$cwd' to refer to whatever is the current 1773 working directory at the time GDB searches the path. If you use 1774 `.' instead, it refers to the directory where you executed the 1775 `path' command. GDB replaces `.' in the DIRECTORY argument (with 1776 the current path) before adding DIRECTORY to the search path. 1777 1778 `show paths' 1779 Display the list of search paths for executables (the `PATH' 1780 environment variable). 1781 1782 `show environment [VARNAME]' 1783 Print the value of environment variable VARNAME to be given to 1784 your program when it starts. If you do not supply VARNAME, print 1785 the names and values of all environment variables to be given to 1786 your program. You can abbreviate `environment' as `env'. 1787 1788 `set environment VARNAME [=VALUE]' 1789 Set environment variable VARNAME to VALUE. The value changes for 1790 your program only, not for GDB itself. VALUE may be any string; 1791 the values of environment variables are just strings, and any 1792 interpretation is supplied by your program itself. The VALUE 1793 parameter is optional; if it is eliminated, the variable is set to 1794 a null value. 1795 1796 For example, this command: 1797 1798 set env USER = foo 1799 1800 tells the debugged program, when subsequently run, that its user 1801 is named `foo'. (The spaces around `=' are used for clarity here; 1802 they are not actually required.) 1803 1804 `unset environment VARNAME' 1805 Remove variable VARNAME from the environment to be passed to your 1806 program. This is different from `set env VARNAME ='; `unset 1807 environment' removes the variable from the environment, rather 1808 than assigning it an empty value. 1809 1810 _Warning:_ On Unix systems, GDB runs your program using the shell 1811 indicated by your `SHELL' environment variable if it exists (or 1812 `/bin/sh' if not). If your `SHELL' variable names a shell that runs an 1813 initialization file--such as `.cshrc' for C-shell, or `.bashrc' for 1814 BASH--any variables you set in that file affect your program. You may 1815 wish to move setting of environment variables to files that are only 1816 run when you sign on, such as `.login' or `.profile'. 1817 1818 1819 File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running 1820 1821 4.5 Your Program's Working Directory 1822 ==================================== 1823 1824 Each time you start your program with `run', it inherits its working 1825 directory from the current working directory of GDB. The GDB working 1826 directory is initially whatever it inherited from its parent process 1827 (typically the shell), but you can specify a new working directory in 1828 GDB with the `cd' command. 1829 1830 The GDB working directory also serves as a default for the commands 1831 that specify files for GDB to operate on. *Note Commands to Specify 1832 Files: Files. 1833 1834 `cd DIRECTORY' 1835 Set the GDB working directory to DIRECTORY. 1836 1837 `pwd' 1838 Print the GDB working directory. 1839 1840 It is generally impossible to find the current working directory of 1841 the process being debugged (since a program can change its directory 1842 during its run). If you work on a system where GDB is configured with 1843 the `/proc' support, you can use the `info proc' command (*note SVR4 1844 Process Information::) to find out the current working directory of the 1845 debuggee. 1846 1847 1848 File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running 1849 1850 4.6 Your Program's Input and Output 1851 =================================== 1852 1853 By default, the program you run under GDB does input and output to the 1854 same terminal that GDB uses. GDB switches the terminal to its own 1855 terminal modes to interact with you, but it records the terminal modes 1856 your program was using and switches back to them when you continue 1857 running your program. 1858 1859 `info terminal' 1860 Displays information recorded by GDB about the terminal modes your 1861 program is using. 1862 1863 You can redirect your program's input and/or output using shell 1864 redirection with the `run' command. For example, 1865 1866 run > outfile 1867 1868 starts your program, diverting its output to the file `outfile'. 1869 1870 Another way to specify where your program should do input and output 1871 is with the `tty' command. This command accepts a file name as 1872 argument, and causes this file to be the default for future `run' 1873 commands. It also resets the controlling terminal for the child 1874 process, for future `run' commands. For example, 1875 1876 tty /dev/ttyb 1877 1878 directs that processes started with subsequent `run' commands default 1879 to do input and output on the terminal `/dev/ttyb' and have that as 1880 their controlling terminal. 1881 1882 An explicit redirection in `run' overrides the `tty' command's 1883 effect on the input/output device, but not its effect on the controlling 1884 terminal. 1885 1886 When you use the `tty' command or redirect input in the `run' 1887 command, only the input _for your program_ is affected. The input for 1888 GDB still comes from your terminal. `tty' is an alias for `set 1889 inferior-tty'. 1890 1891 You can use the `show inferior-tty' command to tell GDB to display 1892 the name of the terminal that will be used for future runs of your 1893 program. 1894 1895 `set inferior-tty /dev/ttyb' 1896 Set the tty for the program being debugged to /dev/ttyb. 1897 1898 `show inferior-tty' 1899 Show the current tty for the program being debugged. 1900 1901 1902 File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running 1903 1904 4.7 Debugging an Already-running Process 1905 ======================================== 1906 1907 `attach PROCESS-ID' 1908 This command attaches to a running process--one that was started 1909 outside GDB. (`info files' shows your active targets.) The 1910 command takes as argument a process ID. The usual way to find out 1911 the PROCESS-ID of a Unix process is with the `ps' utility, or with 1912 the `jobs -l' shell command. 1913 1914 `attach' does not repeat if you press <RET> a second time after 1915 executing the command. 1916 1917 To use `attach', your program must be running in an environment 1918 which supports processes; for example, `attach' does not work for 1919 programs on bare-board targets that lack an operating system. You must 1920 also have permission to send the process a signal. 1921 1922 When you use `attach', the debugger finds the program running in the 1923 process first by looking in the current working directory, then (if the 1924 program is not found) by using the source file search path (*note 1925 Specifying Source Directories: Source Path.). You can also use the 1926 `file' command to load the program. *Note Commands to Specify Files: 1927 Files. 1928 1929 The first thing GDB does after arranging to debug the specified 1930 process is to stop it. You can examine and modify an attached process 1931 with all the GDB commands that are ordinarily available when you start 1932 processes with `run'. You can insert breakpoints; you can step and 1933 continue; you can modify storage. If you would rather the process 1934 continue running, you may use the `continue' command after attaching 1935 GDB to the process. 1936 1937 `detach' 1938 When you have finished debugging the attached process, you can use 1939 the `detach' command to release it from GDB control. Detaching 1940 the process continues its execution. After the `detach' command, 1941 that process and GDB become completely independent once more, and 1942 you are ready to `attach' another process or start one with `run'. 1943 `detach' does not repeat if you press <RET> again after executing 1944 the command. 1945 1946 If you exit GDB while you have an attached process, you detach that 1947 process. If you use the `run' command, you kill that process. By 1948 default, GDB asks for confirmation if you try to do either of these 1949 things; you can control whether or not you need to confirm by using the 1950 `set confirm' command (*note Optional Warnings and Messages: 1951 Messages/Warnings.). 1952 1953 1954 File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running 1955 1956 4.8 Killing the Child Process 1957 ============================= 1958 1959 `kill' 1960 Kill the child process in which your program is running under GDB. 1961 1962 This command is useful if you wish to debug a core dump instead of a 1963 running process. GDB ignores any core dump file while your program is 1964 running. 1965 1966 On some operating systems, a program cannot be executed outside GDB 1967 while you have breakpoints set on it inside GDB. You can use the 1968 `kill' command in this situation to permit running your program outside 1969 the debugger. 1970 1971 The `kill' command is also useful if you wish to recompile and 1972 relink your program, since on many systems it is impossible to modify an 1973 executable file while it is running in a process. In this case, when 1974 you next type `run', GDB notices that the file has changed, and reads 1975 the symbol table again (while trying to preserve your current 1976 breakpoint settings). 1977 1978 1979 File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running 1980 1981 4.9 Debugging Multiple Inferiors and Programs 1982 ============================================= 1983 1984 GDB lets you run and debug multiple programs in a single session. In 1985 addition, GDB on some systems may let you run several programs 1986 simultaneously (otherwise you have to exit from one before starting 1987 another). In the most general case, you can have multiple threads of 1988 execution in each of multiple processes, launched from multiple 1989 executables. 1990 1991 GDB represents the state of each program execution with an object 1992 called an "inferior". An inferior typically corresponds to a process, 1993 but is more general and applies also to targets that do not have 1994 processes. Inferiors may be created before a process runs, and may be 1995 retained after a process exits. Inferiors have unique identifiers that 1996 are different from process ids. Usually each inferior will also have 1997 its own distinct address space, although some embedded targets may have 1998 several inferiors running in different parts of a single address space. 1999 Each inferior may in turn have multiple threads running in it. 2000 2001 To find out what inferiors exist at any moment, use `info inferiors': 2002 2003 `info inferiors' 2004 Print a list of all inferiors currently being managed by GDB. 2005 2006 GDB displays for each inferior (in this order): 2007 2008 1. the inferior number assigned by GDB 2009 2010 2. the target system's inferior identifier 2011 2012 3. the name of the executable the inferior is running. 2013 2014 2015 An asterisk `*' preceding the GDB inferior number indicates the 2016 current inferior. 2017 2018 For example, 2019 2020 (gdb) info inferiors 2021 Num Description Executable 2022 2 process 2307 hello 2023 * 1 process 3401 goodbye 2024 2025 To switch focus between inferiors, use the `inferior' command: 2026 2027 `inferior INFNO' 2028 Make inferior number INFNO the current inferior. The argument 2029 INFNO is the inferior number assigned by GDB, as shown in the 2030 first field of the `info inferiors' display. 2031 2032 You can get multiple executables into a debugging session via the 2033 `add-inferior' and `clone-inferior' commands. On some systems GDB can 2034 add inferiors to the debug session automatically by following calls to 2035 `fork' and `exec'. To remove inferiors from the debugging session use 2036 the `remove-inferior' command. 2037 2038 `add-inferior [ -copies N ] [ -exec EXECUTABLE ]' 2039 Adds N inferiors to be run using EXECUTABLE as the executable. N 2040 defaults to 1. If no executable is specified, the inferiors 2041 begins empty, with no program. You can still assign or change the 2042 program assigned to the inferior at any time by using the `file' 2043 command with the executable name as its argument. 2044 2045 `clone-inferior [ -copies N ] [ INFNO ]' 2046 Adds N inferiors ready to execute the same program as inferior 2047 INFNO. N defaults to 1. INFNO defaults to the number of the 2048 current inferior. This is a convenient command when you want to 2049 run another instance of the inferior you are debugging. 2050 2051 (gdb) info inferiors 2052 Num Description Executable 2053 * 1 process 29964 helloworld 2054 (gdb) clone-inferior 2055 Added inferior 2. 2056 1 inferiors added. 2057 (gdb) info inferiors 2058 Num Description Executable 2059 2 <null> helloworld 2060 * 1 process 29964 helloworld 2061 2062 You can now simply switch focus to inferior 2 and run it. 2063 2064 `remove-inferior INFNO' 2065 Removes the inferior INFNO. It is not possible to remove an 2066 inferior that is running with this command. For those, use the 2067 `kill' or `detach' command first. 2068 2069 2070 To quit debugging one of the running inferiors that is not the 2071 current inferior, you can either detach from it by using the 2072 `detach inferior' command (allowing it to run independently), or kill it 2073 using the `kill inferior' command: 2074 2075 `detach inferior INFNO' 2076 Detach from the inferior identified by GDB inferior number INFNO, 2077 and remove it from the inferior list. 2078 2079 `kill inferior INFNO' 2080 Kill the inferior identified by GDB inferior number INFNO, and 2081 remove it from the inferior list. 2082 2083 After the successful completion of a command such as `detach', 2084 `detach inferior', `kill' or `kill inferior', or after a normal process 2085 exit, the inferior is still valid and listed with `info inferiors', 2086 ready to be restarted. 2087 2088 To be notified when inferiors are started or exit under GDB's 2089 control use `set print inferior-events': 2090 2091 `set print inferior-events' 2092 `set print inferior-events on' 2093 `set print inferior-events off' 2094 The `set print inferior-events' command allows you to enable or 2095 disable printing of messages when GDB notices that new inferiors 2096 have started or that inferiors have exited or have been detached. 2097 By default, these messages will not be printed. 2098 2099 `show print inferior-events' 2100 Show whether messages will be printed when GDB detects that 2101 inferiors have started, exited or have been detached. 2102 2103 Many commands will work the same with multiple programs as with a 2104 single program: e.g., `print myglobal' will simply display the value of 2105 `myglobal' in the current inferior. 2106 2107 Occasionaly, when debugging GDB itself, it may be useful to get more 2108 info about the relationship of inferiors, programs, address spaces in a 2109 debug session. You can do that with the `maint info program-spaces' 2110 command. 2111 2112 `maint info program-spaces' 2113 Print a list of all program spaces currently being managed by GDB. 2114 2115 GDB displays for each program space (in this order): 2116 2117 1. the program space number assigned by GDB 2118 2119 2. the name of the executable loaded into the program space, 2120 with e.g., the `file' command. 2121 2122 2123 An asterisk `*' preceding the GDB program space number indicates 2124 the current program space. 2125 2126 In addition, below each program space line, GDB prints extra 2127 information that isn't suitable to display in tabular form. For 2128 example, the list of inferiors bound to the program space. 2129 2130 (gdb) maint info program-spaces 2131 Id Executable 2132 2 goodbye 2133 Bound inferiors: ID 1 (process 21561) 2134 * 1 hello 2135 2136 Here we can see that no inferior is running the program `hello', 2137 while `process 21561' is running the program `goodbye'. On some 2138 targets, it is possible that multiple inferiors are bound to the 2139 same program space. The most common example is that of debugging 2140 both the parent and child processes of a `vfork' call. For 2141 example, 2142 2143 (gdb) maint info program-spaces 2144 Id Executable 2145 * 1 vfork-test 2146 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) 2147 2148 Here, both inferior 2 and inferior 1 are running in the same 2149 program space as a result of inferior 1 having executed a `vfork' 2150 call. 2151 2152 2153 File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running 2154 2155 4.10 Debugging Programs with Multiple Threads 2156 ============================================= 2157 2158 In some operating systems, such as HP-UX and Solaris, a single program 2159 may have more than one "thread" of execution. The precise semantics of 2160 threads differ from one operating system to another, but in general the 2161 threads of a single program are akin to multiple processes--except that 2162 they share one address space (that is, they can all examine and modify 2163 the same variables). On the other hand, each thread has its own 2164 registers and execution stack, and perhaps private memory. 2165 2166 GDB provides these facilities for debugging multi-thread programs: 2167 2168 * automatic notification of new threads 2169 2170 * `thread THREADNO', a command to switch among threads 2171 2172 * `info threads', a command to inquire about existing threads 2173 2174 * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command 2175 to a list of threads 2176 2177 * thread-specific breakpoints 2178 2179 * `set print thread-events', which controls printing of messages on 2180 thread start and exit. 2181 2182 * `set libthread-db-search-path PATH', which lets the user specify 2183 which `libthread_db' to use if the default choice isn't compatible 2184 with the program. 2185 2186 _Warning:_ These facilities are not yet available on every GDB 2187 configuration where the operating system supports threads. If 2188 your GDB does not support threads, these commands have no effect. 2189 For example, a system without thread support shows no output from 2190 `info threads', and always rejects the `thread' command, like this: 2191 2192 (gdb) info threads 2193 (gdb) thread 1 2194 Thread ID 1 not known. Use the "info threads" command to 2195 see the IDs of currently known threads. 2196 2197 The GDB thread debugging facility allows you to observe all threads 2198 while your program runs--but whenever GDB takes control, one thread in 2199 particular is always the focus of debugging. This thread is called the 2200 "current thread". Debugging commands show program information from the 2201 perspective of the current thread. 2202 2203 Whenever GDB detects a new thread in your program, it displays the 2204 target system's identification for the thread with a message in the 2205 form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies 2206 depending on the particular system. For example, on GNU/Linux, you 2207 might see 2208 2209 [New Thread 46912507313328 (LWP 25582)] 2210 2211 when GDB notices a new thread. In contrast, on an SGI system, the 2212 SYSTAG is simply something like `process 368', with no further 2213 qualifier. 2214 2215 For debugging purposes, GDB associates its own thread number--always 2216 a single integer--with each thread in your program. 2217 2218 `info threads' 2219 Display a summary of all threads currently in your program. GDB 2220 displays for each thread (in this order): 2221 2222 1. the thread number assigned by GDB 2223 2224 2. the target system's thread identifier (SYSTAG) 2225 2226 3. the current stack frame summary for that thread 2227 2228 An asterisk `*' to the left of the GDB thread number indicates the 2229 current thread. 2230 2231 For example, 2232 2233 (gdb) info threads 2234 3 process 35 thread 27 0x34e5 in sigpause () 2235 2 process 35 thread 23 0x34e5 in sigpause () 2236 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 2237 at threadtest.c:68 2238 2239 On HP-UX systems: 2240 2241 For debugging purposes, GDB associates its own thread number--a 2242 small integer assigned in thread-creation order--with each thread in 2243 your program. 2244 2245 Whenever GDB detects a new thread in your program, it displays both 2246 GDB's thread number and the target system's identification for the 2247 thread with a message in the form `[New SYSTAG]'. SYSTAG is a thread 2248 identifier whose form varies depending on the particular system. For 2249 example, on HP-UX, you see 2250 2251 [New thread 2 (system thread 26594)] 2252 2253 when GDB notices a new thread. 2254 2255 `info threads' 2256 Display a summary of all threads currently in your program. GDB 2257 displays for each thread (in this order): 2258 2259 1. the thread number assigned by GDB 2260 2261 2. the target system's thread identifier (SYSTAG) 2262 2263 3. the current stack frame summary for that thread 2264 2265 An asterisk `*' to the left of the GDB thread number indicates the 2266 current thread. 2267 2268 For example, 2269 2270 (gdb) info threads 2271 * 3 system thread 26607 worker (wptr=0x7b09c318 "@") \ 2272 2273 at quicksort.c:137 2274 2 system thread 26606 0x7b0030d8 in __ksleep () \ 2275 2276 from /usr/lib/libc.2 2277 1 system thread 27905 0x7b003498 in _brk () \ 2278 2279 from /usr/lib/libc.2 2280 2281 On Solaris, you can display more information about user threads with 2282 a Solaris-specific command: 2283 2284 `maint info sol-threads' 2285 Display info on Solaris user threads. 2286 2287 `thread THREADNO' 2288 Make thread number THREADNO the current thread. The command 2289 argument THREADNO is the internal GDB thread number, as shown in 2290 the first field of the `info threads' display. GDB responds by 2291 displaying the system identifier of the thread you selected, and 2292 its current stack frame summary: 2293 2294 (gdb) thread 2 2295 [Switching to process 35 thread 23] 2296 0x34e5 in sigpause () 2297 2298 As with the `[New ...]' message, the form of the text after 2299 `Switching to' depends on your system's conventions for identifying 2300 threads. 2301 2302 `thread apply [THREADNO] [ALL] COMMAND' 2303 The `thread apply' command allows you to apply the named COMMAND 2304 to one or more threads. Specify the numbers of the threads that 2305 you want affected with the command argument THREADNO. It can be a 2306 single thread number, one of the numbers shown in the first field 2307 of the `info threads' display; or it could be a range of thread 2308 numbers, as in `2-4'. To apply a command to all threads, type 2309 `thread apply all COMMAND'. 2310 2311 `set print thread-events' 2312 `set print thread-events on' 2313 `set print thread-events off' 2314 The `set print thread-events' command allows you to enable or 2315 disable printing of messages when GDB notices that new threads have 2316 started or that threads have exited. By default, these messages 2317 will be printed if detection of these events is supported by the 2318 target. Note that these messages cannot be disabled on all 2319 targets. 2320 2321 `show print thread-events' 2322 Show whether messages will be printed when GDB detects that threads 2323 have started and exited. 2324 2325 *Note Stopping and Starting Multi-thread Programs: Thread Stops, for 2326 more information about how GDB behaves when you stop and start programs 2327 with multiple threads. 2328 2329 *Note Setting Watchpoints: Set Watchpoints, for information about 2330 watchpoints in programs with multiple threads. 2331 2332 `set libthread-db-search-path [PATH]' 2333 If this variable is set, PATH is a colon-separated list of 2334 directories GDB will use to search for `libthread_db'. If you 2335 omit PATH, `libthread-db-search-path' will be reset to an empty 2336 list. 2337 2338 On GNU/Linux and Solaris systems, GDB uses a "helper" 2339 `libthread_db' library to obtain information about threads in the 2340 inferior process. GDB will use `libthread-db-search-path' to find 2341 `libthread_db'. If that fails, GDB will continue with default 2342 system shared library directories, and finally the directory from 2343 which `libpthread' was loaded in the inferior process. 2344 2345 For any `libthread_db' library GDB finds in above directories, GDB 2346 attempts to initialize it with the current inferior process. If 2347 this initialization fails (which could happen because of a version 2348 mismatch between `libthread_db' and `libpthread'), GDB will unload 2349 `libthread_db', and continue with the next directory. If none of 2350 `libthread_db' libraries initialize successfully, GDB will issue a 2351 warning and thread debugging will be disabled. 2352 2353 Setting `libthread-db-search-path' is currently implemented only 2354 on some platforms. 2355 2356 `show libthread-db-search-path' 2357 Display current libthread_db search path. 2358 2359 2360 File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running 2361 2362 4.11 Debugging Forks 2363 ==================== 2364 2365 On most systems, GDB has no special support for debugging programs 2366 which create additional processes using the `fork' function. When a 2367 program forks, GDB will continue to debug the parent process and the 2368 child process will run unimpeded. If you have set a breakpoint in any 2369 code which the child then executes, the child will get a `SIGTRAP' 2370 signal which (unless it catches the signal) will cause it to terminate. 2371 2372 However, if you want to debug the child process there is a workaround 2373 which isn't too painful. Put a call to `sleep' in the code which the 2374 child process executes after the fork. It may be useful to sleep only 2375 if a certain environment variable is set, or a certain file exists, so 2376 that the delay need not occur when you don't want to run GDB on the 2377 child. While the child is sleeping, use the `ps' program to get its 2378 process ID. Then tell GDB (a new invocation of GDB if you are also 2379 debugging the parent process) to attach to the child process (*note 2380 Attach::). From that point on you can debug the child process just 2381 like any other process which you attached to. 2382 2383 On some systems, GDB provides support for debugging programs that 2384 create additional processes using the `fork' or `vfork' functions. 2385 Currently, the only platforms with this feature are HP-UX (11.x and 2386 later only?) and GNU/Linux (kernel version 2.5.60 and later). 2387 2388 By default, when a program forks, GDB will continue to debug the 2389 parent process and the child process will run unimpeded. 2390 2391 If you want to follow the child process instead of the parent 2392 process, use the command `set follow-fork-mode'. 2393 2394 `set follow-fork-mode MODE' 2395 Set the debugger response to a program call of `fork' or `vfork'. 2396 A call to `fork' or `vfork' creates a new process. The MODE 2397 argument can be: 2398 2399 `parent' 2400 The original process is debugged after a fork. The child 2401 process runs unimpeded. This is the default. 2402 2403 `child' 2404 The new process is debugged after a fork. The parent process 2405 runs unimpeded. 2406 2407 2408 `show follow-fork-mode' 2409 Display the current debugger response to a `fork' or `vfork' call. 2410 2411 On Linux, if you want to debug both the parent and child processes, 2412 use the command `set detach-on-fork'. 2413 2414 `set detach-on-fork MODE' 2415 Tells gdb whether to detach one of the processes after a fork, or 2416 retain debugger control over them both. 2417 2418 `on' 2419 The child process (or parent process, depending on the value 2420 of `follow-fork-mode') will be detached and allowed to run 2421 independently. This is the default. 2422 2423 `off' 2424 Both processes will be held under the control of GDB. One 2425 process (child or parent, depending on the value of 2426 `follow-fork-mode') is debugged as usual, while the other is 2427 held suspended. 2428 2429 2430 `show detach-on-fork' 2431 Show whether detach-on-fork mode is on/off. 2432 2433 If you choose to set `detach-on-fork' mode off, then GDB will retain 2434 control of all forked processes (including nested forks). You can list 2435 the forked processes under the control of GDB by using the 2436 `info inferiors' command, and switch from one fork to another by using 2437 the `inferior' command (*note Debugging Multiple Inferiors and 2438 Programs: Inferiors and Programs.). 2439 2440 To quit debugging one of the forked processes, you can either detach 2441 from it by using the `detach inferior' command (allowing it to run 2442 independently), or kill it using the `kill inferior' command. *Note 2443 Debugging Multiple Inferiors and Programs: Inferiors and Programs. 2444 2445 If you ask to debug a child process and a `vfork' is followed by an 2446 `exec', GDB executes the new target up to the first breakpoint in the 2447 new target. If you have a breakpoint set on `main' in your original 2448 program, the breakpoint will also be set on the child process's `main'. 2449 2450 On some systems, when a child process is spawned by `vfork', you 2451 cannot debug the child or parent until an `exec' call completes. 2452 2453 If you issue a `run' command to GDB after an `exec' call executes, 2454 the new target restarts. To restart the parent process, use the `file' 2455 command with the parent executable name as its argument. By default, 2456 after an `exec' call executes, GDB discards the symbols of the previous 2457 executable image. You can change this behaviour with the 2458 `set follow-exec-mode' command. 2459 2460 `set follow-exec-mode MODE' 2461 Set debugger response to a program call of `exec'. An `exec' call 2462 replaces the program image of a process. 2463 2464 `follow-exec-mode' can be: 2465 2466 `new' 2467 GDB creates a new inferior and rebinds the process to this 2468 new inferior. The program the process was running before the 2469 `exec' call can be restarted afterwards by restarting the 2470 original inferior. 2471 2472 For example: 2473 2474 (gdb) info inferiors 2475 (gdb) info inferior 2476 Id Description Executable 2477 * 1 <null> prog1 2478 (gdb) run 2479 process 12020 is executing new program: prog2 2480 Program exited normally. 2481 (gdb) info inferiors 2482 Id Description Executable 2483 * 2 <null> prog2 2484 1 <null> prog1 2485 2486 `same' 2487 GDB keeps the process bound to the same inferior. The new 2488 executable image replaces the previous executable loaded in 2489 the inferior. Restarting the inferior after the `exec' call, 2490 with e.g., the `run' command, restarts the executable the 2491 process was running after the `exec' call. This is the 2492 default mode. 2493 2494 For example: 2495 2496 (gdb) info inferiors 2497 Id Description Executable 2498 * 1 <null> prog1 2499 (gdb) run 2500 process 12020 is executing new program: prog2 2501 Program exited normally. 2502 (gdb) info inferiors 2503 Id Description Executable 2504 * 1 <null> prog2 2505 2506 2507 You can use the `catch' command to make GDB stop whenever a `fork', 2508 `vfork', or `exec' call is made. *Note Setting Catchpoints: Set 2509 Catchpoints. 2510 2511 2512 File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running 2513 2514 4.12 Setting a _Bookmark_ to Return to Later 2515 ============================================ 2516 2517 On certain operating systems(1), GDB is able to save a "snapshot" of a 2518 program's state, called a "checkpoint", and come back to it later. 2519 2520 Returning to a checkpoint effectively undoes everything that has 2521 happened in the program since the `checkpoint' was saved. This 2522 includes changes in memory, registers, and even (within some limits) 2523 system state. Effectively, it is like going back in time to the moment 2524 when the checkpoint was saved. 2525 2526 Thus, if you're stepping thru a program and you think you're getting 2527 close to the point where things go wrong, you can save a checkpoint. 2528 Then, if you accidentally go too far and miss the critical statement, 2529 instead of having to restart your program from the beginning, you can 2530 just go back to the checkpoint and start again from there. 2531 2532 This can be especially useful if it takes a lot of time or steps to 2533 reach the point where you think the bug occurs. 2534 2535 To use the `checkpoint'/`restart' method of debugging: 2536 2537 `checkpoint' 2538 Save a snapshot of the debugged program's current execution state. 2539 The `checkpoint' command takes no arguments, but each checkpoint 2540 is assigned a small integer id, similar to a breakpoint id. 2541 2542 `info checkpoints' 2543 List the checkpoints that have been saved in the current debugging 2544 session. For each checkpoint, the following information will be 2545 listed: 2546 2547 `Checkpoint ID' 2548 2549 `Process ID' 2550 2551 `Code Address' 2552 2553 `Source line, or label' 2554 2555 `restart CHECKPOINT-ID' 2556 Restore the program state that was saved as checkpoint number 2557 CHECKPOINT-ID. All program variables, registers, stack frames 2558 etc. will be returned to the values that they had when the 2559 checkpoint was saved. In essence, gdb will "wind back the clock" 2560 to the point in time when the checkpoint was saved. 2561 2562 Note that breakpoints, GDB variables, command history etc. are 2563 not affected by restoring a checkpoint. In general, a checkpoint 2564 only restores things that reside in the program being debugged, 2565 not in the debugger. 2566 2567 `delete checkpoint CHECKPOINT-ID' 2568 Delete the previously-saved checkpoint identified by CHECKPOINT-ID. 2569 2570 2571 Returning to a previously saved checkpoint will restore the user 2572 state of the program being debugged, plus a significant subset of the 2573 system (OS) state, including file pointers. It won't "un-write" data 2574 from a file, but it will rewind the file pointer to the previous 2575 location, so that the previously written data can be overwritten. For 2576 files opened in read mode, the pointer will also be restored so that the 2577 previously read data can be read again. 2578 2579 Of course, characters that have been sent to a printer (or other 2580 external device) cannot be "snatched back", and characters received 2581 from eg. a serial device can be removed from internal program buffers, 2582 but they cannot be "pushed back" into the serial pipeline, ready to be 2583 received again. Similarly, the actual contents of files that have been 2584 changed cannot be restored (at this time). 2585 2586 However, within those constraints, you actually can "rewind" your 2587 program to a previously saved point in time, and begin debugging it 2588 again -- and you can change the course of events so as to debug a 2589 different execution path this time. 2590 2591 Finally, there is one bit of internal program state that will be 2592 different when you return to a checkpoint -- the program's process id. 2593 Each checkpoint will have a unique process id (or PID), and each will 2594 be different from the program's original PID. If your program has 2595 saved a local copy of its process id, this could potentially pose a 2596 problem. 2597 2598 4.12.1 A Non-obvious Benefit of Using Checkpoints 2599 ------------------------------------------------- 2600 2601 On some systems such as GNU/Linux, address space randomization is 2602 performed on new processes for security reasons. This makes it 2603 difficult or impossible to set a breakpoint, or watchpoint, on an 2604 absolute address if you have to restart the program, since the absolute 2605 location of a symbol will change from one execution to the next. 2606 2607 A checkpoint, however, is an _identical_ copy of a process. 2608 Therefore if you create a checkpoint at (eg.) the start of main, and 2609 simply return to that checkpoint instead of restarting the process, you 2610 can avoid the effects of address randomization and your symbols will 2611 all stay in the same place. 2612 2613 ---------- Footnotes ---------- 2614 2615 (1) Currently, only GNU/Linux. 2616 2617 2618 File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top 2619 2620 5 Stopping and Continuing 2621 ************************* 2622 2623 The principal purposes of using a debugger are so that you can stop your 2624 program before it terminates; or so that, if your program runs into 2625 trouble, you can investigate and find out why. 2626 2627 Inside GDB, your program may stop for any of several reasons, such 2628 as a signal, a breakpoint, or reaching a new line after a GDB command 2629 such as `step'. You may then examine and change variables, set new 2630 breakpoints or remove old ones, and then continue execution. Usually, 2631 the messages shown by GDB provide ample explanation of the status of 2632 your program--but you can also explicitly request this information at 2633 any time. 2634 2635 `info program' 2636 Display information about the status of your program: whether it is 2637 running or not, what process it is, and why it stopped. 2638 2639 * Menu: 2640 2641 * Breakpoints:: Breakpoints, watchpoints, and catchpoints 2642 * Continuing and Stepping:: Resuming execution 2643 * Signals:: Signals 2644 * Thread Stops:: Stopping and starting multi-thread programs 2645 2646 2647 File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping 2648 2649 5.1 Breakpoints, Watchpoints, and Catchpoints 2650 ============================================= 2651 2652 A "breakpoint" makes your program stop whenever a certain point in the 2653 program is reached. For each breakpoint, you can add conditions to 2654 control in finer detail whether your program stops. You can set 2655 breakpoints with the `break' command and its variants (*note Setting 2656 Breakpoints: Set Breaks.), to specify the place where your program 2657 should stop by line number, function name or exact address in the 2658 program. 2659 2660 On some systems, you can set breakpoints in shared libraries before 2661 the executable is run. There is a minor limitation on HP-UX systems: 2662 you must wait until the executable is run in order to set breakpoints 2663 in shared library routines that are not called directly by the program 2664 (for example, routines that are arguments in a `pthread_create' call). 2665 2666 A "watchpoint" is a special breakpoint that stops your program when 2667 the value of an expression changes. The expression may be a value of a 2668 variable, or it could involve values of one or more variables combined 2669 by operators, such as `a + b'. This is sometimes called "data 2670 breakpoints". You must use a different command to set watchpoints 2671 (*note Setting Watchpoints: Set Watchpoints.), but aside from that, you 2672 can manage a watchpoint like any other breakpoint: you enable, disable, 2673 and delete both breakpoints and watchpoints using the same commands. 2674 2675 You can arrange to have values from your program displayed 2676 automatically whenever GDB stops at a breakpoint. *Note Automatic 2677 Display: Auto Display. 2678 2679 A "catchpoint" is another special breakpoint that stops your program 2680 when a certain kind of event occurs, such as the throwing of a C++ 2681 exception or the loading of a library. As with watchpoints, you use a 2682 different command to set a catchpoint (*note Setting Catchpoints: Set 2683 Catchpoints.), but aside from that, you can manage a catchpoint like any 2684 other breakpoint. (To stop when your program receives a signal, use the 2685 `handle' command; see *Note Signals: Signals.) 2686 2687 GDB assigns a number to each breakpoint, watchpoint, or catchpoint 2688 when you create it; these numbers are successive integers starting with 2689 one. In many of the commands for controlling various features of 2690 breakpoints you use the breakpoint number to say which breakpoint you 2691 want to change. Each breakpoint may be "enabled" or "disabled"; if 2692 disabled, it has no effect on your program until you enable it again. 2693 2694 Some GDB commands accept a range of breakpoints on which to operate. 2695 A breakpoint range is either a single breakpoint number, like `5', or 2696 two such numbers, in increasing order, separated by a hyphen, like 2697 `5-7'. When a breakpoint range is given to a command, all breakpoints 2698 in that range are operated on. 2699 2700 * Menu: 2701 2702 * Set Breaks:: Setting breakpoints 2703 * Set Watchpoints:: Setting watchpoints 2704 * Set Catchpoints:: Setting catchpoints 2705 * Delete Breaks:: Deleting breakpoints 2706 * Disabling:: Disabling breakpoints 2707 * Conditions:: Break conditions 2708 * Break Commands:: Breakpoint command lists 2709 * Error in Breakpoints:: ``Cannot insert breakpoints'' 2710 * Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' 2711 2712 2713 File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints 2714 2715 5.1.1 Setting Breakpoints 2716 ------------------------- 2717 2718 Breakpoints are set with the `break' command (abbreviated `b'). The 2719 debugger convenience variable `$bpnum' records the number of the 2720 breakpoint you've set most recently; see *Note Convenience Variables: 2721 Convenience Vars, for a discussion of what you can do with convenience 2722 variables. 2723 2724 `break LOCATION' 2725 Set a breakpoint at the given LOCATION, which can specify a 2726 function name, a line number, or an address of an instruction. 2727 (*Note Specify Location::, for a list of all the possible ways to 2728 specify a LOCATION.) The breakpoint will stop your program just 2729 before it executes any of the code in the specified LOCATION. 2730 2731 When using source languages that permit overloading of symbols, 2732 such as C++, a function name may refer to more than one possible 2733 place to break. *Note Ambiguous Expressions: Ambiguous 2734 Expressions, for a discussion of that situation. 2735 2736 It is also possible to insert a breakpoint that will stop the 2737 program only if a specific thread (*note Thread-Specific 2738 Breakpoints::) or a specific task (*note Ada Tasks::) hits that 2739 breakpoint. 2740 2741 `break' 2742 When called without any arguments, `break' sets a breakpoint at 2743 the next instruction to be executed in the selected stack frame 2744 (*note Examining the Stack: Stack.). In any selected frame but the 2745 innermost, this makes your program stop as soon as control returns 2746 to that frame. This is similar to the effect of a `finish' 2747 command in the frame inside the selected frame--except that 2748 `finish' does not leave an active breakpoint. If you use `break' 2749 without an argument in the innermost frame, GDB stops the next 2750 time it reaches the current location; this may be useful inside 2751 loops. 2752 2753 GDB normally ignores breakpoints when it resumes execution, until 2754 at least one instruction has been executed. If it did not do 2755 this, you would be unable to proceed past a breakpoint without 2756 first disabling the breakpoint. This rule applies whether or not 2757 the breakpoint already existed when your program stopped. 2758 2759 `break ... if COND' 2760 Set a breakpoint with condition COND; evaluate the expression COND 2761 each time the breakpoint is reached, and stop only if the value is 2762 nonzero--that is, if COND evaluates as true. `...' stands for one 2763 of the possible arguments described above (or no argument) 2764 specifying where to break. *Note Break Conditions: Conditions, 2765 for more information on breakpoint conditions. 2766 2767 `tbreak ARGS' 2768 Set a breakpoint enabled only for one stop. ARGS are the same as 2769 for the `break' command, and the breakpoint is set in the same 2770 way, but the breakpoint is automatically deleted after the first 2771 time your program stops there. *Note Disabling Breakpoints: 2772 Disabling. 2773 2774 `hbreak ARGS' 2775 Set a hardware-assisted breakpoint. ARGS are the same as for the 2776 `break' command and the breakpoint is set in the same way, but the 2777 breakpoint requires hardware support and some target hardware may 2778 not have this support. The main purpose of this is EPROM/ROM code 2779 debugging, so you can set a breakpoint at an instruction without 2780 changing the instruction. This can be used with the new 2781 trap-generation provided by SPARClite DSU and most x86-based 2782 targets. These targets will generate traps when a program 2783 accesses some data or instruction address that is assigned to the 2784 debug registers. However the hardware breakpoint registers can 2785 take a limited number of breakpoints. For example, on the DSU, 2786 only two data breakpoints can be set at a time, and GDB will 2787 reject this command if more than two are used. Delete or disable 2788 unused hardware breakpoints before setting new ones (*note 2789 Disabling Breakpoints: Disabling.). *Note Break Conditions: 2790 Conditions. For remote targets, you can restrict the number of 2791 hardware breakpoints GDB will use, see *Note set remote 2792 hardware-breakpoint-limit::. 2793 2794 `thbreak ARGS' 2795 Set a hardware-assisted breakpoint enabled only for one stop. ARGS 2796 are the same as for the `hbreak' command and the breakpoint is set 2797 in the same way. However, like the `tbreak' command, the 2798 breakpoint is automatically deleted after the first time your 2799 program stops there. Also, like the `hbreak' command, the 2800 breakpoint requires hardware support and some target hardware may 2801 not have this support. *Note Disabling Breakpoints: Disabling. 2802 See also *Note Break Conditions: Conditions. 2803 2804 `rbreak REGEX' 2805 Set breakpoints on all functions matching the regular expression 2806 REGEX. This command sets an unconditional breakpoint on all 2807 matches, printing a list of all breakpoints it set. Once these 2808 breakpoints are set, they are treated just like the breakpoints 2809 set with the `break' command. You can delete them, disable them, 2810 or make them conditional the same way as any other breakpoint. 2811 2812 The syntax of the regular expression is the standard one used with 2813 tools like `grep'. Note that this is different from the syntax 2814 used by shells, so for instance `foo*' matches all functions that 2815 include an `fo' followed by zero or more `o's. There is an 2816 implicit `.*' leading and trailing the regular expression you 2817 supply, so to match only functions that begin with `foo', use 2818 `^foo'. 2819 2820 When debugging C++ programs, `rbreak' is useful for setting 2821 breakpoints on overloaded functions that are not members of any 2822 special classes. 2823 2824 The `rbreak' command can be used to set breakpoints in *all* the 2825 functions in a program, like this: 2826 2827 (gdb) rbreak . 2828 2829 `info breakpoints [N]' 2830 `info break [N]' 2831 `info watchpoints [N]' 2832 Print a table of all breakpoints, watchpoints, and catchpoints set 2833 and not deleted. Optional argument N means print information only 2834 about the specified breakpoint (or watchpoint or catchpoint). For 2835 each breakpoint, following columns are printed: 2836 2837 _Breakpoint Numbers_ 2838 2839 _Type_ 2840 Breakpoint, watchpoint, or catchpoint. 2841 2842 _Disposition_ 2843 Whether the breakpoint is marked to be disabled or deleted 2844 when hit. 2845 2846 _Enabled or Disabled_ 2847 Enabled breakpoints are marked with `y'. `n' marks 2848 breakpoints that are not enabled. 2849 2850 _Address_ 2851 Where the breakpoint is in your program, as a memory address. 2852 For a pending breakpoint whose address is not yet known, 2853 this field will contain `<PENDING>'. Such breakpoint won't 2854 fire until a shared library that has the symbol or line 2855 referred by breakpoint is loaded. See below for details. A 2856 breakpoint with several locations will have `<MULTIPLE>' in 2857 this field--see below for details. 2858 2859 _What_ 2860 Where the breakpoint is in the source for your program, as a 2861 file and line number. For a pending breakpoint, the original 2862 string passed to the breakpoint command will be listed as it 2863 cannot be resolved until the appropriate shared library is 2864 loaded in the future. 2865 2866 If a breakpoint is conditional, `info break' shows the condition on 2867 the line following the affected breakpoint; breakpoint commands, 2868 if any, are listed after that. A pending breakpoint is allowed to 2869 have a condition specified for it. The condition is not parsed 2870 for validity until a shared library is loaded that allows the 2871 pending breakpoint to resolve to a valid location. 2872 2873 `info break' with a breakpoint number N as argument lists only 2874 that breakpoint. The convenience variable `$_' and the default 2875 examining-address for the `x' command are set to the address of 2876 the last breakpoint listed (*note Examining Memory: Memory.). 2877 2878 `info break' displays a count of the number of times the breakpoint 2879 has been hit. This is especially useful in conjunction with the 2880 `ignore' command. You can ignore a large number of breakpoint 2881 hits, look at the breakpoint info to see how many times the 2882 breakpoint was hit, and then run again, ignoring one less than 2883 that number. This will get you quickly to the last hit of that 2884 breakpoint. 2885 2886 GDB allows you to set any number of breakpoints at the same place in 2887 your program. There is nothing silly or meaningless about this. When 2888 the breakpoints are conditional, this is even useful (*note Break 2889 Conditions: Conditions.). 2890 2891 It is possible that a breakpoint corresponds to several locations in 2892 your program. Examples of this situation are: 2893 2894 * For a C++ constructor, the GCC compiler generates several 2895 instances of the function body, used in different cases. 2896 2897 * For a C++ template function, a given line in the function can 2898 correspond to any number of instantiations. 2899 2900 * For an inlined function, a given source line can correspond to 2901 several places where that function is inlined. 2902 2903 In all those cases, GDB will insert a breakpoint at all the relevant 2904 locations(1). 2905 2906 A breakpoint with multiple locations is displayed in the breakpoint 2907 table using several rows--one header row, followed by one row for each 2908 breakpoint location. The header row has `<MULTIPLE>' in the address 2909 column. The rows for individual locations contain the actual addresses 2910 for locations, and show the functions to which those locations belong. 2911 The number column for a location is of the form 2912 BREAKPOINT-NUMBER.LOCATION-NUMBER. 2913 2914 For example: 2915 2916 Num Type Disp Enb Address What 2917 1 breakpoint keep y <MULTIPLE> 2918 stop only if i==1 2919 breakpoint already hit 1 time 2920 1.1 y 0x080486a2 in void foo<int>() at t.cc:8 2921 1.2 y 0x080486ca in void foo<double>() at t.cc:8 2922 2923 Each location can be individually enabled or disabled by passing 2924 BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and 2925 `disable' commands. Note that you cannot delete the individual 2926 locations from the list, you can only delete the entire list of 2927 locations that belong to their parent breakpoint (with the `delete NUM' 2928 command, where NUM is the number of the parent breakpoint, 1 in the 2929 above example). Disabling or enabling the parent breakpoint (*note 2930 Disabling::) affects all of the locations that belong to that 2931 breakpoint. 2932 2933 It's quite common to have a breakpoint inside a shared library. 2934 Shared libraries can be loaded and unloaded explicitly, and possibly 2935 repeatedly, as the program is executed. To support this use case, GDB 2936 updates breakpoint locations whenever any shared library is loaded or 2937 unloaded. Typically, you would set a breakpoint in a shared library at 2938 the beginning of your debugging session, when the library is not 2939 loaded, and when the symbols from the library are not available. When 2940 you try to set breakpoint, GDB will ask you if you want to set a so 2941 called "pending breakpoint"--breakpoint whose address is not yet 2942 resolved. 2943 2944 After the program is run, whenever a new shared library is loaded, 2945 GDB reevaluates all the breakpoints. When a newly loaded shared 2946 library contains the symbol or line referred to by some pending 2947 breakpoint, that breakpoint is resolved and becomes an ordinary 2948 breakpoint. When a library is unloaded, all breakpoints that refer to 2949 its symbols or source lines become pending again. 2950 2951 This logic works for breakpoints with multiple locations, too. For 2952 example, if you have a breakpoint in a C++ template function, and a 2953 newly loaded shared library has an instantiation of that template, a 2954 new location is added to the list of locations for the breakpoint. 2955 2956 Except for having unresolved address, pending breakpoints do not 2957 differ from regular breakpoints. You can set conditions or commands, 2958 enable and disable them and perform other breakpoint operations. 2959 2960 GDB provides some additional commands for controlling what happens 2961 when the `break' command cannot resolve breakpoint address 2962 specification to an address: 2963 2964 `set breakpoint pending auto' 2965 This is the default behavior. When GDB cannot find the breakpoint 2966 location, it queries you whether a pending breakpoint should be 2967 created. 2968 2969 `set breakpoint pending on' 2970 This indicates that an unrecognized breakpoint location should 2971 automatically result in a pending breakpoint being created. 2972 2973 `set breakpoint pending off' 2974 This indicates that pending breakpoints are not to be created. Any 2975 unrecognized breakpoint location results in an error. This 2976 setting does not affect any pending breakpoints previously created. 2977 2978 `show breakpoint pending' 2979 Show the current behavior setting for creating pending breakpoints. 2980 2981 The settings above only affect the `break' command and its variants. 2982 Once breakpoint is set, it will be automatically updated as shared 2983 libraries are loaded and unloaded. 2984 2985 For some targets, GDB can automatically decide if hardware or 2986 software breakpoints should be used, depending on whether the 2987 breakpoint address is read-only or read-write. This applies to 2988 breakpoints set with the `break' command as well as to internal 2989 breakpoints set by commands like `next' and `finish'. For breakpoints 2990 set with `hbreak', GDB will always use hardware breakpoints. 2991 2992 You can control this automatic behaviour with the following 2993 commands:: 2994 2995 `set breakpoint auto-hw on' 2996 This is the default behavior. When GDB sets a breakpoint, it will 2997 try to use the target memory map to decide if software or hardware 2998 breakpoint must be used. 2999 3000 `set breakpoint auto-hw off' 3001 This indicates GDB should not automatically select breakpoint 3002 type. If the target provides a memory map, GDB will warn when 3003 trying to set software breakpoint at a read-only address. 3004 3005 GDB normally implements breakpoints by replacing the program code at 3006 the breakpoint address with a special instruction, which, when 3007 executed, given control to the debugger. By default, the program code 3008 is so modified only when the program is resumed. As soon as the 3009 program stops, GDB restores the original instructions. This behaviour 3010 guards against leaving breakpoints inserted in the target should gdb 3011 abrubptly disconnect. However, with slow remote targets, inserting and 3012 removing breakpoint can reduce the performance. This behavior can be 3013 controlled with the following commands:: 3014 3015 `set breakpoint always-inserted off' 3016 All breakpoints, including newly added by the user, are inserted in 3017 the target only when the target is resumed. All breakpoints are 3018 removed from the target when it stops. 3019 3020 `set breakpoint always-inserted on' 3021 Causes all breakpoints to be inserted in the target at all times. 3022 If the user adds a new breakpoint, or changes an existing 3023 breakpoint, the breakpoints in the target are updated immediately. 3024 A breakpoint is removed from the target only when breakpoint 3025 itself is removed. 3026 3027 `set breakpoint always-inserted auto' 3028 This is the default mode. If GDB is controlling the inferior in 3029 non-stop mode (*note Non-Stop Mode::), gdb behaves as if 3030 `breakpoint always-inserted' mode is on. If GDB is controlling 3031 the inferior in all-stop mode, GDB behaves as if `breakpoint 3032 always-inserted' mode is off. 3033 3034 GDB itself sometimes sets breakpoints in your program for special 3035 purposes, such as proper handling of `longjmp' (in C programs). These 3036 internal breakpoints are assigned negative numbers, starting with `-1'; 3037 `info breakpoints' does not display them. You can see these 3038 breakpoints with the GDB maintenance command `maint info breakpoints' 3039 (*note maint info breakpoints::). 3040 3041 ---------- Footnotes ---------- 3042 3043 (1) As of this writing, multiple-location breakpoints work only if 3044 there's line number information for all the locations. This means that 3045 they will generally not work in system libraries, unless you have debug 3046 info with line numbers for them. 3047 3048 3049 File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints 3050 3051 5.1.2 Setting Watchpoints 3052 ------------------------- 3053 3054 You can use a watchpoint to stop execution whenever the value of an 3055 expression changes, without having to predict a particular place where 3056 this may happen. (This is sometimes called a "data breakpoint".) The 3057 expression may be as simple as the value of a single variable, or as 3058 complex as many variables combined by operators. Examples include: 3059 3060 * A reference to the value of a single variable. 3061 3062 * An address cast to an appropriate data type. For example, `*(int 3063 *)0x12345678' will watch a 4-byte region at the specified address 3064 (assuming an `int' occupies 4 bytes). 3065 3066 * An arbitrarily complex expression, such as `a*b + c/d'. The 3067 expression can use any operators valid in the program's native 3068 language (*note Languages::). 3069 3070 You can set a watchpoint on an expression even if the expression can 3071 not be evaluated yet. For instance, you can set a watchpoint on 3072 `*global_ptr' before `global_ptr' is initialized. GDB will stop when 3073 your program sets `global_ptr' and the expression produces a valid 3074 value. If the expression becomes valid in some other way than changing 3075 a variable (e.g. if the memory pointed to by `*global_ptr' becomes 3076 readable as the result of a `malloc' call), GDB may not stop until the 3077 next time the expression changes. 3078 3079 Depending on your system, watchpoints may be implemented in software 3080 or hardware. GDB does software watchpointing by single-stepping your 3081 program and testing the variable's value each time, which is hundreds of 3082 times slower than normal execution. (But this may still be worth it, to 3083 catch errors where you have no clue what part of your program is the 3084 culprit.) 3085 3086 On some systems, such as HP-UX, PowerPC, GNU/Linux and most other 3087 x86-based targets, GDB includes support for hardware watchpoints, which 3088 do not slow down the running of your program. 3089 3090 `watch EXPR [thread THREADNUM]' 3091 Set a watchpoint for an expression. GDB will break when the 3092 expression EXPR is written into by the program and its value 3093 changes. The simplest (and the most popular) use of this command 3094 is to watch the value of a single variable: 3095 3096 (gdb) watch foo 3097 3098 If the command includes a `[thread THREADNUM]' clause, GDB breaks 3099 only when the thread identified by THREADNUM changes the value of 3100 EXPR. If any other threads change the value of EXPR, GDB will not 3101 break. Note that watchpoints restricted to a single thread in 3102 this way only work with Hardware Watchpoints. 3103 3104 `rwatch EXPR [thread THREADNUM]' 3105 Set a watchpoint that will break when the value of EXPR is read by 3106 the program. 3107 3108 `awatch EXPR [thread THREADNUM]' 3109 Set a watchpoint that will break when EXPR is either read from or 3110 written into by the program. 3111 3112 `info watchpoints' 3113 This command prints a list of watchpoints, breakpoints, and 3114 catchpoints; it is the same as `info break' (*note Set Breaks::). 3115 3116 GDB sets a "hardware watchpoint" if possible. Hardware watchpoints 3117 execute very quickly, and the debugger reports a change in value at the 3118 exact instruction where the change occurs. If GDB cannot set a 3119 hardware watchpoint, it sets a software watchpoint, which executes more 3120 slowly and reports the change in value at the next _statement_, not the 3121 instruction, after the change occurs. 3122 3123 You can force GDB to use only software watchpoints with the `set 3124 can-use-hw-watchpoints 0' command. With this variable set to zero, GDB 3125 will never try to use hardware watchpoints, even if the underlying 3126 system supports them. (Note that hardware-assisted watchpoints that 3127 were set _before_ setting `can-use-hw-watchpoints' to zero will still 3128 use the hardware mechanism of watching expression values.) 3129 3130 `set can-use-hw-watchpoints' 3131 Set whether or not to use hardware watchpoints. 3132 3133 `show can-use-hw-watchpoints' 3134 Show the current mode of using hardware watchpoints. 3135 3136 For remote targets, you can restrict the number of hardware 3137 watchpoints GDB will use, see *Note set remote 3138 hardware-breakpoint-limit::. 3139 3140 When you issue the `watch' command, GDB reports 3141 3142 Hardware watchpoint NUM: EXPR 3143 3144 if it was able to set a hardware watchpoint. 3145 3146 Currently, the `awatch' and `rwatch' commands can only set hardware 3147 watchpoints, because accesses to data that don't change the value of 3148 the watched expression cannot be detected without examining every 3149 instruction as it is being executed, and GDB does not do that 3150 currently. If GDB finds that it is unable to set a hardware breakpoint 3151 with the `awatch' or `rwatch' command, it will print a message like 3152 this: 3153 3154 Expression cannot be implemented with read/access watchpoint. 3155 3156 Sometimes, GDB cannot set a hardware watchpoint because the data 3157 type of the watched expression is wider than what a hardware watchpoint 3158 on the target machine can handle. For example, some systems can only 3159 watch regions that are up to 4 bytes wide; on such systems you cannot 3160 set hardware watchpoints for an expression that yields a 3161 double-precision floating-point number (which is typically 8 bytes 3162 wide). As a work-around, it might be possible to break the large region 3163 into a series of smaller ones and watch them with separate watchpoints. 3164 3165 If you set too many hardware watchpoints, GDB might be unable to 3166 insert all of them when you resume the execution of your program. 3167 Since the precise number of active watchpoints is unknown until such 3168 time as the program is about to be resumed, GDB might not be able to 3169 warn you about this when you set the watchpoints, and the warning will 3170 be printed only when the program is resumed: 3171 3172 Hardware watchpoint NUM: Could not insert watchpoint 3173 3174 If this happens, delete or disable some of the watchpoints. 3175 3176 Watching complex expressions that reference many variables can also 3177 exhaust the resources available for hardware-assisted watchpoints. 3178 That's because GDB needs to watch every variable in the expression with 3179 separately allocated resources. 3180 3181 If you call a function interactively using `print' or `call', any 3182 watchpoints you have set will be inactive until GDB reaches another 3183 kind of breakpoint or the call completes. 3184 3185 GDB automatically deletes watchpoints that watch local (automatic) 3186 variables, or expressions that involve such variables, when they go out 3187 of scope, that is, when the execution leaves the block in which these 3188 variables were defined. In particular, when the program being debugged 3189 terminates, _all_ local variables go out of scope, and so only 3190 watchpoints that watch global variables remain set. If you rerun the 3191 program, you will need to set all such watchpoints again. One way of 3192 doing that would be to set a code breakpoint at the entry to the `main' 3193 function and when it breaks, set all the watchpoints. 3194 3195 In multi-threaded programs, watchpoints will detect changes to the 3196 watched expression from every thread. 3197 3198 _Warning:_ In multi-threaded programs, software watchpoints have 3199 only limited usefulness. If GDB creates a software watchpoint, it 3200 can only watch the value of an expression _in a single thread_. 3201 If you are confident that the expression can only change due to 3202 the current thread's activity (and if you are also confident that 3203 no other thread can become current), then you can use software 3204 watchpoints as usual. However, GDB may not notice when a 3205 non-current thread's activity changes the expression. (Hardware 3206 watchpoints, in contrast, watch an expression in all threads.) 3207 3208 *Note set remote hardware-watchpoint-limit::. 3209 3210 3211 File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints 3212 3213 5.1.3 Setting Catchpoints 3214 ------------------------- 3215 3216 You can use "catchpoints" to cause the debugger to stop for certain 3217 kinds of program events, such as C++ exceptions or the loading of a 3218 shared library. Use the `catch' command to set a catchpoint. 3219 3220 `catch EVENT' 3221 Stop when EVENT occurs. EVENT can be any of the following: 3222 `throw' 3223 The throwing of a C++ exception. 3224 3225 `catch' 3226 The catching of a C++ exception. 3227 3228 `exception' 3229 An Ada exception being raised. If an exception name is 3230 specified at the end of the command (eg `catch exception 3231 Program_Error'), the debugger will stop only when this 3232 specific exception is raised. Otherwise, the debugger stops 3233 execution when any Ada exception is raised. 3234 3235 When inserting an exception catchpoint on a user-defined 3236 exception whose name is identical to one of the exceptions 3237 defined by the language, the fully qualified name must be 3238 used as the exception name. Otherwise, GDB will assume that 3239 it should stop on the pre-defined exception rather than the 3240 user-defined one. For instance, assuming an exception called 3241 `Constraint_Error' is defined in package `Pck', then the 3242 command to use to catch such exceptions is `catch exception 3243 Pck.Constraint_Error'. 3244 3245 `exception unhandled' 3246 An exception that was raised but is not handled by the 3247 program. 3248 3249 `assert' 3250 A failed Ada assertion. 3251 3252 `exec' 3253 A call to `exec'. This is currently only available for HP-UX 3254 and GNU/Linux. 3255 3256 `syscall' 3257 `syscall [NAME | NUMBER] ...' 3258 A call to or return from a system call, a.k.a. "syscall". A 3259 syscall is a mechanism for application programs to request a 3260 service from the operating system (OS) or one of the OS 3261 system services. GDB can catch some or all of the syscalls 3262 issued by the debuggee, and show the related information for 3263 each syscall. If no argument is specified, calls to and 3264 returns from all system calls will be caught. 3265 3266 NAME can be any system call name that is valid for the 3267 underlying OS. Just what syscalls are valid depends on the 3268 OS. On GNU and Unix systems, you can find the full list of 3269 valid syscall names on `/usr/include/asm/unistd.h'. 3270 3271 Normally, GDB knows in advance which syscalls are valid for 3272 each OS, so you can use the GDB command-line completion 3273 facilities (*note command completion: Completion.) to list the 3274 available choices. 3275 3276 You may also specify the system call numerically. A syscall's 3277 number is the value passed to the OS's syscall dispatcher to 3278 identify the requested service. When you specify the syscall 3279 by its name, GDB uses its database of syscalls to convert the 3280 name into the corresponding numeric code, but using the 3281 number directly may be useful if GDB's database does not have 3282 the complete list of syscalls on your system (e.g., because 3283 GDB lags behind the OS upgrades). 3284 3285 The example below illustrates how this command works if you 3286 don't provide arguments to it: 3287 3288 (gdb) catch syscall 3289 Catchpoint 1 (syscall) 3290 (gdb) r 3291 Starting program: /tmp/catch-syscall 3292 3293 Catchpoint 1 (call to syscall 'close'), \ 3294 0xffffe424 in __kernel_vsyscall () 3295 (gdb) c 3296 Continuing. 3297 3298 Catchpoint 1 (returned from syscall 'close'), \ 3299 0xffffe424 in __kernel_vsyscall () 3300 (gdb) 3301 3302 Here is an example of catching a system call by name: 3303 3304 (gdb) catch syscall chroot 3305 Catchpoint 1 (syscall 'chroot' [61]) 3306 (gdb) r 3307 Starting program: /tmp/catch-syscall 3308 3309 Catchpoint 1 (call to syscall 'chroot'), \ 3310 0xffffe424 in __kernel_vsyscall () 3311 (gdb) c 3312 Continuing. 3313 3314 Catchpoint 1 (returned from syscall 'chroot'), \ 3315 0xffffe424 in __kernel_vsyscall () 3316 (gdb) 3317 3318 An example of specifying a system call numerically. In the 3319 case below, the syscall number has a corresponding entry in 3320 the XML file, so GDB finds its name and prints it: 3321 3322 (gdb) catch syscall 252 3323 Catchpoint 1 (syscall(s) 'exit_group') 3324 (gdb) r 3325 Starting program: /tmp/catch-syscall 3326 3327 Catchpoint 1 (call to syscall 'exit_group'), \ 3328 0xffffe424 in __kernel_vsyscall () 3329 (gdb) c 3330 Continuing. 3331 3332 Program exited normally. 3333 (gdb) 3334 3335 However, there can be situations when there is no 3336 corresponding name in XML file for that syscall number. In 3337 this case, GDB prints a warning message saying that it was 3338 not able to find the syscall name, but the catchpoint will be 3339 set anyway. See the example below: 3340 3341 (gdb) catch syscall 764 3342 warning: The number '764' does not represent a known syscall. 3343 Catchpoint 2 (syscall 764) 3344 (gdb) 3345 3346 If you configure GDB using the `--without-expat' option, it 3347 will not be able to display syscall names. Also, if your 3348 architecture does not have an XML file describing its system 3349 calls, you will not be able to see the syscall names. It is 3350 important to notice that these two features are used for 3351 accessing the syscall name database. In either case, you 3352 will see a warning like this: 3353 3354 (gdb) catch syscall 3355 warning: Could not open "syscalls/i386-linux.xml" 3356 warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. 3357 GDB will not be able to display syscall names. 3358 Catchpoint 1 (syscall) 3359 (gdb) 3360 3361 Of course, the file name will change depending on your 3362 architecture and system. 3363 3364 Still using the example above, you can also try to catch a 3365 syscall by its number. In this case, you would see something 3366 like: 3367 3368 (gdb) catch syscall 252 3369 Catchpoint 1 (syscall(s) 252) 3370 3371 Again, in this case GDB would not be able to display 3372 syscall's names. 3373 3374 `fork' 3375 A call to `fork'. This is currently only available for HP-UX 3376 and GNU/Linux. 3377 3378 `vfork' 3379 A call to `vfork'. This is currently only available for HP-UX 3380 and GNU/Linux. 3381 3382 3383 `tcatch EVENT' 3384 Set a catchpoint that is enabled only for one stop. The 3385 catchpoint is automatically deleted after the first time the event 3386 is caught. 3387 3388 3389 Use the `info break' command to list the current catchpoints. 3390 3391 There are currently some limitations to C++ exception handling 3392 (`catch throw' and `catch catch') in GDB: 3393 3394 * If you call a function interactively, GDB normally returns control 3395 to you when the function has finished executing. If the call 3396 raises an exception, however, the call may bypass the mechanism 3397 that returns control to you and cause your program either to abort 3398 or to simply continue running until it hits a breakpoint, catches 3399 a signal that GDB is listening for, or exits. This is the case 3400 even if you set a catchpoint for the exception; catchpoints on 3401 exceptions are disabled within interactive calls. 3402 3403 * You cannot raise an exception interactively. 3404 3405 * You cannot install an exception handler interactively. 3406 3407 Sometimes `catch' is not the best way to debug exception handling: 3408 if you need to know exactly where an exception is raised, it is better 3409 to stop _before_ the exception handler is called, since that way you 3410 can see the stack before any unwinding takes place. If you set a 3411 breakpoint in an exception handler instead, it may not be easy to find 3412 out where the exception was raised. 3413 3414 To stop just before an exception handler is called, you need some 3415 knowledge of the implementation. In the case of GNU C++, exceptions are 3416 raised by calling a library function named `__raise_exception' which 3417 has the following ANSI C interface: 3418 3419 /* ADDR is where the exception identifier is stored. 3420 ID is the exception identifier. */ 3421 void __raise_exception (void **addr, void *id); 3422 3423 To make the debugger catch all exceptions before any stack unwinding 3424 takes place, set a breakpoint on `__raise_exception' (*note 3425 Breakpoints; Watchpoints; and Exceptions: Breakpoints.). 3426 3427 With a conditional breakpoint (*note Break Conditions: Conditions.) 3428 that depends on the value of ID, you can stop your program when a 3429 specific exception is raised. You can use multiple conditional 3430 breakpoints to stop your program when any of a number of exceptions are 3431 raised. 3432 3433 3434 File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints 3435 3436 5.1.4 Deleting Breakpoints 3437 -------------------------- 3438 3439 It is often necessary to eliminate a breakpoint, watchpoint, or 3440 catchpoint once it has done its job and you no longer want your program 3441 to stop there. This is called "deleting" the breakpoint. A breakpoint 3442 that has been deleted no longer exists; it is forgotten. 3443 3444 With the `clear' command you can delete breakpoints according to 3445 where they are in your program. With the `delete' command you can 3446 delete individual breakpoints, watchpoints, or catchpoints by specifying 3447 their breakpoint numbers. 3448 3449 It is not necessary to delete a breakpoint to proceed past it. GDB 3450 automatically ignores breakpoints on the first instruction to be 3451 executed when you continue execution without changing the execution 3452 address. 3453 3454 `clear' 3455 Delete any breakpoints at the next instruction to be executed in 3456 the selected stack frame (*note Selecting a Frame: Selection.). 3457 When the innermost frame is selected, this is a good way to delete 3458 a breakpoint where your program just stopped. 3459 3460 `clear LOCATION' 3461 Delete any breakpoints set at the specified LOCATION. *Note 3462 Specify Location::, for the various forms of LOCATION; the most 3463 useful ones are listed below: 3464 3465 `clear FUNCTION' 3466 `clear FILENAME:FUNCTION' 3467 Delete any breakpoints set at entry to the named FUNCTION. 3468 3469 `clear LINENUM' 3470 `clear FILENAME:LINENUM' 3471 Delete any breakpoints set at or within the code of the 3472 specified LINENUM of the specified FILENAME. 3473 3474 `delete [breakpoints] [RANGE...]' 3475 Delete the breakpoints, watchpoints, or catchpoints of the 3476 breakpoint ranges specified as arguments. If no argument is 3477 specified, delete all breakpoints (GDB asks confirmation, unless 3478 you have `set confirm off'). You can abbreviate this command as 3479 `d'. 3480 3481 3482 File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints 3483 3484 5.1.5 Disabling Breakpoints 3485 --------------------------- 3486 3487 Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 3488 prefer to "disable" it. This makes the breakpoint inoperative as if it 3489 had been deleted, but remembers the information on the breakpoint so 3490 that you can "enable" it again later. 3491 3492 You disable and enable breakpoints, watchpoints, and catchpoints with 3493 the `enable' and `disable' commands, optionally specifying one or more 3494 breakpoint numbers as arguments. Use `info break' or `info watch' to 3495 print a list of breakpoints, watchpoints, and catchpoints if you do not 3496 know which numbers to use. 3497 3498 Disabling and enabling a breakpoint that has multiple locations 3499 affects all of its locations. 3500 3501 A breakpoint, watchpoint, or catchpoint can have any of four 3502 different states of enablement: 3503 3504 * Enabled. The breakpoint stops your program. A breakpoint set 3505 with the `break' command starts out in this state. 3506 3507 * Disabled. The breakpoint has no effect on your program. 3508 3509 * Enabled once. The breakpoint stops your program, but then becomes 3510 disabled. 3511 3512 * Enabled for deletion. The breakpoint stops your program, but 3513 immediately after it does so it is deleted permanently. A 3514 breakpoint set with the `tbreak' command starts out in this state. 3515 3516 You can use the following commands to enable or disable breakpoints, 3517 watchpoints, and catchpoints: 3518 3519 `disable [breakpoints] [RANGE...]' 3520 Disable the specified breakpoints--or all breakpoints, if none are 3521 listed. A disabled breakpoint has no effect but is not forgotten. 3522 All options such as ignore-counts, conditions and commands are 3523 remembered in case the breakpoint is enabled again later. You may 3524 abbreviate `disable' as `dis'. 3525 3526 `enable [breakpoints] [RANGE...]' 3527 Enable the specified breakpoints (or all defined breakpoints). 3528 They become effective once again in stopping your program. 3529 3530 `enable [breakpoints] once RANGE...' 3531 Enable the specified breakpoints temporarily. GDB disables any of 3532 these breakpoints immediately after stopping your program. 3533 3534 `enable [breakpoints] delete RANGE...' 3535 Enable the specified breakpoints to work once, then die. GDB 3536 deletes any of these breakpoints as soon as your program stops 3537 there. Breakpoints set by the `tbreak' command start out in this 3538 state. 3539 3540 Except for a breakpoint set with `tbreak' (*note Setting 3541 Breakpoints: Set Breaks.), breakpoints that you set are initially 3542 enabled; subsequently, they become disabled or enabled only when you 3543 use one of the commands above. (The command `until' can set and delete 3544 a breakpoint of its own, but it does not change the state of your other 3545 breakpoints; see *Note Continuing and Stepping: Continuing and 3546 Stepping.) 3547 3548 3549 File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints 3550 3551 5.1.6 Break Conditions 3552 ---------------------- 3553 3554 The simplest sort of breakpoint breaks every time your program reaches a 3555 specified place. You can also specify a "condition" for a breakpoint. 3556 A condition is just a Boolean expression in your programming language 3557 (*note Expressions: Expressions.). A breakpoint with a condition 3558 evaluates the expression each time your program reaches it, and your 3559 program stops only if the condition is _true_. 3560 3561 This is the converse of using assertions for program validation; in 3562 that situation, you want to stop when the assertion is violated--that 3563 is, when the condition is false. In C, if you want to test an 3564 assertion expressed by the condition ASSERT, you should set the 3565 condition `! ASSERT' on the appropriate breakpoint. 3566 3567 Conditions are also accepted for watchpoints; you may not need them, 3568 since a watchpoint is inspecting the value of an expression anyhow--but 3569 it might be simpler, say, to just set a watchpoint on a variable name, 3570 and specify a condition that tests whether the new value is an 3571 interesting one. 3572 3573 Break conditions can have side effects, and may even call functions 3574 in your program. This can be useful, for example, to activate functions 3575 that log program progress, or to use your own print functions to format 3576 special data structures. The effects are completely predictable unless 3577 there is another enabled breakpoint at the same address. (In that 3578 case, GDB might see the other breakpoint first and stop your program 3579 without checking the condition of this one.) Note that breakpoint 3580 commands are usually more convenient and flexible than break conditions 3581 for the purpose of performing side effects when a breakpoint is reached 3582 (*note Breakpoint Command Lists: Break Commands.). 3583 3584 Break conditions can be specified when a breakpoint is set, by using 3585 `if' in the arguments to the `break' command. *Note Setting 3586 Breakpoints: Set Breaks. They can also be changed at any time with the 3587 `condition' command. 3588 3589 You can also use the `if' keyword with the `watch' command. The 3590 `catch' command does not recognize the `if' keyword; `condition' is the 3591 only way to impose a further condition on a catchpoint. 3592 3593 `condition BNUM EXPRESSION' 3594 Specify EXPRESSION as the break condition for breakpoint, 3595 watchpoint, or catchpoint number BNUM. After you set a condition, 3596 breakpoint BNUM stops your program only if the value of EXPRESSION 3597 is true (nonzero, in C). When you use `condition', GDB checks 3598 EXPRESSION immediately for syntactic correctness, and to determine 3599 whether symbols in it have referents in the context of your 3600 breakpoint. If EXPRESSION uses symbols not referenced in the 3601 context of the breakpoint, GDB prints an error message: 3602 3603 No symbol "foo" in current context. 3604 3605 GDB does not actually evaluate EXPRESSION at the time the 3606 `condition' command (or a command that sets a breakpoint with a 3607 condition, like `break if ...') is given, however. *Note 3608 Expressions: Expressions. 3609 3610 `condition BNUM' 3611 Remove the condition from breakpoint number BNUM. It becomes an 3612 ordinary unconditional breakpoint. 3613 3614 A special case of a breakpoint condition is to stop only when the 3615 breakpoint has been reached a certain number of times. This is so 3616 useful that there is a special way to do it, using the "ignore count" 3617 of the breakpoint. Every breakpoint has an ignore count, which is an 3618 integer. Most of the time, the ignore count is zero, and therefore has 3619 no effect. But if your program reaches a breakpoint whose ignore count 3620 is positive, then instead of stopping, it just decrements the ignore 3621 count by one and continues. As a result, if the ignore count value is 3622 N, the breakpoint does not stop the next N times your program reaches 3623 it. 3624 3625 `ignore BNUM COUNT' 3626 Set the ignore count of breakpoint number BNUM to COUNT. The next 3627 COUNT times the breakpoint is reached, your program's execution 3628 does not stop; other than to decrement the ignore count, GDB takes 3629 no action. 3630 3631 To make the breakpoint stop the next time it is reached, specify a 3632 count of zero. 3633 3634 When you use `continue' to resume execution of your program from a 3635 breakpoint, you can specify an ignore count directly as an 3636 argument to `continue', rather than using `ignore'. *Note 3637 Continuing and Stepping: Continuing and Stepping. 3638 3639 If a breakpoint has a positive ignore count and a condition, the 3640 condition is not checked. Once the ignore count reaches zero, GDB 3641 resumes checking the condition. 3642 3643 You could achieve the effect of the ignore count with a condition 3644 such as `$foo-- <= 0' using a debugger convenience variable that 3645 is decremented each time. *Note Convenience Variables: 3646 Convenience Vars. 3647 3648 Ignore counts apply to breakpoints, watchpoints, and catchpoints. 3649 3650 3651 File: gdb.info, Node: Break Commands, Next: Error in Breakpoints, Prev: Conditions, Up: Breakpoints 3652 3653 5.1.7 Breakpoint Command Lists 3654 ------------------------------ 3655 3656 You can give any breakpoint (or watchpoint or catchpoint) a series of 3657 commands to execute when your program stops due to that breakpoint. For 3658 example, you might want to print the values of certain expressions, or 3659 enable other breakpoints. 3660 3661 `commands [BNUM]' 3662 `... COMMAND-LIST ...' 3663 `end' 3664 Specify a list of commands for breakpoint number BNUM. The 3665 commands themselves appear on the following lines. Type a line 3666 containing just `end' to terminate the commands. 3667 3668 To remove all commands from a breakpoint, type `commands' and 3669 follow it immediately with `end'; that is, give no commands. 3670 3671 With no BNUM argument, `commands' refers to the last breakpoint, 3672 watchpoint, or catchpoint set (not to the breakpoint most recently 3673 encountered). 3674 3675 Pressing <RET> as a means of repeating the last GDB command is 3676 disabled within a COMMAND-LIST. 3677 3678 You can use breakpoint commands to start your program up again. 3679 Simply use the `continue' command, or `step', or any other command that 3680 resumes execution. 3681 3682 Any other commands in the command list, after a command that resumes 3683 execution, are ignored. This is because any time you resume execution 3684 (even with a simple `next' or `step'), you may encounter another 3685 breakpoint--which could have its own command list, leading to 3686 ambiguities about which list to execute. 3687 3688 If the first command you specify in a command list is `silent', the 3689 usual message about stopping at a breakpoint is not printed. This may 3690 be desirable for breakpoints that are to print a specific message and 3691 then continue. If none of the remaining commands print anything, you 3692 see no sign that the breakpoint was reached. `silent' is meaningful 3693 only at the beginning of a breakpoint command list. 3694 3695 The commands `echo', `output', and `printf' allow you to print 3696 precisely controlled output, and are often useful in silent 3697 breakpoints. *Note Commands for Controlled Output: Output. 3698 3699 For example, here is how you could use breakpoint commands to print 3700 the value of `x' at entry to `foo' whenever `x' is positive. 3701 3702 break foo if x>0 3703 commands 3704 silent 3705 printf "x is %d\n",x 3706 cont 3707 end 3708 3709 One application for breakpoint commands is to compensate for one bug 3710 so you can test for another. Put a breakpoint just after the erroneous 3711 line of code, give it a condition to detect the case in which something 3712 erroneous has been done, and give it commands to assign correct values 3713 to any variables that need them. End with the `continue' command so 3714 that your program does not stop, and start with the `silent' command so 3715 that no output is produced. Here is an example: 3716 3717 break 403 3718 commands 3719 silent 3720 set x = y + 4 3721 cont 3722 end 3723 3724 3725 File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Break Commands, Up: Breakpoints 3726 3727 5.1.8 "Cannot insert breakpoints" 3728 --------------------------------- 3729 3730 If you request too many active hardware-assisted breakpoints and 3731 watchpoints, you will see this error message: 3732 3733 Stopped; cannot insert breakpoints. 3734 You may have requested too many hardware breakpoints and watchpoints. 3735 3736 This message is printed when you attempt to resume the program, since 3737 only then GDB knows exactly how many hardware breakpoints and 3738 watchpoints it needs to insert. 3739 3740 When this message is printed, you need to disable or remove some of 3741 the hardware-assisted breakpoints and watchpoints, and then continue. 3742 3743 3744 File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints 3745 3746 5.1.9 "Breakpoint address adjusted..." 3747 -------------------------------------- 3748 3749 Some processor architectures place constraints on the addresses at 3750 which breakpoints may be placed. For architectures thus constrained, 3751 GDB will attempt to adjust the breakpoint's address to comply with the 3752 constraints dictated by the architecture. 3753 3754 One example of such an architecture is the Fujitsu FR-V. The FR-V is 3755 a VLIW architecture in which a number of RISC-like instructions may be 3756 bundled together for parallel execution. The FR-V architecture 3757 constrains the location of a breakpoint instruction within such a 3758 bundle to the instruction with the lowest address. GDB honors this 3759 constraint by adjusting a breakpoint's address to the first in the 3760 bundle. 3761 3762 It is not uncommon for optimized code to have bundles which contain 3763 instructions from different source statements, thus it may happen that 3764 a breakpoint's address will be adjusted from one source statement to 3765 another. Since this adjustment may significantly alter GDB's 3766 breakpoint related behavior from what the user expects, a warning is 3767 printed when the breakpoint is first set and also when the breakpoint 3768 is hit. 3769 3770 A warning like the one below is printed when setting a breakpoint 3771 that's been subject to address adjustment: 3772 3773 warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. 3774 3775 Such warnings are printed both for user settable and GDB's internal 3776 breakpoints. If you see one of these warnings, you should verify that 3777 a breakpoint set at the adjusted address will have the desired affect. 3778 If not, the breakpoint in question may be removed and other breakpoints 3779 may be set which will have the desired behavior. E.g., it may be 3780 sufficient to place the breakpoint at a later instruction. A 3781 conditional breakpoint may also be useful in some cases to prevent the 3782 breakpoint from triggering too often. 3783 3784 GDB will also issue a warning when stopping at one of these adjusted 3785 breakpoints: 3786 3787 warning: Breakpoint 1 address previously adjusted from 0x00010414 3788 to 0x00010410. 3789 3790 When this warning is encountered, it may be too late to take remedial 3791 action except in cases where the breakpoint is hit earlier or more 3792 frequently than expected. 3793 3794 3795 File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping 3796 3797 5.2 Continuing and Stepping 3798 =========================== 3799 3800 "Continuing" means resuming program execution until your program 3801 completes normally. In contrast, "stepping" means executing just one 3802 more "step" of your program, where "step" may mean either one line of 3803 source code, or one machine instruction (depending on what particular 3804 command you use). Either when continuing or when stepping, your 3805 program may stop even sooner, due to a breakpoint or a signal. (If it 3806 stops due to a signal, you may want to use `handle', or use `signal 0' 3807 to resume execution. *Note Signals: Signals.) 3808 3809 `continue [IGNORE-COUNT]' 3810 `c [IGNORE-COUNT]' 3811 `fg [IGNORE-COUNT]' 3812 Resume program execution, at the address where your program last 3813 stopped; any breakpoints set at that address are bypassed. The 3814 optional argument IGNORE-COUNT allows you to specify a further 3815 number of times to ignore a breakpoint at this location; its 3816 effect is like that of `ignore' (*note Break Conditions: 3817 Conditions.). 3818 3819 The argument IGNORE-COUNT is meaningful only when your program 3820 stopped due to a breakpoint. At other times, the argument to 3821 `continue' is ignored. 3822 3823 The synonyms `c' and `fg' (for "foreground", as the debugged 3824 program is deemed to be the foreground program) are provided 3825 purely for convenience, and have exactly the same behavior as 3826 `continue'. 3827 3828 To resume execution at a different place, you can use `return' 3829 (*note Returning from a Function: Returning.) to go back to the calling 3830 function; or `jump' (*note Continuing at a Different Address: Jumping.) 3831 to go to an arbitrary location in your program. 3832 3833 A typical technique for using stepping is to set a breakpoint (*note 3834 Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the 3835 beginning of the function or the section of your program where a problem 3836 is believed to lie, run your program until it stops at that breakpoint, 3837 and then step through the suspect area, examining the variables that are 3838 interesting, until you see the problem happen. 3839 3840 `step' 3841 Continue running your program until control reaches a different 3842 source line, then stop it and return control to GDB. This command 3843 is abbreviated `s'. 3844 3845 _Warning:_ If you use the `step' command while control is 3846 within a function that was compiled without debugging 3847 information, execution proceeds until control reaches a 3848 function that does have debugging information. Likewise, it 3849 will not step into a function which is compiled without 3850 debugging information. To step through functions without 3851 debugging information, use the `stepi' command, described 3852 below. 3853 3854 The `step' command only stops at the first instruction of a source 3855 line. This prevents the multiple stops that could otherwise occur 3856 in `switch' statements, `for' loops, etc. `step' continues to 3857 stop if a function that has debugging information is called within 3858 the line. In other words, `step' _steps inside_ any functions 3859 called within the line. 3860 3861 Also, the `step' command only enters a function if there is line 3862 number information for the function. Otherwise it acts like the 3863 `next' command. This avoids problems when using `cc -gl' on MIPS 3864 machines. Previously, `step' entered subroutines if there was any 3865 debugging information about the routine. 3866 3867 `step COUNT' 3868 Continue running as in `step', but do so COUNT times. If a 3869 breakpoint is reached, or a signal not related to stepping occurs 3870 before COUNT steps, stepping stops right away. 3871 3872 `next [COUNT]' 3873 Continue to the next source line in the current (innermost) stack 3874 frame. This is similar to `step', but function calls that appear 3875 within the line of code are executed without stopping. Execution 3876 stops when control reaches a different line of code at the 3877 original stack level that was executing when you gave the `next' 3878 command. This command is abbreviated `n'. 3879 3880 An argument COUNT is a repeat count, as for `step'. 3881 3882 The `next' command only stops at the first instruction of a source 3883 line. This prevents multiple stops that could otherwise occur in 3884 `switch' statements, `for' loops, etc. 3885 3886 `set step-mode' 3887 `set step-mode on' 3888 The `set step-mode on' command causes the `step' command to stop 3889 at the first instruction of a function which contains no debug line 3890 information rather than stepping over it. 3891 3892 This is useful in cases where you may be interested in inspecting 3893 the machine instructions of a function which has no symbolic info 3894 and do not want GDB to automatically skip over this function. 3895 3896 `set step-mode off' 3897 Causes the `step' command to step over any functions which 3898 contains no debug information. This is the default. 3899 3900 `show step-mode' 3901 Show whether GDB will stop in or step over functions without 3902 source line debug information. 3903 3904 `finish' 3905 Continue running until just after function in the selected stack 3906 frame returns. Print the returned value (if any). This command 3907 can be abbreviated as `fin'. 3908 3909 Contrast this with the `return' command (*note Returning from a 3910 Function: Returning.). 3911 3912 `until' 3913 `u' 3914 Continue running until a source line past the current line, in the 3915 current stack frame, is reached. This command is used to avoid 3916 single stepping through a loop more than once. It is like the 3917 `next' command, except that when `until' encounters a jump, it 3918 automatically continues execution until the program counter is 3919 greater than the address of the jump. 3920 3921 This means that when you reach the end of a loop after single 3922 stepping though it, `until' makes your program continue execution 3923 until it exits the loop. In contrast, a `next' command at the end 3924 of a loop simply steps back to the beginning of the loop, which 3925 forces you to step through the next iteration. 3926 3927 `until' always stops your program if it attempts to exit the 3928 current stack frame. 3929 3930 `until' may produce somewhat counterintuitive results if the order 3931 of machine code does not match the order of the source lines. For 3932 example, in the following excerpt from a debugging session, the `f' 3933 (`frame') command shows that execution is stopped at line `206'; 3934 yet when we use `until', we get to line `195': 3935 3936 (gdb) f 3937 #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 3938 206 expand_input(); 3939 (gdb) until 3940 195 for ( ; argc > 0; NEXTARG) { 3941 3942 This happened because, for execution efficiency, the compiler had 3943 generated code for the loop closure test at the end, rather than 3944 the start, of the loop--even though the test in a C `for'-loop is 3945 written before the body of the loop. The `until' command appeared 3946 to step back to the beginning of the loop when it advanced to this 3947 expression; however, it has not really gone to an earlier 3948 statement--not in terms of the actual machine code. 3949 3950 `until' with no argument works by means of single instruction 3951 stepping, and hence is slower than `until' with an argument. 3952 3953 `until LOCATION' 3954 `u LOCATION' 3955 Continue running your program until either the specified location 3956 is reached, or the current stack frame returns. LOCATION is any of 3957 the forms described in *Note Specify Location::. This form of the 3958 command uses temporary breakpoints, and hence is quicker than 3959 `until' without an argument. The specified location is actually 3960 reached only if it is in the current frame. This implies that 3961 `until' can be used to skip over recursive function invocations. 3962 For instance in the code below, if the current location is line 3963 `96', issuing `until 99' will execute the program up to line `99' 3964 in the same invocation of factorial, i.e., after the inner 3965 invocations have returned. 3966 3967 94 int factorial (int value) 3968 95 { 3969 96 if (value > 1) { 3970 97 value *= factorial (value - 1); 3971 98 } 3972 99 return (value); 3973 100 } 3974 3975 `advance LOCATION' 3976 Continue running the program up to the given LOCATION. An 3977 argument is required, which should be of one of the forms 3978 described in *Note Specify Location::. Execution will also stop 3979 upon exit from the current stack frame. This command is similar 3980 to `until', but `advance' will not skip over recursive function 3981 calls, and the target location doesn't have to be in the same 3982 frame as the current one. 3983 3984 `stepi' 3985 `stepi ARG' 3986 `si' 3987 Execute one machine instruction, then stop and return to the 3988 debugger. 3989 3990 It is often useful to do `display/i $pc' when stepping by machine 3991 instructions. This makes GDB automatically display the next 3992 instruction to be executed, each time your program stops. *Note 3993 Automatic Display: Auto Display. 3994 3995 An argument is a repeat count, as in `step'. 3996 3997 `nexti' 3998 `nexti ARG' 3999 `ni' 4000 Execute one machine instruction, but if it is a function call, 4001 proceed until the function returns. 4002 4003 An argument is a repeat count, as in `next'. 4004 4005 4006 File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping 4007 4008 5.3 Signals 4009 =========== 4010 4011 A signal is an asynchronous event that can happen in a program. The 4012 operating system defines the possible kinds of signals, and gives each 4013 kind a name and a number. For example, in Unix `SIGINT' is the signal 4014 a program gets when you type an interrupt character (often `Ctrl-c'); 4015 `SIGSEGV' is the signal a program gets from referencing a place in 4016 memory far away from all the areas in use; `SIGALRM' occurs when the 4017 alarm clock timer goes off (which happens only if your program has 4018 requested an alarm). 4019 4020 Some signals, including `SIGALRM', are a normal part of the 4021 functioning of your program. Others, such as `SIGSEGV', indicate 4022 errors; these signals are "fatal" (they kill your program immediately) 4023 if the program has not specified in advance some other way to handle 4024 the signal. `SIGINT' does not indicate an error in your program, but 4025 it is normally fatal so it can carry out the purpose of the interrupt: 4026 to kill the program. 4027 4028 GDB has the ability to detect any occurrence of a signal in your 4029 program. You can tell GDB in advance what to do for each kind of 4030 signal. 4031 4032 Normally, GDB is set up to let the non-erroneous signals like 4033 `SIGALRM' be silently passed to your program (so as not to interfere 4034 with their role in the program's functioning) but to stop your program 4035 immediately whenever an error signal happens. You can change these 4036 settings with the `handle' command. 4037 4038 `info signals' 4039 `info handle' 4040 Print a table of all the kinds of signals and how GDB has been 4041 told to handle each one. You can use this to see the signal 4042 numbers of all the defined types of signals. 4043 4044 `info signals SIG' 4045 Similar, but print information only about the specified signal 4046 number. 4047 4048 `info handle' is an alias for `info signals'. 4049 4050 `handle SIGNAL [KEYWORDS...]' 4051 Change the way GDB handles signal SIGNAL. SIGNAL can be the 4052 number of a signal or its name (with or without the `SIG' at the 4053 beginning); a list of signal numbers of the form `LOW-HIGH'; or 4054 the word `all', meaning all the known signals. Optional arguments 4055 KEYWORDS, described below, say what change to make. 4056 4057 The keywords allowed by the `handle' command can be abbreviated. 4058 Their full names are: 4059 4060 `nostop' 4061 GDB should not stop your program when this signal happens. It may 4062 still print a message telling you that the signal has come in. 4063 4064 `stop' 4065 GDB should stop your program when this signal happens. This 4066 implies the `print' keyword as well. 4067 4068 `print' 4069 GDB should print a message when this signal happens. 4070 4071 `noprint' 4072 GDB should not mention the occurrence of the signal at all. This 4073 implies the `nostop' keyword as well. 4074 4075 `pass' 4076 `noignore' 4077 GDB should allow your program to see this signal; your program can 4078 handle the signal, or else it may terminate if the signal is fatal 4079 and not handled. `pass' and `noignore' are synonyms. 4080 4081 `nopass' 4082 `ignore' 4083 GDB should not allow your program to see this signal. `nopass' 4084 and `ignore' are synonyms. 4085 4086 When a signal stops your program, the signal is not visible to the 4087 program until you continue. Your program sees the signal then, if 4088 `pass' is in effect for the signal in question _at that time_. In 4089 other words, after GDB reports a signal, you can use the `handle' 4090 command with `pass' or `nopass' to control whether your program sees 4091 that signal when you continue. 4092 4093 The default is set to `nostop', `noprint', `pass' for non-erroneous 4094 signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop', 4095 `print', `pass' for the erroneous signals. 4096 4097 You can also use the `signal' command to prevent your program from 4098 seeing a signal, or cause it to see a signal it normally would not see, 4099 or to give it any signal at any time. For example, if your program 4100 stopped due to some sort of memory reference error, you might store 4101 correct values into the erroneous variables and continue, hoping to see 4102 more execution; but your program would probably terminate immediately as 4103 a result of the fatal signal once it saw the signal. To prevent this, 4104 you can continue with `signal 0'. *Note Giving your Program a Signal: 4105 Signaling. 4106 4107 On some targets, GDB can inspect extra signal information associated 4108 with the intercepted signal, before it is actually delivered to the 4109 program being debugged. This information is exported by the 4110 convenience variable `$_siginfo', and consists of data that is passed 4111 by the kernel to the signal handler at the time of the receipt of a 4112 signal. The data type of the information itself is target dependent. 4113 You can see the data type using the `ptype $_siginfo' command. On Unix 4114 systems, it typically corresponds to the standard `siginfo_t' type, as 4115 defined in the `signal.h' system header. 4116 4117 Here's an example, on a GNU/Linux system, printing the stray 4118 referenced address that raised a segmentation fault. 4119 4120 (gdb) continue 4121 Program received signal SIGSEGV, Segmentation fault. 4122 0x0000000000400766 in main () 4123 69 *(int *)p = 0; 4124 (gdb) ptype $_siginfo 4125 type = struct { 4126 int si_signo; 4127 int si_errno; 4128 int si_code; 4129 union { 4130 int _pad[28]; 4131 struct {...} _kill; 4132 struct {...} _timer; 4133 struct {...} _rt; 4134 struct {...} _sigchld; 4135 struct {...} _sigfault; 4136 struct {...} _sigpoll; 4137 } _sifields; 4138 } 4139 (gdb) ptype $_siginfo._sifields._sigfault 4140 type = struct { 4141 void *si_addr; 4142 } 4143 (gdb) p $_siginfo._sifields._sigfault.si_addr 4144 $1 = (void *) 0x7ffff7ff7000 4145 4146 Depending on target support, `$_siginfo' may also be writable. 4147 4148 4149 File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping 4150 4151 5.4 Stopping and Starting Multi-thread Programs 4152 =============================================== 4153 4154 GDB supports debugging programs with multiple threads (*note Debugging 4155 Programs with Multiple Threads: Threads.). There are two modes of 4156 controlling execution of your program within the debugger. In the 4157 default mode, referred to as "all-stop mode", when any thread in your 4158 program stops (for example, at a breakpoint or while being stepped), 4159 all other threads in the program are also stopped by GDB. On some 4160 targets, GDB also supports "non-stop mode", in which other threads can 4161 continue to run freely while you examine the stopped thread in the 4162 debugger. 4163 4164 * Menu: 4165 4166 * All-Stop Mode:: All threads stop when GDB takes control 4167 * Non-Stop Mode:: Other threads continue to execute 4168 * Background Execution:: Running your program asynchronously 4169 * Thread-Specific Breakpoints:: Controlling breakpoints 4170 * Interrupted System Calls:: GDB may interfere with system calls 4171 4172 4173 File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops 4174 4175 5.4.1 All-Stop Mode 4176 ------------------- 4177 4178 In all-stop mode, whenever your program stops under GDB for any reason, 4179 _all_ threads of execution stop, not just the current thread. This 4180 allows you to examine the overall state of the program, including 4181 switching between threads, without worrying that things may change 4182 underfoot. 4183 4184 Conversely, whenever you restart the program, _all_ threads start 4185 executing. _This is true even when single-stepping_ with commands like 4186 `step' or `next'. 4187 4188 In particular, GDB cannot single-step all threads in lockstep. 4189 Since thread scheduling is up to your debugging target's operating 4190 system (not controlled by GDB), other threads may execute more than one 4191 statement while the current thread completes a single step. Moreover, 4192 in general other threads stop in the middle of a statement, rather than 4193 at a clean statement boundary, when the program stops. 4194 4195 You might even find your program stopped in another thread after 4196 continuing or even single-stepping. This happens whenever some other 4197 thread runs into a breakpoint, a signal, or an exception before the 4198 first thread completes whatever you requested. 4199 4200 Whenever GDB stops your program, due to a breakpoint or a signal, it 4201 automatically selects the thread where that breakpoint or signal 4202 happened. GDB alerts you to the context switch with a message such as 4203 `[Switching to Thread N]' to identify the thread. 4204 4205 On some OSes, you can modify GDB's default behavior by locking the 4206 OS scheduler to allow only a single thread to run. 4207 4208 `set scheduler-locking MODE' 4209 Set the scheduler locking mode. If it is `off', then there is no 4210 locking and any thread may run at any time. If `on', then only the 4211 current thread may run when the inferior is resumed. The `step' 4212 mode optimizes for single-stepping; it prevents other threads from 4213 preempting the current thread while you are stepping, so that the 4214 focus of debugging does not change unexpectedly. Other threads 4215 only rarely (or never) get a chance to run when you step. They 4216 are more likely to run when you `next' over a function call, and 4217 they are completely free to run when you use commands like 4218 `continue', `until', or `finish'. However, unless another thread 4219 hits a breakpoint during its timeslice, GDB does not change the 4220 current thread away from the thread that you are debugging. 4221 4222 `show scheduler-locking' 4223 Display the current scheduler locking mode. 4224 4225 By default, when you issue one of the execution commands such as 4226 `continue', `next' or `step', GDB allows only threads of the current 4227 inferior to run. For example, if GDB is attached to two inferiors, 4228 each with two threads, the `continue' command resumes only the two 4229 threads of the current inferior. This is useful, for example, when you 4230 debug a program that forks and you want to hold the parent stopped (so 4231 that, for instance, it doesn't run to exit), while you debug the child. 4232 In other situations, you may not be interested in inspecting the 4233 current state of any of the processes GDB is attached to, and you may 4234 want to resume them all until some breakpoint is hit. In the latter 4235 case, you can instruct GDB to allow all threads of all the inferiors to 4236 run with the `set schedule-multiple' command. 4237 4238 `set schedule-multiple' 4239 Set the mode for allowing threads of multiple processes to be 4240 resumed when an execution command is issued. When `on', all 4241 threads of all processes are allowed to run. When `off', only the 4242 threads of the current process are resumed. The default is `off'. 4243 The `scheduler-locking' mode takes precedence when set to `on', 4244 or while you are stepping and set to `step'. 4245 4246 `show schedule-multiple' 4247 Display the current mode for resuming the execution of threads of 4248 multiple processes. 4249 4250 4251 File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops 4252 4253 5.4.2 Non-Stop Mode 4254 ------------------- 4255 4256 For some multi-threaded targets, GDB supports an optional mode of 4257 operation in which you can examine stopped program threads in the 4258 debugger while other threads continue to execute freely. This 4259 minimizes intrusion when debugging live systems, such as programs where 4260 some threads have real-time constraints or must continue to respond to 4261 external events. This is referred to as "non-stop" mode. 4262 4263 In non-stop mode, when a thread stops to report a debugging event, 4264 _only_ that thread is stopped; GDB does not stop other threads as well, 4265 in contrast to the all-stop mode behavior. Additionally, execution 4266 commands such as `continue' and `step' apply by default only to the 4267 current thread in non-stop mode, rather than all threads as in all-stop 4268 mode. This allows you to control threads explicitly in ways that are 4269 not possible in all-stop mode -- for example, stepping one thread while 4270 allowing others to run freely, stepping one thread while holding all 4271 others stopped, or stepping several threads independently and 4272 simultaneously. 4273 4274 To enter non-stop mode, use this sequence of commands before you run 4275 or attach to your program: 4276 4277 # Enable the async interface. 4278 set target-async 1 4279 4280 # If using the CLI, pagination breaks non-stop. 4281 set pagination off 4282 4283 # Finally, turn it on! 4284 set non-stop on 4285 4286 You can use these commands to manipulate the non-stop mode setting: 4287 4288 `set non-stop on' 4289 Enable selection of non-stop mode. 4290 4291 `set non-stop off' 4292 Disable selection of non-stop mode. 4293 4294 `show non-stop' 4295 Show the current non-stop enablement setting. 4296 4297 Note these commands only reflect whether non-stop mode is enabled, 4298 not whether the currently-executing program is being run in non-stop 4299 mode. In particular, the `set non-stop' preference is only consulted 4300 when GDB starts or connects to the target program, and it is generally 4301 not possible to switch modes once debugging has started. Furthermore, 4302 since not all targets support non-stop mode, even when you have enabled 4303 non-stop mode, GDB may still fall back to all-stop operation by default. 4304 4305 In non-stop mode, all execution commands apply only to the current 4306 thread by default. That is, `continue' only continues one thread. To 4307 continue all threads, issue `continue -a' or `c -a'. 4308 4309 You can use GDB's background execution commands (*note Background 4310 Execution::) to run some threads in the background while you continue 4311 to examine or step others from GDB. The MI execution commands (*note 4312 GDB/MI Program Execution::) are always executed asynchronously in 4313 non-stop mode. 4314 4315 Suspending execution is done with the `interrupt' command when 4316 running in the background, or `Ctrl-c' during foreground execution. In 4317 all-stop mode, this stops the whole process; but in non-stop mode the 4318 interrupt applies only to the current thread. To stop the whole 4319 program, use `interrupt -a'. 4320 4321 Other execution commands do not currently support the `-a' option. 4322 4323 In non-stop mode, when a thread stops, GDB doesn't automatically make 4324 that thread current, as it does in all-stop mode. This is because the 4325 thread stop notifications are asynchronous with respect to GDB's 4326 command interpreter, and it would be confusing if GDB unexpectedly 4327 changed to a different thread just as you entered a command to operate 4328 on the previously current thread. 4329 4330 4331 File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops 4332 4333 5.4.3 Background Execution 4334 -------------------------- 4335 4336 GDB's execution commands have two variants: the normal foreground 4337 (synchronous) behavior, and a background (asynchronous) behavior. In 4338 foreground execution, GDB waits for the program to report that some 4339 thread has stopped before prompting for another command. In background 4340 execution, GDB immediately gives a command prompt so that you can issue 4341 other commands while your program runs. 4342 4343 You need to explicitly enable asynchronous mode before you can use 4344 background execution commands. You can use these commands to 4345 manipulate the asynchronous mode setting: 4346 4347 `set target-async on' 4348 Enable asynchronous mode. 4349 4350 `set target-async off' 4351 Disable asynchronous mode. 4352 4353 `show target-async' 4354 Show the current target-async setting. 4355 4356 If the target doesn't support async mode, GDB issues an error 4357 message if you attempt to use the background execution commands. 4358 4359 To specify background execution, add a `&' to the command. For 4360 example, the background form of the `continue' command is `continue&', 4361 or just `c&'. The execution commands that accept background execution 4362 are: 4363 4364 `run' 4365 *Note Starting your Program: Starting. 4366 4367 `attach' 4368 *Note Debugging an Already-running Process: Attach. 4369 4370 `step' 4371 *Note step: Continuing and Stepping. 4372 4373 `stepi' 4374 *Note stepi: Continuing and Stepping. 4375 4376 `next' 4377 *Note next: Continuing and Stepping. 4378 4379 `nexti' 4380 *Note nexti: Continuing and Stepping. 4381 4382 `continue' 4383 *Note continue: Continuing and Stepping. 4384 4385 `finish' 4386 *Note finish: Continuing and Stepping. 4387 4388 `until' 4389 *Note until: Continuing and Stepping. 4390 4391 4392 Background execution is especially useful in conjunction with 4393 non-stop mode for debugging programs with multiple threads; see *Note 4394 Non-Stop Mode::. However, you can also use these commands in the 4395 normal all-stop mode with the restriction that you cannot issue another 4396 execution command until the previous one finishes. Examples of 4397 commands that are valid in all-stop mode while the program is running 4398 include `help' and `info break'. 4399 4400 You can interrupt your program while it is running in the background 4401 by using the `interrupt' command. 4402 4403 `interrupt' 4404 `interrupt -a' 4405 Suspend execution of the running program. In all-stop mode, 4406 `interrupt' stops the whole process, but in non-stop mode, it stops 4407 only the current thread. To stop the whole program in non-stop 4408 mode, use `interrupt -a'. 4409 4410 4411 File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops 4412 4413 5.4.4 Thread-Specific Breakpoints 4414 --------------------------------- 4415 4416 When your program has multiple threads (*note Debugging Programs with 4417 Multiple Threads: Threads.), you can choose whether to set breakpoints 4418 on all threads, or on a particular thread. 4419 4420 `break LINESPEC thread THREADNO' 4421 `break LINESPEC thread THREADNO if ...' 4422 LINESPEC specifies source lines; there are several ways of writing 4423 them (*note Specify Location::), but the effect is always to 4424 specify some source line. 4425 4426 Use the qualifier `thread THREADNO' with a breakpoint command to 4427 specify that you only want GDB to stop the program when a 4428 particular thread reaches this breakpoint. THREADNO is one of the 4429 numeric thread identifiers assigned by GDB, shown in the first 4430 column of the `info threads' display. 4431 4432 If you do not specify `thread THREADNO' when you set a breakpoint, 4433 the breakpoint applies to _all_ threads of your program. 4434 4435 You can use the `thread' qualifier on conditional breakpoints as 4436 well; in this case, place `thread THREADNO' before or after the 4437 breakpoint condition, like this: 4438 4439 (gdb) break frik.c:13 thread 28 if bartab > lim 4440 4441 4442 4443 File: gdb.info, Node: Interrupted System Calls, Prev: Thread-Specific Breakpoints, Up: Thread Stops 4444 4445 5.4.5 Interrupted System Calls 4446 ------------------------------ 4447 4448 There is an unfortunate side effect when using GDB to debug 4449 multi-threaded programs. If one thread stops for a breakpoint, or for 4450 some other reason, and another thread is blocked in a system call, then 4451 the system call may return prematurely. This is a consequence of the 4452 interaction between multiple threads and the signals that GDB uses to 4453 implement breakpoints and other events that stop execution. 4454 4455 To handle this problem, your program should check the return value of 4456 each system call and react appropriately. This is good programming 4457 style anyways. 4458 4459 For example, do not write code like this: 4460 4461 sleep (10); 4462 4463 The call to `sleep' will return early if a different thread stops at 4464 a breakpoint or for some other reason. 4465 4466 Instead, write this: 4467 4468 int unslept = 10; 4469 while (unslept > 0) 4470 unslept = sleep (unslept); 4471 4472 A system call is allowed to return early, so the system is still 4473 conforming to its specification. But GDB does cause your 4474 multi-threaded program to behave differently than it would without GDB. 4475 4476 Also, GDB uses internal breakpoints in the thread library to monitor 4477 certain events such as thread creation and thread destruction. When 4478 such an event happens, a system call in another thread may return 4479 prematurely, even though your program does not appear to stop. 4480 4481 4482 File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top 4483 4484 6 Running programs backward 4485 *************************** 4486 4487 When you are debugging a program, it is not unusual to realize that you 4488 have gone too far, and some event of interest has already happened. If 4489 the target environment supports it, GDB can allow you to "rewind" the 4490 program by running it backward. 4491 4492 A target environment that supports reverse execution should be able 4493 to "undo" the changes in machine state that have taken place as the 4494 program was executing normally. Variables, registers etc. should 4495 revert to their previous values. Obviously this requires a great deal 4496 of sophistication on the part of the target environment; not all target 4497 environments can support reverse execution. 4498 4499 When a program is executed in reverse, the instructions that have 4500 most recently been executed are "un-executed", in reverse order. The 4501 program counter runs backward, following the previous thread of 4502 execution in reverse. As each instruction is "un-executed", the values 4503 of memory and/or registers that were changed by that instruction are 4504 reverted to their previous states. After executing a piece of source 4505 code in reverse, all side effects of that code should be "undone", and 4506 all variables should be returned to their prior values(1). 4507 4508 If you are debugging in a target environment that supports reverse 4509 execution, GDB provides the following commands. 4510 4511 `reverse-continue [IGNORE-COUNT]' 4512 `rc [IGNORE-COUNT]' 4513 Beginning at the point where your program last stopped, start 4514 executing in reverse. Reverse execution will stop for breakpoints 4515 and synchronous exceptions (signals), just like normal execution. 4516 Behavior of asynchronous signals depends on the target environment. 4517 4518 `reverse-step [COUNT]' 4519 Run the program backward until control reaches the start of a 4520 different source line; then stop it, and return control to GDB. 4521 4522 Like the `step' command, `reverse-step' will only stop at the 4523 beginning of a source line. It "un-executes" the previously 4524 executed source line. If the previous source line included calls 4525 to debuggable functions, `reverse-step' will step (backward) into 4526 the called function, stopping at the beginning of the _last_ 4527 statement in the called function (typically a return statement). 4528 4529 Also, as with the `step' command, if non-debuggable functions are 4530 called, `reverse-step' will run thru them backward without 4531 stopping. 4532 4533 `reverse-stepi [COUNT]' 4534 Reverse-execute one machine instruction. Note that the instruction 4535 to be reverse-executed is _not_ the one pointed to by the program 4536 counter, but the instruction executed prior to that one. For 4537 instance, if the last instruction was a jump, `reverse-stepi' will 4538 take you back from the destination of the jump to the jump 4539 instruction itself. 4540 4541 `reverse-next [COUNT]' 4542 Run backward to the beginning of the previous line executed in the 4543 current (innermost) stack frame. If the line contains function 4544 calls, they will be "un-executed" without stopping. Starting from 4545 the first line of a function, `reverse-next' will take you back to 4546 the caller of that function, _before_ the function was called, 4547 just as the normal `next' command would take you from the last 4548 line of a function back to its return to its caller (2). 4549 4550 `reverse-nexti [COUNT]' 4551 Like `nexti', `reverse-nexti' executes a single instruction in 4552 reverse, except that called functions are "un-executed" atomically. 4553 That is, if the previously executed instruction was a return from 4554 another function, `reverse-nexti' will continue to execute in 4555 reverse until the call to that function (from the current stack 4556 frame) is reached. 4557 4558 `reverse-finish' 4559 Just as the `finish' command takes you to the point where the 4560 current function returns, `reverse-finish' takes you to the point 4561 where it was called. Instead of ending up at the end of the 4562 current function invocation, you end up at the beginning. 4563 4564 `set exec-direction' 4565 Set the direction of target execution. 4566 4567 `set exec-direction reverse' 4568 GDB will perform all execution commands in reverse, until the 4569 exec-direction mode is changed to "forward". Affected commands 4570 include `step, stepi, next, nexti, continue, and finish'. The 4571 `return' command cannot be used in reverse mode. 4572 4573 `set exec-direction forward' 4574 GDB will perform all execution commands in the normal fashion. 4575 This is the default. 4576 4577 ---------- Footnotes ---------- 4578 4579 (1) Note that some side effects are easier to undo than others. For 4580 instance, memory and registers are relatively easy, but device I/O is 4581 hard. Some targets may be able undo things like device I/O, and some 4582 may not. 4583 4584 The contract between GDB and the reverse executing target requires 4585 only that the target do something reasonable when GDB tells it to 4586 execute backwards, and then report the results back to GDB. Whatever 4587 the target reports back to GDB, GDB will report back to the user. GDB 4588 assumes that the memory and registers that the target reports are in a 4589 consistant state, but GDB accepts whatever it is given. 4590 4591 (2) Unless the code is too heavily optimized. 4592 4593 4594 File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top 4595 4596 7 Recording Inferior's Execution and Replaying It 4597 ************************************************* 4598 4599 On some platforms, GDB provides a special "process record and replay" 4600 target that can record a log of the process execution, and replay it 4601 later with both forward and reverse execution commands. 4602 4603 When this target is in use, if the execution log includes the record 4604 for the next instruction, GDB will debug in "replay mode". In the 4605 replay mode, the inferior does not really execute code instructions. 4606 Instead, all the events that normally happen during code execution are 4607 taken from the execution log. While code is not really executed in 4608 replay mode, the values of registers (including the program counter 4609 register) and the memory of the inferior are still changed as they 4610 normally would. Their contents are taken from the execution log. 4611 4612 If the record for the next instruction is not in the execution log, 4613 GDB will debug in "record mode". In this mode, the inferior executes 4614 normally, and GDB records the execution log for future replay. 4615 4616 The process record and replay target supports reverse execution 4617 (*note Reverse Execution::), even if the platform on which the inferior 4618 runs does not. However, the reverse execution is limited in this case 4619 by the range of the instructions recorded in the execution log. In 4620 other words, reverse execution on platforms that don't support it 4621 directly can only be done in the replay mode. 4622 4623 When debugging in the reverse direction, GDB will work in replay 4624 mode as long as the execution log includes the record for the previous 4625 instruction; otherwise, it will work in record mode, if the platform 4626 supports reverse execution, or stop if not. 4627 4628 For architecture environments that support process record and replay, 4629 GDB provides the following commands: 4630 4631 `target record' 4632 This command starts the process record and replay target. The 4633 process record and replay target can only debug a process that is 4634 already running. Therefore, you need first to start the process 4635 with the `run' or `start' commands, and then start the recording 4636 with the `target record' command. 4637 4638 Both `record' and `rec' are aliases of `target record'. 4639 4640 Displaced stepping (*note displaced stepping: Maintenance 4641 Commands.) will be automatically disabled when process record and 4642 replay target is started. That's because the process record and 4643 replay target doesn't support displaced stepping. 4644 4645 If the inferior is in the non-stop mode (*note Non-Stop Mode::) or 4646 in the asynchronous execution mode (*note Background Execution::), 4647 the process record and replay target cannot be started because it 4648 doesn't support these two modes. 4649 4650 `record stop' 4651 Stop the process record and replay target. When process record and 4652 replay target stops, the entire execution log will be deleted and 4653 the inferior will either be terminated, or will remain in its 4654 final state. 4655 4656 When you stop the process record and replay target in record mode 4657 (at the end of the execution log), the inferior will be stopped at 4658 the next instruction that would have been recorded. In other 4659 words, if you record for a while and then stop recording, the 4660 inferior process will be left in the same state as if the 4661 recording never happened. 4662 4663 On the other hand, if the process record and replay target is 4664 stopped while in replay mode (that is, not at the end of the 4665 execution log, but at some earlier point), the inferior process 4666 will become "live" at that earlier state, and it will then be 4667 possible to continue the usual "live" debugging of the process 4668 from that state. 4669 4670 When the inferior process exits, or GDB detaches from it, process 4671 record and replay target will automatically stop itself. 4672 4673 `set record insn-number-max LIMIT' 4674 Set the limit of instructions to be recorded. Default value is 4675 200000. 4676 4677 If LIMIT is a positive number, then GDB will start deleting 4678 instructions from the log once the number of the record 4679 instructions becomes greater than LIMIT. For every new recorded 4680 instruction, GDB will delete the earliest recorded instruction to 4681 keep the number of recorded instructions at the limit. (Since 4682 deleting recorded instructions loses information, GDB lets you 4683 control what happens when the limit is reached, by means of the 4684 `stop-at-limit' option, described below.) 4685 4686 If LIMIT is zero, GDB will never delete recorded instructions from 4687 the execution log. The number of recorded instructions is 4688 unlimited in this case. 4689 4690 `show record insn-number-max' 4691 Show the limit of instructions to be recorded. 4692 4693 `set record stop-at-limit' 4694 Control the behavior when the number of recorded instructions 4695 reaches the limit. If ON (the default), GDB will stop when the 4696 limit is reached for the first time and ask you whether you want 4697 to stop the inferior or continue running it and recording the 4698 execution log. If you decide to continue recording, each new 4699 recorded instruction will cause the oldest one to be deleted. 4700 4701 If this option is OFF, GDB will automatically delete the oldest 4702 record to make room for each new one, without asking. 4703 4704 `show record stop-at-limit' 4705 Show the current setting of `stop-at-limit'. 4706 4707 `info record' 4708 Show various statistics about the state of process record and its 4709 in-memory execution log buffer, including: 4710 4711 * Whether in record mode or replay mode. 4712 4713 * Lowest recorded instruction number (counting from when the 4714 current execution log started recording instructions). 4715 4716 * Highest recorded instruction number. 4717 4718 * Current instruction about to be replayed (if in replay mode). 4719 4720 * Number of instructions contained in the execution log. 4721 4722 * Maximum number of instructions that may be contained in the 4723 execution log. 4724 4725 `record delete' 4726 When record target runs in replay mode ("in the past"), delete the 4727 subsequent execution log and begin to record a new execution log 4728 starting from the current address. This means you will abandon 4729 the previously recorded "future" and begin recording a new 4730 "future". 4731 4732 4733 File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top 4734 4735 8 Examining the Stack 4736 ********************* 4737 4738 When your program has stopped, the first thing you need to know is 4739 where it stopped and how it got there. 4740 4741 Each time your program performs a function call, information about 4742 the call is generated. That information includes the location of the 4743 call in your program, the arguments of the call, and the local 4744 variables of the function being called. The information is saved in a 4745 block of data called a "stack frame". The stack frames are allocated 4746 in a region of memory called the "call stack". 4747 4748 When your program stops, the GDB commands for examining the stack 4749 allow you to see all of this information. 4750 4751 One of the stack frames is "selected" by GDB and many GDB commands 4752 refer implicitly to the selected frame. In particular, whenever you 4753 ask GDB for the value of a variable in your program, the value is found 4754 in the selected frame. There are special GDB commands to select 4755 whichever frame you are interested in. *Note Selecting a Frame: 4756 Selection. 4757 4758 When your program stops, GDB automatically selects the currently 4759 executing frame and describes it briefly, similar to the `frame' 4760 command (*note Information about a Frame: Frame Info.). 4761 4762 * Menu: 4763 4764 * Frames:: Stack frames 4765 * Backtrace:: Backtraces 4766 * Selection:: Selecting a frame 4767 * Frame Info:: Information on a frame 4768 4769 4770 File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack 4771 4772 8.1 Stack Frames 4773 ================ 4774 4775 The call stack is divided up into contiguous pieces called "stack 4776 frames", or "frames" for short; each frame is the data associated with 4777 one call to one function. The frame contains the arguments given to 4778 the function, the function's local variables, and the address at which 4779 the function is executing. 4780 4781 When your program is started, the stack has only one frame, that of 4782 the function `main'. This is called the "initial" frame or the 4783 "outermost" frame. Each time a function is called, a new frame is 4784 made. Each time a function returns, the frame for that function 4785 invocation is eliminated. If a function is recursive, there can be 4786 many frames for the same function. The frame for the function in which 4787 execution is actually occurring is called the "innermost" frame. This 4788 is the most recently created of all the stack frames that still exist. 4789 4790 Inside your program, stack frames are identified by their addresses. 4791 A stack frame consists of many bytes, each of which has its own 4792 address; each kind of computer has a convention for choosing one byte 4793 whose address serves as the address of the frame. Usually this address 4794 is kept in a register called the "frame pointer register" (*note $fp: 4795 Registers.) while execution is going on in that frame. 4796 4797 GDB assigns numbers to all existing stack frames, starting with zero 4798 for the innermost frame, one for the frame that called it, and so on 4799 upward. These numbers do not really exist in your program; they are 4800 assigned by GDB to give you a way of designating stack frames in GDB 4801 commands. 4802 4803 Some compilers provide a way to compile functions so that they 4804 operate without stack frames. (For example, the GCC option 4805 `-fomit-frame-pointer' 4806 generates functions without a frame.) This is occasionally done 4807 with heavily used library functions to save the frame setup time. GDB 4808 has limited facilities for dealing with these function invocations. If 4809 the innermost function invocation has no stack frame, GDB nevertheless 4810 regards it as though it had a separate frame, which is numbered zero as 4811 usual, allowing correct tracing of the function call chain. However, 4812 GDB has no provision for frameless functions elsewhere in the stack. 4813 4814 `frame ARGS' 4815 The `frame' command allows you to move from one stack frame to 4816 another, and to print the stack frame you select. ARGS may be 4817 either the address of the frame or the stack frame number. 4818 Without an argument, `frame' prints the current stack frame. 4819 4820 `select-frame' 4821 The `select-frame' command allows you to move from one stack frame 4822 to another without printing the frame. This is the silent version 4823 of `frame'. 4824 4825 4826 File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack 4827 4828 8.2 Backtraces 4829 ============== 4830 4831 A backtrace is a summary of how your program got where it is. It shows 4832 one line per frame, for many frames, starting with the currently 4833 executing frame (frame zero), followed by its caller (frame one), and 4834 on up the stack. 4835 4836 `backtrace' 4837 `bt' 4838 Print a backtrace of the entire stack: one line per frame for all 4839 frames in the stack. 4840 4841 You can stop the backtrace at any time by typing the system 4842 interrupt character, normally `Ctrl-c'. 4843 4844 `backtrace N' 4845 `bt N' 4846 Similar, but print only the innermost N frames. 4847 4848 `backtrace -N' 4849 `bt -N' 4850 Similar, but print only the outermost N frames. 4851 4852 `backtrace full' 4853 `bt full' 4854 `bt full N' 4855 `bt full -N' 4856 Print the values of the local variables also. N specifies the 4857 number of frames to print, as described above. 4858 4859 The names `where' and `info stack' (abbreviated `info s') are 4860 additional aliases for `backtrace'. 4861 4862 In a multi-threaded program, GDB by default shows the backtrace only 4863 for the current thread. To display the backtrace for several or all of 4864 the threads, use the command `thread apply' (*note thread apply: 4865 Threads.). For example, if you type `thread apply all backtrace', GDB 4866 will display the backtrace for all the threads; this is handy when you 4867 debug a core dump of a multi-threaded program. 4868 4869 Each line in the backtrace shows the frame number and the function 4870 name. The program counter value is also shown--unless you use `set 4871 print address off'. The backtrace also shows the source file name and 4872 line number, as well as the arguments to the function. The program 4873 counter value is omitted if it is at the beginning of the code for that 4874 line number. 4875 4876 Here is an example of a backtrace. It was made with the command `bt 4877 3', so it shows the innermost three frames. 4878 4879 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 4880 at builtin.c:993 4881 #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 4882 #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 4883 at macro.c:71 4884 (More stack frames follow...) 4885 4886 The display for frame zero does not begin with a program counter value, 4887 indicating that your program has stopped at the beginning of the code 4888 for line `993' of `builtin.c'. 4889 4890 The value of parameter `data' in frame 1 has been replaced by `...'. 4891 By default, GDB prints the value of a parameter only if it is a scalar 4892 (integer, pointer, enumeration, etc). See command `set print 4893 frame-arguments' in *Note Print Settings:: for more details on how to 4894 configure the way function parameter values are printed. 4895 4896 If your program was compiled with optimizations, some compilers will 4897 optimize away arguments passed to functions if those arguments are 4898 never used after the call. Such optimizations generate code that 4899 passes arguments through registers, but doesn't store those arguments 4900 in the stack frame. GDB has no way of displaying such arguments in 4901 stack frames other than the innermost one. Here's what such a 4902 backtrace might look like: 4903 4904 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 4905 at builtin.c:993 4906 #1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242 4907 #2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08) 4908 at macro.c:71 4909 (More stack frames follow...) 4910 4911 The values of arguments that were not saved in their stack frames are 4912 shown as `<value optimized out>'. 4913 4914 If you need to display the values of such optimized-out arguments, 4915 either deduce that from other variables whose values depend on the one 4916 you are interested in, or recompile without optimizations. 4917 4918 Most programs have a standard user entry point--a place where system 4919 libraries and startup code transition into user code. For C this is 4920 `main'(1). When GDB finds the entry function in a backtrace it will 4921 terminate the backtrace, to avoid tracing into highly system-specific 4922 (and generally uninteresting) code. 4923 4924 If you need to examine the startup code, or limit the number of 4925 levels in a backtrace, you can change this behavior: 4926 4927 `set backtrace past-main' 4928 `set backtrace past-main on' 4929 Backtraces will continue past the user entry point. 4930 4931 `set backtrace past-main off' 4932 Backtraces will stop when they encounter the user entry point. 4933 This is the default. 4934 4935 `show backtrace past-main' 4936 Display the current user entry point backtrace policy. 4937 4938 `set backtrace past-entry' 4939 `set backtrace past-entry on' 4940 Backtraces will continue past the internal entry point of an 4941 application. This entry point is encoded by the linker when the 4942 application is built, and is likely before the user entry point 4943 `main' (or equivalent) is called. 4944 4945 `set backtrace past-entry off' 4946 Backtraces will stop when they encounter the internal entry point 4947 of an application. This is the default. 4948 4949 `show backtrace past-entry' 4950 Display the current internal entry point backtrace policy. 4951 4952 `set backtrace limit N' 4953 `set backtrace limit 0' 4954 Limit the backtrace to N levels. A value of zero means unlimited. 4955 4956 `show backtrace limit' 4957 Display the current limit on backtrace levels. 4958 4959 ---------- Footnotes ---------- 4960 4961 (1) Note that embedded programs (the so-called "free-standing" 4962 environment) are not required to have a `main' function as the entry 4963 point. They could even have multiple entry points. 4964 4965 4966 File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack 4967 4968 8.3 Selecting a Frame 4969 ===================== 4970 4971 Most commands for examining the stack and other data in your program 4972 work on whichever stack frame is selected at the moment. Here are the 4973 commands for selecting a stack frame; all of them finish by printing a 4974 brief description of the stack frame just selected. 4975 4976 `frame N' 4977 `f N' 4978 Select frame number N. Recall that frame zero is the innermost 4979 (currently executing) frame, frame one is the frame that called the 4980 innermost one, and so on. The highest-numbered frame is the one 4981 for `main'. 4982 4983 `frame ADDR' 4984 `f ADDR' 4985 Select the frame at address ADDR. This is useful mainly if the 4986 chaining of stack frames has been damaged by a bug, making it 4987 impossible for GDB to assign numbers properly to all frames. In 4988 addition, this can be useful when your program has multiple stacks 4989 and switches between them. 4990 4991 On the SPARC architecture, `frame' needs two addresses to select 4992 an arbitrary frame: a frame pointer and a stack pointer. 4993 4994 On the MIPS and Alpha architecture, it needs two addresses: a stack 4995 pointer and a program counter. 4996 4997 On the 29k architecture, it needs three addresses: a register stack 4998 pointer, a program counter, and a memory stack pointer. 4999 5000 `up N' 5001 Move N frames up the stack. For positive numbers N, this advances 5002 toward the outermost frame, to higher frame numbers, to frames 5003 that have existed longer. N defaults to one. 5004 5005 `down N' 5006 Move N frames down the stack. For positive numbers N, this 5007 advances toward the innermost frame, to lower frame numbers, to 5008 frames that were created more recently. N defaults to one. You 5009 may abbreviate `down' as `do'. 5010 5011 All of these commands end by printing two lines of output describing 5012 the frame. The first line shows the frame number, the function name, 5013 the arguments, and the source file and line number of execution in that 5014 frame. The second line shows the text of that source line. 5015 5016 For example: 5017 5018 (gdb) up 5019 #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) 5020 at env.c:10 5021 10 read_input_file (argv[i]); 5022 5023 After such a printout, the `list' command with no arguments prints 5024 ten lines centered on the point of execution in the frame. You can 5025 also edit the program at the point of execution with your favorite 5026 editing program by typing `edit'. *Note Printing Source Lines: List, 5027 for details. 5028 5029 `up-silently N' 5030 `down-silently N' 5031 These two commands are variants of `up' and `down', respectively; 5032 they differ in that they do their work silently, without causing 5033 display of the new frame. They are intended primarily for use in 5034 GDB command scripts, where the output might be unnecessary and 5035 distracting. 5036 5037 5038 File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack 5039 5040 8.4 Information About a Frame 5041 ============================= 5042 5043 There are several other commands to print information about the selected 5044 stack frame. 5045 5046 `frame' 5047 `f' 5048 When used without any argument, this command does not change which 5049 frame is selected, but prints a brief description of the currently 5050 selected stack frame. It can be abbreviated `f'. With an 5051 argument, this command is used to select a stack frame. *Note 5052 Selecting a Frame: Selection. 5053 5054 `info frame' 5055 `info f' 5056 This command prints a verbose description of the selected stack 5057 frame, including: 5058 5059 * the address of the frame 5060 5061 * the address of the next frame down (called by this frame) 5062 5063 * the address of the next frame up (caller of this frame) 5064 5065 * the language in which the source code corresponding to this 5066 frame is written 5067 5068 * the address of the frame's arguments 5069 5070 * the address of the frame's local variables 5071 5072 * the program counter saved in it (the address of execution in 5073 the caller frame) 5074 5075 * which registers were saved in the frame 5076 5077 The verbose description is useful when something has gone wrong 5078 that has made the stack format fail to fit the usual conventions. 5079 5080 `info frame ADDR' 5081 `info f ADDR' 5082 Print a verbose description of the frame at address ADDR, without 5083 selecting that frame. The selected frame remains unchanged by this 5084 command. This requires the same kind of address (more than one 5085 for some architectures) that you specify in the `frame' command. 5086 *Note Selecting a Frame: Selection. 5087 5088 `info args' 5089 Print the arguments of the selected frame, each on a separate line. 5090 5091 `info locals' 5092 Print the local variables of the selected frame, each on a separate 5093 line. These are all variables (declared either static or 5094 automatic) accessible at the point of execution of the selected 5095 frame. 5096 5097 `info catch' 5098 Print a list of all the exception handlers that are active in the 5099 current stack frame at the current point of execution. To see 5100 other exception handlers, visit the associated frame (using the 5101 `up', `down', or `frame' commands); then type `info catch'. *Note 5102 Setting Catchpoints: Set Catchpoints. 5103 5104 5105 5106 File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top 5107 5108 9 Examining Source Files 5109 ************************ 5110 5111 GDB can print parts of your program's source, since the debugging 5112 information recorded in the program tells GDB what source files were 5113 used to build it. When your program stops, GDB spontaneously prints 5114 the line where it stopped. Likewise, when you select a stack frame 5115 (*note Selecting a Frame: Selection.), GDB prints the line where 5116 execution in that frame has stopped. You can print other portions of 5117 source files by explicit command. 5118 5119 If you use GDB through its GNU Emacs interface, you may prefer to 5120 use Emacs facilities to view source; see *Note Using GDB under GNU 5121 Emacs: Emacs. 5122 5123 * Menu: 5124 5125 * List:: Printing source lines 5126 * Specify Location:: How to specify code locations 5127 * Edit:: Editing source files 5128 * Search:: Searching source files 5129 * Source Path:: Specifying source directories 5130 * Machine Code:: Source and machine code 5131 5132 5133 File: gdb.info, Node: List, Next: Specify Location, Up: Source 5134 5135 9.1 Printing Source Lines 5136 ========================= 5137 5138 To print lines from a source file, use the `list' command (abbreviated 5139 `l'). By default, ten lines are printed. There are several ways to 5140 specify what part of the file you want to print; see *Note Specify 5141 Location::, for the full list. 5142 5143 Here are the forms of the `list' command most commonly used: 5144 5145 `list LINENUM' 5146 Print lines centered around line number LINENUM in the current 5147 source file. 5148 5149 `list FUNCTION' 5150 Print lines centered around the beginning of function FUNCTION. 5151 5152 `list' 5153 Print more lines. If the last lines printed were printed with a 5154 `list' command, this prints lines following the last lines 5155 printed; however, if the last line printed was a solitary line 5156 printed as part of displaying a stack frame (*note Examining the 5157 Stack: Stack.), this prints lines centered around that line. 5158 5159 `list -' 5160 Print lines just before the lines last printed. 5161 5162 By default, GDB prints ten source lines with any of these forms of 5163 the `list' command. You can change this using `set listsize': 5164 5165 `set listsize COUNT' 5166 Make the `list' command display COUNT source lines (unless the 5167 `list' argument explicitly specifies some other number). 5168 5169 `show listsize' 5170 Display the number of lines that `list' prints. 5171 5172 Repeating a `list' command with <RET> discards the argument, so it 5173 is equivalent to typing just `list'. This is more useful than listing 5174 the same lines again. An exception is made for an argument of `-'; 5175 that argument is preserved in repetition so that each repetition moves 5176 up in the source file. 5177 5178 In general, the `list' command expects you to supply zero, one or two 5179 "linespecs". Linespecs specify source lines; there are several ways of 5180 writing them (*note Specify Location::), but the effect is always to 5181 specify some source line. 5182 5183 Here is a complete description of the possible arguments for `list': 5184 5185 `list LINESPEC' 5186 Print lines centered around the line specified by LINESPEC. 5187 5188 `list FIRST,LAST' 5189 Print lines from FIRST to LAST. Both arguments are linespecs. 5190 When a `list' command has two linespecs, and the source file of 5191 the second linespec is omitted, this refers to the same source 5192 file as the first linespec. 5193 5194 `list ,LAST' 5195 Print lines ending with LAST. 5196 5197 `list FIRST,' 5198 Print lines starting with FIRST. 5199 5200 `list +' 5201 Print lines just after the lines last printed. 5202 5203 `list -' 5204 Print lines just before the lines last printed. 5205 5206 `list' 5207 As described in the preceding table. 5208 5209 5210 File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source 5211 5212 9.2 Specifying a Location 5213 ========================= 5214 5215 Several GDB commands accept arguments that specify a location of your 5216 program's code. Since GDB is a source-level debugger, a location 5217 usually specifies some line in the source code; for that reason, 5218 locations are also known as "linespecs". 5219 5220 Here are all the different ways of specifying a code location that 5221 GDB understands: 5222 5223 `LINENUM' 5224 Specifies the line number LINENUM of the current source file. 5225 5226 `-OFFSET' 5227 `+OFFSET' 5228 Specifies the line OFFSET lines before or after the "current 5229 line". For the `list' command, the current line is the last one 5230 printed; for the breakpoint commands, this is the line at which 5231 execution stopped in the currently selected "stack frame" (*note 5232 Frames: Frames, for a description of stack frames.) When used as 5233 the second of the two linespecs in a `list' command, this 5234 specifies the line OFFSET lines up or down from the first linespec. 5235 5236 `FILENAME:LINENUM' 5237 Specifies the line LINENUM in the source file FILENAME. 5238 5239 `FUNCTION' 5240 Specifies the line that begins the body of the function FUNCTION. 5241 For example, in C, this is the line with the open brace. 5242 5243 `FILENAME:FUNCTION' 5244 Specifies the line that begins the body of the function FUNCTION 5245 in the file FILENAME. You only need the file name with a function 5246 name to avoid ambiguity when there are identically named functions 5247 in different source files. 5248 5249 `*ADDRESS' 5250 Specifies the program address ADDRESS. For line-oriented 5251 commands, such as `list' and `edit', this specifies a source line 5252 that contains ADDRESS. For `break' and other breakpoint oriented 5253 commands, this can be used to set breakpoints in parts of your 5254 program which do not have debugging information or source files. 5255 5256 Here ADDRESS may be any expression valid in the current working 5257 language (*note working language: Languages.) that specifies a code 5258 address. In addition, as a convenience, GDB extends the semantics 5259 of expressions used in locations to cover the situations that 5260 frequently happen during debugging. Here are the various forms of 5261 ADDRESS: 5262 5263 `EXPRESSION' 5264 Any expression valid in the current working language. 5265 5266 `FUNCADDR' 5267 An address of a function or procedure derived from its name. 5268 In C, C++, Java, Objective-C, Fortran, minimal, and assembly, 5269 this is simply the function's name FUNCTION (and actually a 5270 special case of a valid expression). In Pascal and Modula-2, 5271 this is `&FUNCTION'. In Ada, this is `FUNCTION'Address' 5272 (although the Pascal form also works). 5273 5274 This form specifies the address of the function's first 5275 instruction, before the stack frame and arguments have been 5276 set up. 5277 5278 `'FILENAME'::FUNCADDR' 5279 Like FUNCADDR above, but also specifies the name of the source 5280 file explicitly. This is useful if the name of the function 5281 does not specify the function unambiguously, e.g., if there 5282 are several functions with identical names in different 5283 source files. 5284 5285 5286 5287 File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source 5288 5289 9.3 Editing Source Files 5290 ======================== 5291 5292 To edit the lines in a source file, use the `edit' command. The 5293 editing program of your choice is invoked with the current line set to 5294 the active line in the program. Alternatively, there are several ways 5295 to specify what part of the file you want to print if you want to see 5296 other parts of the program: 5297 5298 `edit LOCATION' 5299 Edit the source file specified by `location'. Editing starts at 5300 that LOCATION, e.g., at the specified source line of the specified 5301 file. *Note Specify Location::, for all the possible forms of the 5302 LOCATION argument; here are the forms of the `edit' command most 5303 commonly used: 5304 5305 `edit NUMBER' 5306 Edit the current source file with NUMBER as the active line 5307 number. 5308 5309 `edit FUNCTION' 5310 Edit the file containing FUNCTION at the beginning of its 5311 definition. 5312 5313 5314 9.3.1 Choosing your Editor 5315 -------------------------- 5316 5317 You can customize GDB to use any editor you want (1). By default, it 5318 is `/bin/ex', but you can change this by setting the environment 5319 variable `EDITOR' before using GDB. For example, to configure GDB to 5320 use the `vi' editor, you could use these commands with the `sh' shell: 5321 EDITOR=/usr/bin/vi 5322 export EDITOR 5323 gdb ... 5324 or in the `csh' shell, 5325 setenv EDITOR /usr/bin/vi 5326 gdb ... 5327 5328 ---------- Footnotes ---------- 5329 5330 (1) The only restriction is that your editor (say `ex'), recognizes 5331 the following command-line syntax: 5332 ex +NUMBER file 5333 The optional numeric value +NUMBER specifies the number of the line 5334 in the file where to start editing. 5335 5336 5337 File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source 5338 5339 9.4 Searching Source Files 5340 ========================== 5341 5342 There are two commands for searching through the current source file 5343 for a regular expression. 5344 5345 `forward-search REGEXP' 5346 `search REGEXP' 5347 The command `forward-search REGEXP' checks each line, starting 5348 with the one following the last line listed, for a match for 5349 REGEXP. It lists the line that is found. You can use the synonym 5350 `search REGEXP' or abbreviate the command name as `fo'. 5351 5352 `reverse-search REGEXP' 5353 The command `reverse-search REGEXP' checks each line, starting 5354 with the one before the last line listed and going backward, for a 5355 match for REGEXP. It lists the line that is found. You can 5356 abbreviate this command as `rev'. 5357 5358 5359 File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source 5360 5361 9.5 Specifying Source Directories 5362 ================================= 5363 5364 Executable programs sometimes do not record the directories of the 5365 source files from which they were compiled, just the names. Even when 5366 they do, the directories could be moved between the compilation and 5367 your debugging session. GDB has a list of directories to search for 5368 source files; this is called the "source path". Each time GDB wants a 5369 source file, it tries all the directories in the list, in the order 5370 they are present in the list, until it finds a file with the desired 5371 name. 5372 5373 For example, suppose an executable references the file 5374 `/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The 5375 file is first looked up literally; if this fails, 5376 `/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails, 5377 `/mnt/cross/foo.c' is opened; if this fails, an error message is 5378 printed. GDB does not look up the parts of the source file name, such 5379 as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of 5380 the source path are not searched: if the source path is `/mnt/cross', 5381 and the binary refers to `foo.c', GDB would not find it under 5382 `/mnt/cross/usr/src/foo-1.0/lib'. 5383 5384 Plain file names, relative file names with leading directories, file 5385 names containing dots, etc. are all treated as described above; for 5386 instance, if the source path is `/mnt/cross', and the source file is 5387 recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then 5388 `/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'. 5389 5390 Note that the executable search path is _not_ used to locate the 5391 source files. 5392 5393 Whenever you reset or rearrange the source path, GDB clears out any 5394 information it has cached about where source files are found and where 5395 each line is in the file. 5396 5397 When you start GDB, its source path includes only `cdir' and `cwd', 5398 in that order. To add other directories, use the `directory' command. 5399 5400 The search path is used to find both program source files and GDB 5401 script files (read using the `-command' option and `source' command). 5402 5403 In addition to the source path, GDB provides a set of commands that 5404 manage a list of source path substitution rules. A "substitution rule" 5405 specifies how to rewrite source directories stored in the program's 5406 debug information in case the sources were moved to a different 5407 directory between compilation and debugging. A rule is made of two 5408 strings, the first specifying what needs to be rewritten in the path, 5409 and the second specifying how it should be rewritten. In *Note set 5410 substitute-path::, we name these two parts FROM and TO respectively. 5411 GDB does a simple string replacement of FROM with TO at the start of 5412 the directory part of the source file name, and uses that result 5413 instead of the original file name to look up the sources. 5414 5415 Using the previous example, suppose the `foo-1.0' tree has been 5416 moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace 5417 `/usr/src' in all source path names with `/mnt/cross'. The first 5418 lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the 5419 original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source 5420 path substitution rule, use the `set substitute-path' command (*note 5421 set substitute-path::). 5422 5423 To avoid unexpected substitution results, a rule is applied only if 5424 the FROM part of the directory name ends at a directory separator. For 5425 instance, a rule substituting `/usr/source' into `/mnt/cross' will be 5426 applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'. 5427 And because the substitution is applied only at the beginning of the 5428 directory name, this rule will not be applied to 5429 `/root/usr/source/baz.c' either. 5430 5431 In many cases, you can achieve the same result using the `directory' 5432 command. However, `set substitute-path' can be more efficient in the 5433 case where the sources are organized in a complex tree with multiple 5434 subdirectories. With the `directory' command, you need to add each 5435 subdirectory of your project. If you moved the entire tree while 5436 preserving its internal organization, then `set substitute-path' allows 5437 you to direct the debugger to all the sources with one single command. 5438 5439 `set substitute-path' is also more than just a shortcut command. 5440 The source path is only used if the file at the original location no 5441 longer exists. On the other hand, `set substitute-path' modifies the 5442 debugger behavior to look at the rewritten location instead. So, if 5443 for any reason a source file that is not relevant to your executable is 5444 located at the original location, a substitution rule is the only 5445 method available to point GDB at the new location. 5446 5447 You can configure a default source path substitution rule by 5448 configuring GDB with the `--with-relocated-sources=DIR' option. The DIR 5449 should be the name of a directory under GDB's configured prefix (set 5450 with `--prefix' or `--exec-prefix'), and directory names in debug 5451 information under DIR will be adjusted automatically if the installed 5452 GDB is moved to a new location. This is useful if GDB, libraries or 5453 executables with debug information and corresponding source code are 5454 being moved together. 5455 5456 `directory DIRNAME ...' 5457 5458 `dir DIRNAME ...' 5459 Add directory DIRNAME to the front of the source path. Several 5460 directory names may be given to this command, separated by `:' 5461 (`;' on MS-DOS and MS-Windows, where `:' usually appears as part 5462 of absolute file names) or whitespace. You may specify a 5463 directory that is already in the source path; this moves it 5464 forward, so GDB searches it sooner. 5465 5466 You can use the string `$cdir' to refer to the compilation 5467 directory (if one is recorded), and `$cwd' to refer to the current 5468 working directory. `$cwd' is not the same as `.'--the former 5469 tracks the current working directory as it changes during your GDB 5470 session, while the latter is immediately expanded to the current 5471 directory at the time you add an entry to the source path. 5472 5473 `directory' 5474 Reset the source path to its default value (`$cdir:$cwd' on Unix 5475 systems). This requires confirmation. 5476 5477 `show directories' 5478 Print the source path: show which directories it contains. 5479 5480 `set substitute-path FROM TO' 5481 Define a source path substitution rule, and add it at the end of 5482 the current list of existing substitution rules. If a rule with 5483 the same FROM was already defined, then the old rule is also 5484 deleted. 5485 5486 For example, if the file `/foo/bar/baz.c' was moved to 5487 `/mnt/cross/baz.c', then the command 5488 5489 (gdb) set substitute-path /usr/src /mnt/cross 5490 5491 will tell GDB to replace `/usr/src' with `/mnt/cross', which will 5492 allow GDB to find the file `baz.c' even though it was moved. 5493 5494 In the case when more than one substitution rule have been defined, 5495 the rules are evaluated one by one in the order where they have 5496 been defined. The first one matching, if any, is selected to 5497 perform the substitution. 5498 5499 For instance, if we had entered the following commands: 5500 5501 (gdb) set substitute-path /usr/src/include /mnt/include 5502 (gdb) set substitute-path /usr/src /mnt/src 5503 5504 GDB would then rewrite `/usr/src/include/defs.h' into 5505 `/mnt/include/defs.h' by using the first rule. However, it would 5506 use the second rule to rewrite `/usr/src/lib/foo.c' into 5507 `/mnt/src/lib/foo.c'. 5508 5509 `unset substitute-path [path]' 5510 If a path is specified, search the current list of substitution 5511 rules for a rule that would rewrite that path. Delete that rule 5512 if found. A warning is emitted by the debugger if no rule could 5513 be found. 5514 5515 If no path is specified, then all substitution rules are deleted. 5516 5517 `show substitute-path [path]' 5518 If a path is specified, then print the source path substitution 5519 rule which would rewrite that path, if any. 5520 5521 If no path is specified, then print all existing source path 5522 substitution rules. 5523 5524 5525 If your source path is cluttered with directories that are no longer 5526 of interest, GDB may sometimes cause confusion by finding the wrong 5527 versions of source. You can correct the situation as follows: 5528 5529 1. Use `directory' with no argument to reset the source path to its 5530 default value. 5531 5532 2. Use `directory' with suitable arguments to reinstall the 5533 directories you want in the source path. You can add all the 5534 directories in one command. 5535 5536 5537 File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source 5538 5539 9.6 Source and Machine Code 5540 =========================== 5541 5542 You can use the command `info line' to map source lines to program 5543 addresses (and vice versa), and the command `disassemble' to display a 5544 range of addresses as machine instructions. You can use the command 5545 `set disassemble-next-line' to set whether to disassemble next source 5546 line when execution stops. When run under GNU Emacs mode, the `info 5547 line' command causes the arrow to point to the line specified. Also, 5548 `info line' prints addresses in symbolic form as well as hex. 5549 5550 `info line LINESPEC' 5551 Print the starting and ending addresses of the compiled code for 5552 source line LINESPEC. You can specify source lines in any of the 5553 ways documented in *Note Specify Location::. 5554 5555 For example, we can use `info line' to discover the location of the 5556 object code for the first line of function `m4_changequote': 5557 5558 (gdb) info line m4_changequote 5559 Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. 5560 5561 We can also inquire (using `*ADDR' as the form for LINESPEC) what 5562 source line covers a particular address: 5563 (gdb) info line *0x63ff 5564 Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. 5565 5566 After `info line', the default address for the `x' command is 5567 changed to the starting address of the line, so that `x/i' is 5568 sufficient to begin examining the machine code (*note Examining Memory: 5569 Memory.). Also, this address is saved as the value of the convenience 5570 variable `$_' (*note Convenience Variables: Convenience Vars.). 5571 5572 `disassemble' 5573 `disassemble /m' 5574 `disassemble /r' 5575 This specialized command dumps a range of memory as machine 5576 instructions. It can also print mixed source+disassembly by 5577 specifying the `/m' modifier and print the raw instructions in hex 5578 as well as in symbolic form by specifying the `/r'. The default 5579 memory range is the function surrounding the program counter of 5580 the selected frame. A single argument to this command is a 5581 program counter value; GDB dumps the function surrounding this 5582 value. When two arguments are given, they should be separated by 5583 a comma, possibly surrounded by whitespace. The arguments specify 5584 a range of addresses (first inclusive, second exclusive) to dump. 5585 In that case, the name of the function is also printed (since 5586 there could be several functions in the given range). 5587 5588 The argument(s) can be any expression yielding a numeric value, 5589 such as `0x32c4', `&main+10' or `$pc - 8'. 5590 5591 If the range of memory being disassembled contains current program 5592 counter, the instruction at that location is shown with a `=>' 5593 marker. 5594 5595 The following example shows the disassembly of a range of addresses 5596 of HP PA-RISC 2.0 code: 5597 5598 (gdb) disas 0x32c4, 0x32e4 5599 Dump of assembler code from 0x32c4 to 0x32e4: 5600 0x32c4 <main+204>: addil 0,dp 5601 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 5602 0x32cc <main+212>: ldil 0x3000,r31 5603 0x32d0 <main+216>: ble 0x3f8(sr4,r31) 5604 0x32d4 <main+220>: ldo 0(r31),rp 5605 0x32d8 <main+224>: addil -0x800,dp 5606 0x32dc <main+228>: ldo 0x588(r1),r26 5607 0x32e0 <main+232>: ldil 0x3000,r31 5608 End of assembler dump. 5609 5610 Here is an example showing mixed source+assembly for Intel x86, when 5611 the program is stopped just after function prologue: 5612 5613 (gdb) disas /m main 5614 Dump of assembler code for function main: 5615 5 { 5616 0x08048330 <+0>: push %ebp 5617 0x08048331 <+1>: mov %esp,%ebp 5618 0x08048333 <+3>: sub $0x8,%esp 5619 0x08048336 <+6>: and $0xfffffff0,%esp 5620 0x08048339 <+9>: sub $0x10,%esp 5621 5622 6 printf ("Hello.\n"); 5623 => 0x0804833c <+12>: movl $0x8048440,(%esp) 5624 0x08048343 <+19>: call 0x8048284 <puts@plt> 5625 5626 7 return 0; 5627 8 } 5628 0x08048348 <+24>: mov $0x0,%eax 5629 0x0804834d <+29>: leave 5630 0x0804834e <+30>: ret 5631 5632 End of assembler dump. 5633 5634 Some architectures have more than one commonly-used set of 5635 instruction mnemonics or other syntax. 5636 5637 For programs that were dynamically linked and use shared libraries, 5638 instructions that call functions or branch to locations in the shared 5639 libraries might show a seemingly bogus location--it's actually a 5640 location of the relocation table. On some architectures, GDB might be 5641 able to resolve these to actual function names. 5642 5643 `set disassembly-flavor INSTRUCTION-SET' 5644 Select the instruction set to use when disassembling the program 5645 via the `disassemble' or `x/i' commands. 5646 5647 Currently this command is only defined for the Intel x86 family. 5648 You can set INSTRUCTION-SET to either `intel' or `att'. The 5649 default is `att', the AT&T flavor used by default by Unix 5650 assemblers for x86-based targets. 5651 5652 `show disassembly-flavor' 5653 Show the current setting of the disassembly flavor. 5654 5655 `set disassemble-next-line' 5656 `show disassemble-next-line' 5657 Control whether or not GDB will disassemble the next source line 5658 or instruction when execution stops. If ON, GDB will display 5659 disassembly of the next source line when execution of the program 5660 being debugged stops. This is _in addition_ to displaying the 5661 source line itself, which GDB always does if possible. If the 5662 next source line cannot be displayed for some reason (e.g., if GDB 5663 cannot find the source file, or there's no line info in the debug 5664 info), GDB will display disassembly of the next _instruction_ 5665 instead of showing the next source line. If AUTO, GDB will 5666 display disassembly of next instruction only if the source line 5667 cannot be displayed. This setting causes GDB to display some 5668 feedback when you step through a function with no line info or 5669 whose source file is unavailable. The default is OFF, which means 5670 never display the disassembly of the next line or instruction. 5671 5672 5673 File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top 5674 5675 10 Examining Data 5676 ***************** 5677 5678 The usual way to examine data in your program is with the `print' 5679 command (abbreviated `p'), or its synonym `inspect'. It evaluates and 5680 prints the value of an expression of the language your program is 5681 written in (*note Using GDB with Different Languages: Languages.). 5682 5683 `print EXPR' 5684 `print /F EXPR' 5685 EXPR is an expression (in the source language). By default the 5686 value of EXPR is printed in a format appropriate to its data type; 5687 you can choose a different format by specifying `/F', where F is a 5688 letter specifying the format; see *Note Output Formats: Output 5689 Formats. 5690 5691 `print' 5692 `print /F' 5693 If you omit EXPR, GDB displays the last value again (from the 5694 "value history"; *note Value History: Value History.). This 5695 allows you to conveniently inspect the same value in an 5696 alternative format. 5697 5698 A more low-level way of examining data is with the `x' command. It 5699 examines data in memory at a specified address and prints it in a 5700 specified format. *Note Examining Memory: Memory. 5701 5702 If you are interested in information about types, or about how the 5703 fields of a struct or a class are declared, use the `ptype EXP' command 5704 rather than `print'. *Note Examining the Symbol Table: Symbols. 5705 5706 * Menu: 5707 5708 * Expressions:: Expressions 5709 * Ambiguous Expressions:: Ambiguous Expressions 5710 * Variables:: Program variables 5711 * Arrays:: Artificial arrays 5712 * Output Formats:: Output formats 5713 * Memory:: Examining memory 5714 * Auto Display:: Automatic display 5715 * Print Settings:: Print settings 5716 * Value History:: Value history 5717 * Convenience Vars:: Convenience variables 5718 * Registers:: Registers 5719 * Floating Point Hardware:: Floating point hardware 5720 * Vector Unit:: Vector Unit 5721 * OS Information:: Auxiliary data provided by operating system 5722 * Memory Region Attributes:: Memory region attributes 5723 * Dump/Restore Files:: Copy between memory and a file 5724 * Core File Generation:: Cause a program dump its core 5725 * Character Sets:: Debugging programs that use a different 5726 character set than GDB does 5727 * Caching Remote Data:: Data caching for remote targets 5728 * Searching Memory:: Searching memory for a sequence of bytes 5729 5730 5731 File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data 5732 5733 10.1 Expressions 5734 ================ 5735 5736 `print' and many other GDB commands accept an expression and compute 5737 its value. Any kind of constant, variable or operator defined by the 5738 programming language you are using is valid in an expression in GDB. 5739 This includes conditional expressions, function calls, casts, and 5740 string constants. It also includes preprocessor macros, if you 5741 compiled your program to include this information; see *Note 5742 Compilation::. 5743 5744 GDB supports array constants in expressions input by the user. The 5745 syntax is {ELEMENT, ELEMENT...}. For example, you can use the command 5746 `print {1, 2, 3}' to create an array of three integers. If you pass an 5747 array to a function or assign it to a program variable, GDB copies the 5748 array to memory that is `malloc'ed in the target program. 5749 5750 Because C is so widespread, most of the expressions shown in 5751 examples in this manual are in C. *Note Using GDB with Different 5752 Languages: Languages, for information on how to use expressions in other 5753 languages. 5754 5755 In this section, we discuss operators that you can use in GDB 5756 expressions regardless of your programming language. 5757 5758 Casts are supported in all languages, not just in C, because it is so 5759 useful to cast a number into a pointer in order to examine a structure 5760 at that address in memory. 5761 5762 GDB supports these operators, in addition to those common to 5763 programming languages: 5764 5765 `@' 5766 `@' is a binary operator for treating parts of memory as arrays. 5767 *Note Artificial Arrays: Arrays, for more information. 5768 5769 `::' 5770 `::' allows you to specify a variable in terms of the file or 5771 function where it is defined. *Note Program Variables: Variables. 5772 5773 `{TYPE} ADDR' 5774 Refers to an object of type TYPE stored at address ADDR in memory. 5775 ADDR may be any expression whose value is an integer or pointer 5776 (but parentheses are required around binary operators, just as in 5777 a cast). This construct is allowed regardless of what kind of 5778 data is normally supposed to reside at ADDR. 5779 5780 5781 File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data 5782 5783 10.2 Ambiguous Expressions 5784 ========================== 5785 5786 Expressions can sometimes contain some ambiguous elements. For 5787 instance, some programming languages (notably Ada, C++ and Objective-C) 5788 permit a single function name to be defined several times, for 5789 application in different contexts. This is called "overloading". 5790 Another example involving Ada is generics. A "generic package" is 5791 similar to C++ templates and is typically instantiated several times, 5792 resulting in the same function name being defined in different contexts. 5793 5794 In some cases and depending on the language, it is possible to adjust 5795 the expression to remove the ambiguity. For instance in C++, you can 5796 specify the signature of the function you want to break on, as in 5797 `break FUNCTION(TYPES)'. In Ada, using the fully qualified name of 5798 your function often makes the expression unambiguous as well. 5799 5800 When an ambiguity that needs to be resolved is detected, the debugger 5801 has the capability to display a menu of numbered choices for each 5802 possibility, and then waits for the selection with the prompt `>'. The 5803 first option is always `[0] cancel', and typing `0 <RET>' aborts the 5804 current command. If the command in which the expression was used 5805 allows more than one choice to be selected, the next option in the menu 5806 is `[1] all', and typing `1 <RET>' selects all possible choices. 5807 5808 For example, the following session excerpt shows an attempt to set a 5809 breakpoint at the overloaded symbol `String::after'. We choose three 5810 particular definitions of that function name: 5811 5812 (gdb) b String::after 5813 [0] cancel 5814 [1] all 5815 [2] file:String.cc; line number:867 5816 [3] file:String.cc; line number:860 5817 [4] file:String.cc; line number:875 5818 [5] file:String.cc; line number:853 5819 [6] file:String.cc; line number:846 5820 [7] file:String.cc; line number:735 5821 > 2 4 6 5822 Breakpoint 1 at 0xb26c: file String.cc, line 867. 5823 Breakpoint 2 at 0xb344: file String.cc, line 875. 5824 Breakpoint 3 at 0xafcc: file String.cc, line 846. 5825 Multiple breakpoints were set. 5826 Use the "delete" command to delete unwanted 5827 breakpoints. 5828 (gdb) 5829 5830 `set multiple-symbols MODE' 5831 This option allows you to adjust the debugger behavior when an 5832 expression is ambiguous. 5833 5834 By default, MODE is set to `all'. If the command with which the 5835 expression is used allows more than one choice, then GDB 5836 automatically selects all possible choices. For instance, 5837 inserting a breakpoint on a function using an ambiguous name 5838 results in a breakpoint inserted on each possible match. However, 5839 if a unique choice must be made, then GDB uses the menu to help 5840 you disambiguate the expression. For instance, printing the 5841 address of an overloaded function will result in the use of the 5842 menu. 5843 5844 When MODE is set to `ask', the debugger always uses the menu when 5845 an ambiguity is detected. 5846 5847 Finally, when MODE is set to `cancel', the debugger reports an 5848 error due to the ambiguity and the command is aborted. 5849 5850 `show multiple-symbols' 5851 Show the current value of the `multiple-symbols' setting. 5852 5853 5854 File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data 5855 5856 10.3 Program Variables 5857 ====================== 5858 5859 The most common kind of expression to use is the name of a variable in 5860 your program. 5861 5862 Variables in expressions are understood in the selected stack frame 5863 (*note Selecting a Frame: Selection.); they must be either: 5864 5865 * global (or file-static) 5866 5867 or 5868 5869 * visible according to the scope rules of the programming language 5870 from the point of execution in that frame 5871 5872 This means that in the function 5873 5874 foo (a) 5875 int a; 5876 { 5877 bar (a); 5878 { 5879 int b = test (); 5880 bar (b); 5881 } 5882 } 5883 5884 you can examine and use the variable `a' whenever your program is 5885 executing within the function `foo', but you can only use or examine 5886 the variable `b' while your program is executing inside the block where 5887 `b' is declared. 5888 5889 There is an exception: you can refer to a variable or function whose 5890 scope is a single source file even if the current execution point is not 5891 in this file. But it is possible to have more than one such variable or 5892 function with the same name (in different source files). If that 5893 happens, referring to that name has unpredictable effects. If you wish, 5894 you can specify a static variable in a particular function or file, 5895 using the colon-colon (`::') notation: 5896 5897 FILE::VARIABLE 5898 FUNCTION::VARIABLE 5899 5900 Here FILE or FUNCTION is the name of the context for the static 5901 VARIABLE. In the case of file names, you can use quotes to make sure 5902 GDB parses the file name as a single word--for example, to print a 5903 global value of `x' defined in `f2.c': 5904 5905 (gdb) p 'f2.c'::x 5906 5907 This use of `::' is very rarely in conflict with the very similar 5908 use of the same notation in C++. GDB also supports use of the C++ 5909 scope resolution operator in GDB expressions. 5910 5911 _Warning:_ Occasionally, a local variable may appear to have the 5912 wrong value at certain points in a function--just after entry to a 5913 new scope, and just before exit. 5914 You may see this problem when you are stepping by machine 5915 instructions. This is because, on most machines, it takes more than 5916 one instruction to set up a stack frame (including local variable 5917 definitions); if you are stepping by machine instructions, variables 5918 may appear to have the wrong values until the stack frame is completely 5919 built. On exit, it usually also takes more than one machine 5920 instruction to destroy a stack frame; after you begin stepping through 5921 that group of instructions, local variable definitions may be gone. 5922 5923 This may also happen when the compiler does significant 5924 optimizations. To be sure of always seeing accurate values, turn off 5925 all optimization when compiling. 5926 5927 Another possible effect of compiler optimizations is to optimize 5928 unused variables out of existence, or assign variables to registers (as 5929 opposed to memory addresses). Depending on the support for such cases 5930 offered by the debug info format used by the compiler, GDB might not be 5931 able to display values for such local variables. If that happens, GDB 5932 will print a message like this: 5933 5934 No symbol "foo" in current context. 5935 5936 To solve such problems, either recompile without optimizations, or 5937 use a different debug info format, if the compiler supports several such 5938 formats. For example, GCC, the GNU C/C++ compiler, usually supports 5939 the `-gstabs+' option. `-gstabs+' produces debug info in a format that 5940 is superior to formats such as COFF. You may be able to use DWARF 2 5941 (`-gdwarf-2'), which is also an effective form for debug info. *Note 5942 Options for Debugging Your Program or GCC: (gcc.info)Debugging Options. 5943 *Note C and C++: C, for more information about debug info formats that 5944 are best suited to C++ programs. 5945 5946 If you ask to print an object whose contents are unknown to GDB, 5947 e.g., because its data type is not completely specified by the debug 5948 information, GDB will say `<incomplete type>'. *Note incomplete type: 5949 Symbols, for more about this. 5950 5951 Strings are identified as arrays of `char' values without specified 5952 signedness. Arrays of either `signed char' or `unsigned char' get 5953 printed as arrays of 1 byte sized integers. `-fsigned-char' or 5954 `-funsigned-char' GCC options have no effect as GDB defines literal 5955 string type `"char"' as `char' without a sign. For program code 5956 5957 char var0[] = "A"; 5958 signed char var1[] = "A"; 5959 5960 You get during debugging 5961 (gdb) print var0 5962 $1 = "A" 5963 (gdb) print var1 5964 $2 = {65 'A', 0 '\0'} 5965 5966 5967 File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data 5968 5969 10.4 Artificial Arrays 5970 ====================== 5971 5972 It is often useful to print out several successive objects of the same 5973 type in memory; a section of an array, or an array of dynamically 5974 determined size for which only a pointer exists in the program. 5975 5976 You can do this by referring to a contiguous span of memory as an 5977 "artificial array", using the binary operator `@'. The left operand of 5978 `@' should be the first element of the desired array and be an 5979 individual object. The right operand should be the desired length of 5980 the array. The result is an array value whose elements are all of the 5981 type of the left argument. The first element is actually the left 5982 argument; the second element comes from bytes of memory immediately 5983 following those that hold the first element, and so on. Here is an 5984 example. If a program says 5985 5986 int *array = (int *) malloc (len * sizeof (int)); 5987 5988 you can print the contents of `array' with 5989 5990 p *array@len 5991 5992 The left operand of `@' must reside in memory. Array values made 5993 with `@' in this way behave just like other arrays in terms of 5994 subscripting, and are coerced to pointers when used in expressions. 5995 Artificial arrays most often appear in expressions via the value history 5996 (*note Value History: Value History.), after printing one out. 5997 5998 Another way to create an artificial array is to use a cast. This 5999 re-interprets a value as if it were an array. The value need not be in 6000 memory: 6001 (gdb) p/x (short[2])0x12345678 6002 $1 = {0x1234, 0x5678} 6003 6004 As a convenience, if you leave the array length out (as in 6005 `(TYPE[])VALUE') GDB calculates the size to fill the value (as 6006 `sizeof(VALUE)/sizeof(TYPE)': 6007 (gdb) p/x (short[])0x12345678 6008 $2 = {0x1234, 0x5678} 6009 6010 Sometimes the artificial array mechanism is not quite enough; in 6011 moderately complex data structures, the elements of interest may not 6012 actually be adjacent--for example, if you are interested in the values 6013 of pointers in an array. One useful work-around in this situation is 6014 to use a convenience variable (*note Convenience Variables: Convenience 6015 Vars.) as a counter in an expression that prints the first interesting 6016 value, and then repeat that expression via <RET>. For instance, 6017 suppose you have an array `dtab' of pointers to structures, and you are 6018 interested in the values of a field `fv' in each structure. Here is an 6019 example of what you might type: 6020 6021 set $i = 0 6022 p dtab[$i++]->fv 6023 <RET> 6024 <RET> 6025 ... 6026 6027 6028 File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data 6029 6030 10.5 Output Formats 6031 =================== 6032 6033 By default, GDB prints a value according to its data type. Sometimes 6034 this is not what you want. For example, you might want to print a 6035 number in hex, or a pointer in decimal. Or you might want to view data 6036 in memory at a certain address as a character string or as an 6037 instruction. To do these things, specify an "output format" when you 6038 print a value. 6039 6040 The simplest use of output formats is to say how to print a value 6041 already computed. This is done by starting the arguments of the 6042 `print' command with a slash and a format letter. The format letters 6043 supported are: 6044 6045 `x' 6046 Regard the bits of the value as an integer, and print the integer 6047 in hexadecimal. 6048 6049 `d' 6050 Print as integer in signed decimal. 6051 6052 `u' 6053 Print as integer in unsigned decimal. 6054 6055 `o' 6056 Print as integer in octal. 6057 6058 `t' 6059 Print as integer in binary. The letter `t' stands for "two". (1) 6060 6061 `a' 6062 Print as an address, both absolute in hexadecimal and as an offset 6063 from the nearest preceding symbol. You can use this format used 6064 to discover where (in what function) an unknown address is located: 6065 6066 (gdb) p/a 0x54320 6067 $3 = 0x54320 <_initialize_vx+396> 6068 6069 The command `info symbol 0x54320' yields similar results. *Note 6070 info symbol: Symbols. 6071 6072 `c' 6073 Regard as an integer and print it as a character constant. This 6074 prints both the numerical value and its character representation. 6075 The character representation is replaced with the octal escape 6076 `\nnn' for characters outside the 7-bit ASCII range. 6077 6078 Without this format, GDB displays `char', `unsigned char', and 6079 `signed char' data as character constants. Single-byte members of 6080 vectors are displayed as integer data. 6081 6082 `f' 6083 Regard the bits of the value as a floating point number and print 6084 using typical floating point syntax. 6085 6086 `s' 6087 Regard as a string, if possible. With this format, pointers to 6088 single-byte data are displayed as null-terminated strings and 6089 arrays of single-byte data are displayed as fixed-length strings. 6090 Other values are displayed in their natural types. 6091 6092 Without this format, GDB displays pointers to and arrays of 6093 `char', `unsigned char', and `signed char' as strings. 6094 Single-byte members of a vector are displayed as an integer array. 6095 6096 `r' 6097 Print using the `raw' formatting. By default, GDB will use a 6098 type-specific pretty-printer. The `r' format bypasses any 6099 pretty-printer which might exist for the value's type. 6100 6101 For example, to print the program counter in hex (*note 6102 Registers::), type 6103 6104 p/x $pc 6105 6106 Note that no space is required before the slash; this is because command 6107 names in GDB cannot contain a slash. 6108 6109 To reprint the last value in the value history with a different 6110 format, you can use the `print' command with just a format and no 6111 expression. For example, `p/x' reprints the last value in hex. 6112 6113 ---------- Footnotes ---------- 6114 6115 (1) `b' cannot be used because these format letters are also used 6116 with the `x' command, where `b' stands for "byte"; see *Note Examining 6117 Memory: Memory. 6118 6119 6120 File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data 6121 6122 10.6 Examining Memory 6123 ===================== 6124 6125 You can use the command `x' (for "examine") to examine memory in any of 6126 several formats, independently of your program's data types. 6127 6128 `x/NFU ADDR' 6129 `x ADDR' 6130 `x' 6131 Use the `x' command to examine memory. 6132 6133 N, F, and U are all optional parameters that specify how much memory 6134 to display and how to format it; ADDR is an expression giving the 6135 address where you want to start displaying memory. If you use defaults 6136 for NFU, you need not type the slash `/'. Several commands set 6137 convenient defaults for ADDR. 6138 6139 N, the repeat count 6140 The repeat count is a decimal integer; the default is 1. It 6141 specifies how much memory (counting by units U) to display. 6142 6143 F, the display format 6144 The display format is one of the formats used by `print' (`x', 6145 `d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for 6146 machine instructions). The default is `x' (hexadecimal) 6147 initially. The default changes each time you use either `x' or 6148 `print'. 6149 6150 U, the unit size 6151 The unit size is any of 6152 6153 `b' 6154 Bytes. 6155 6156 `h' 6157 Halfwords (two bytes). 6158 6159 `w' 6160 Words (four bytes). This is the initial default. 6161 6162 `g' 6163 Giant words (eight bytes). 6164 6165 Each time you specify a unit size with `x', that size becomes the 6166 default unit the next time you use `x'. (For the `s' and `i' 6167 formats, the unit size is ignored and is normally not written.) 6168 6169 ADDR, starting display address 6170 ADDR is the address where you want GDB to begin displaying memory. 6171 The expression need not have a pointer value (though it may); it 6172 is always interpreted as an integer address of a byte of memory. 6173 *Note Expressions: Expressions, for more information on 6174 expressions. The default for ADDR is usually just after the last 6175 address examined--but several other commands also set the default 6176 address: `info breakpoints' (to the address of the last breakpoint 6177 listed), `info line' (to the starting address of a line), and 6178 `print' (if you use it to display a value from memory). 6179 6180 For example, `x/3uh 0x54320' is a request to display three halfwords 6181 (`h') of memory, formatted as unsigned decimal integers (`u'), starting 6182 at address `0x54320'. `x/4xw $sp' prints the four words (`w') of 6183 memory above the stack pointer (here, `$sp'; *note Registers: 6184 Registers.) in hexadecimal (`x'). 6185 6186 Since the letters indicating unit sizes are all distinct from the 6187 letters specifying output formats, you do not have to remember whether 6188 unit size or format comes first; either order works. The output 6189 specifications `4xw' and `4wx' mean exactly the same thing. (However, 6190 the count N must come first; `wx4' does not work.) 6191 6192 Even though the unit size U is ignored for the formats `s' and `i', 6193 you might still want to use a count N; for example, `3i' specifies that 6194 you want to see three machine instructions, including any operands. 6195 For convenience, especially when used with the `display' command, the 6196 `i' format also prints branch delay slot instructions, if any, beyond 6197 the count specified, which immediately follow the last instruction that 6198 is within the count. The command `disassemble' gives an alternative 6199 way of inspecting machine instructions; see *Note Source and Machine 6200 Code: Machine Code. 6201 6202 All the defaults for the arguments to `x' are designed to make it 6203 easy to continue scanning memory with minimal specifications each time 6204 you use `x'. For example, after you have inspected three machine 6205 instructions with `x/3i ADDR', you can inspect the next seven with just 6206 `x/7'. If you use <RET> to repeat the `x' command, the repeat count N 6207 is used again; the other arguments default as for successive uses of 6208 `x'. 6209 6210 When examining machine instructions, the instruction at current 6211 program counter is shown with a `=>' marker. For example: 6212 6213 (gdb) x/5i $pc-6 6214 0x804837f <main+11>: mov %esp,%ebp 6215 0x8048381 <main+13>: push %ecx 6216 0x8048382 <main+14>: sub $0x4,%esp 6217 => 0x8048385 <main+17>: movl $0x8048460,(%esp) 6218 0x804838c <main+24>: call 0x80482d4 <puts@plt> 6219 6220 The addresses and contents printed by the `x' command are not saved 6221 in the value history because there is often too much of them and they 6222 would get in the way. Instead, GDB makes these values available for 6223 subsequent use in expressions as values of the convenience variables 6224 `$_' and `$__'. After an `x' command, the last address examined is 6225 available for use in expressions in the convenience variable `$_'. The 6226 contents of that address, as examined, are available in the convenience 6227 variable `$__'. 6228 6229 If the `x' command has a repeat count, the address and contents saved 6230 are from the last memory unit printed; this is not the same as the last 6231 address printed if several units were printed on the last line of 6232 output. 6233 6234 When you are debugging a program running on a remote target machine 6235 (*note Remote Debugging::), you may wish to verify the program's image 6236 in the remote machine's memory against the executable file you 6237 downloaded to the target. The `compare-sections' command is provided 6238 for such situations. 6239 6240 `compare-sections [SECTION-NAME]' 6241 Compare the data of a loadable section SECTION-NAME in the 6242 executable file of the program being debugged with the same 6243 section in the remote machine's memory, and report any mismatches. 6244 With no arguments, compares all loadable sections. This command's 6245 availability depends on the target's support for the `"qCRC"' 6246 remote request. 6247 6248 6249 File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data 6250 6251 10.7 Automatic Display 6252 ====================== 6253 6254 If you find that you want to print the value of an expression frequently 6255 (to see how it changes), you might want to add it to the "automatic 6256 display list" so that GDB prints its value each time your program stops. 6257 Each expression added to the list is given a number to identify it; to 6258 remove an expression from the list, you specify that number. The 6259 automatic display looks like this: 6260 6261 2: foo = 38 6262 3: bar[5] = (struct hack *) 0x3804 6263 6264 This display shows item numbers, expressions and their current values. 6265 As with displays you request manually using `x' or `print', you can 6266 specify the output format you prefer; in fact, `display' decides 6267 whether to use `print' or `x' depending your format specification--it 6268 uses `x' if you specify either the `i' or `s' format, or a unit size; 6269 otherwise it uses `print'. 6270 6271 `display EXPR' 6272 Add the expression EXPR to the list of expressions to display each 6273 time your program stops. *Note Expressions: Expressions. 6274 6275 `display' does not repeat if you press <RET> again after using it. 6276 6277 `display/FMT EXPR' 6278 For FMT specifying only a display format and not a size or count, 6279 add the expression EXPR to the auto-display list but arrange to 6280 display it each time in the specified format FMT. *Note Output 6281 Formats: Output Formats. 6282 6283 `display/FMT ADDR' 6284 For FMT `i' or `s', or including a unit-size or a number of units, 6285 add the expression ADDR as a memory address to be examined each 6286 time your program stops. Examining means in effect doing `x/FMT 6287 ADDR'. *Note Examining Memory: Memory. 6288 6289 For example, `display/i $pc' can be helpful, to see the machine 6290 instruction about to be executed each time execution stops (`$pc' is a 6291 common name for the program counter; *note Registers: Registers.). 6292 6293 `undisplay DNUMS...' 6294 `delete display DNUMS...' 6295 Remove item numbers DNUMS from the list of expressions to display. 6296 6297 `undisplay' does not repeat if you press <RET> after using it. 6298 (Otherwise you would just get the error `No display number ...'.) 6299 6300 `disable display DNUMS...' 6301 Disable the display of item numbers DNUMS. A disabled display 6302 item is not printed automatically, but is not forgotten. It may be 6303 enabled again later. 6304 6305 `enable display DNUMS...' 6306 Enable display of item numbers DNUMS. It becomes effective once 6307 again in auto display of its expression, until you specify 6308 otherwise. 6309 6310 `display' 6311 Display the current values of the expressions on the list, just as 6312 is done when your program stops. 6313 6314 `info display' 6315 Print the list of expressions previously set up to display 6316 automatically, each one with its item number, but without showing 6317 the values. This includes disabled expressions, which are marked 6318 as such. It also includes expressions which would not be 6319 displayed right now because they refer to automatic variables not 6320 currently available. 6321 6322 If a display expression refers to local variables, then it does not 6323 make sense outside the lexical context for which it was set up. Such an 6324 expression is disabled when execution enters a context where one of its 6325 variables is not defined. For example, if you give the command 6326 `display last_char' while inside a function with an argument 6327 `last_char', GDB displays this argument while your program continues to 6328 stop inside that function. When it stops elsewhere--where there is no 6329 variable `last_char'--the display is disabled automatically. The next 6330 time your program stops where `last_char' is meaningful, you can enable 6331 the display expression once again. 6332 6333 6334 File: gdb.info, Node: Print Settings, Next: Value History, Prev: Auto Display, Up: Data 6335 6336 10.8 Print Settings 6337 =================== 6338 6339 GDB provides the following ways to control how arrays, structures, and 6340 symbols are printed. 6341 6342 These settings are useful for debugging programs in any language: 6343 6344 `set print address' 6345 `set print address on' 6346 GDB prints memory addresses showing the location of stack traces, 6347 structure values, pointer values, breakpoints, and so forth, even 6348 when it also displays the contents of those addresses. The default 6349 is `on'. For example, this is what a stack frame display looks 6350 like with `set print address on': 6351 6352 (gdb) f 6353 #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") 6354 at input.c:530 6355 530 if (lquote != def_lquote) 6356 6357 `set print address off' 6358 Do not print addresses when displaying their contents. For 6359 example, this is the same stack frame displayed with `set print 6360 address off': 6361 6362 (gdb) set print addr off 6363 (gdb) f 6364 #0 set_quotes (lq="<<", rq=">>") at input.c:530 6365 530 if (lquote != def_lquote) 6366 6367 You can use `set print address off' to eliminate all machine 6368 dependent displays from the GDB interface. For example, with 6369 `print address off', you should get the same text for backtraces on 6370 all machines--whether or not they involve pointer arguments. 6371 6372 `show print address' 6373 Show whether or not addresses are to be printed. 6374 6375 When GDB prints a symbolic address, it normally prints the closest 6376 earlier symbol plus an offset. If that symbol does not uniquely 6377 identify the address (for example, it is a name whose scope is a single 6378 source file), you may need to clarify. One way to do this is with 6379 `info line', for example `info line *0x4537'. Alternately, you can set 6380 GDB to print the source file and line number when it prints a symbolic 6381 address: 6382 6383 `set print symbol-filename on' 6384 Tell GDB to print the source file name and line number of a symbol 6385 in the symbolic form of an address. 6386 6387 `set print symbol-filename off' 6388 Do not print source file name and line number of a symbol. This 6389 is the default. 6390 6391 `show print symbol-filename' 6392 Show whether or not GDB will print the source file name and line 6393 number of a symbol in the symbolic form of an address. 6394 6395 Another situation where it is helpful to show symbol filenames and 6396 line numbers is when disassembling code; GDB shows you the line number 6397 and source file that corresponds to each instruction. 6398 6399 Also, you may wish to see the symbolic form only if the address being 6400 printed is reasonably close to the closest earlier symbol: 6401 6402 `set print max-symbolic-offset MAX-OFFSET' 6403 Tell GDB to only display the symbolic form of an address if the 6404 offset between the closest earlier symbol and the address is less 6405 than MAX-OFFSET. The default is 0, which tells GDB to always 6406 print the symbolic form of an address if any symbol precedes it. 6407 6408 `show print max-symbolic-offset' 6409 Ask how large the maximum offset is that GDB prints in a symbolic 6410 address. 6411 6412 If you have a pointer and you are not sure where it points, try `set 6413 print symbol-filename on'. Then you can determine the name and source 6414 file location of the variable where it points, using `p/a POINTER'. 6415 This interprets the address in symbolic form. For example, here GDB 6416 shows that a variable `ptt' points at another variable `t', defined in 6417 `hi2.c': 6418 6419 (gdb) set print symbol-filename on 6420 (gdb) p/a ptt 6421 $4 = 0xe008 <t in hi2.c> 6422 6423 _Warning:_ For pointers that point to a local variable, `p/a' does 6424 not show the symbol name and filename of the referent, even with 6425 the appropriate `set print' options turned on. 6426 6427 Other settings control how different kinds of objects are printed: 6428 6429 `set print array' 6430 `set print array on' 6431 Pretty print arrays. This format is more convenient to read, but 6432 uses more space. The default is off. 6433 6434 `set print array off' 6435 Return to compressed format for arrays. 6436 6437 `show print array' 6438 Show whether compressed or pretty format is selected for displaying 6439 arrays. 6440 6441 `set print array-indexes' 6442 `set print array-indexes on' 6443 Print the index of each element when displaying arrays. May be 6444 more convenient to locate a given element in the array or quickly 6445 find the index of a given element in that printed array. The 6446 default is off. 6447 6448 `set print array-indexes off' 6449 Stop printing element indexes when displaying arrays. 6450 6451 `show print array-indexes' 6452 Show whether the index of each element is printed when displaying 6453 arrays. 6454 6455 `set print elements NUMBER-OF-ELEMENTS' 6456 Set a limit on how many elements of an array GDB will print. If 6457 GDB is printing a large array, it stops printing after it has 6458 printed the number of elements set by the `set print elements' 6459 command. This limit also applies to the display of strings. When 6460 GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS 6461 to zero means that the printing is unlimited. 6462 6463 `show print elements' 6464 Display the number of elements of a large array that GDB will 6465 print. If the number is 0, then the printing is unlimited. 6466 6467 `set print frame-arguments VALUE' 6468 This command allows to control how the values of arguments are 6469 printed when the debugger prints a frame (*note Frames::). The 6470 possible values are: 6471 6472 `all' 6473 The values of all arguments are printed. 6474 6475 `scalars' 6476 Print the value of an argument only if it is a scalar. The 6477 value of more complex arguments such as arrays, structures, 6478 unions, etc, is replaced by `...'. This is the default. 6479 Here is an example where only scalar arguments are shown: 6480 6481 #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) 6482 at frame-args.c:23 6483 6484 `none' 6485 None of the argument values are printed. Instead, the value 6486 of each argument is replaced by `...'. In this case, the 6487 example above now becomes: 6488 6489 #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) 6490 at frame-args.c:23 6491 6492 By default, only scalar arguments are printed. This command can 6493 be used to configure the debugger to print the value of all 6494 arguments, regardless of their type. However, it is often 6495 advantageous to not print the value of more complex parameters. 6496 For instance, it reduces the amount of information printed in each 6497 frame, making the backtrace more readable. Also, it improves 6498 performance when displaying Ada frames, because the computation of 6499 large arguments can sometimes be CPU-intensive, especially in 6500 large applications. Setting `print frame-arguments' to `scalars' 6501 (the default) or `none' avoids this computation, thus speeding up 6502 the display of each Ada frame. 6503 6504 `show print frame-arguments' 6505 Show how the value of arguments should be displayed when printing 6506 a frame. 6507 6508 `set print repeats' 6509 Set the threshold for suppressing display of repeated array 6510 elements. When the number of consecutive identical elements of an 6511 array exceeds the threshold, GDB prints the string `"<repeats N 6512 times>"', where N is the number of identical repetitions, instead 6513 of displaying the identical elements themselves. Setting the 6514 threshold to zero will cause all elements to be individually 6515 printed. The default threshold is 10. 6516 6517 `show print repeats' 6518 Display the current threshold for printing repeated identical 6519 elements. 6520 6521 `set print null-stop' 6522 Cause GDB to stop printing the characters of an array when the 6523 first NULL is encountered. This is useful when large arrays 6524 actually contain only short strings. The default is off. 6525 6526 `show print null-stop' 6527 Show whether GDB stops printing an array on the first NULL 6528 character. 6529 6530 `set print pretty on' 6531 Cause GDB to print structures in an indented format with one member 6532 per line, like this: 6533 6534 $1 = { 6535 next = 0x0, 6536 flags = { 6537 sweet = 1, 6538 sour = 1 6539 }, 6540 meat = 0x54 "Pork" 6541 } 6542 6543 `set print pretty off' 6544 Cause GDB to print structures in a compact format, like this: 6545 6546 $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ 6547 meat = 0x54 "Pork"} 6548 6549 This is the default format. 6550 6551 `show print pretty' 6552 Show which format GDB is using to print structures. 6553 6554 `set print sevenbit-strings on' 6555 Print using only seven-bit characters; if this option is set, GDB 6556 displays any eight-bit characters (in strings or character values) 6557 using the notation `\'NNN. This setting is best if you are 6558 working in English (ASCII) and you use the high-order bit of 6559 characters as a marker or "meta" bit. 6560 6561 `set print sevenbit-strings off' 6562 Print full eight-bit characters. This allows the use of more 6563 international character sets, and is the default. 6564 6565 `show print sevenbit-strings' 6566 Show whether or not GDB is printing only seven-bit characters. 6567 6568 `set print union on' 6569 Tell GDB to print unions which are contained in structures and 6570 other unions. This is the default setting. 6571 6572 `set print union off' 6573 Tell GDB not to print unions which are contained in structures and 6574 other unions. GDB will print `"{...}"' instead. 6575 6576 `show print union' 6577 Ask GDB whether or not it will print unions which are contained in 6578 structures and other unions. 6579 6580 For example, given the declarations 6581 6582 typedef enum {Tree, Bug} Species; 6583 typedef enum {Big_tree, Acorn, Seedling} Tree_forms; 6584 typedef enum {Caterpillar, Cocoon, Butterfly} 6585 Bug_forms; 6586 6587 struct thing { 6588 Species it; 6589 union { 6590 Tree_forms tree; 6591 Bug_forms bug; 6592 } form; 6593 }; 6594 6595 struct thing foo = {Tree, {Acorn}}; 6596 6597 with `set print union on' in effect `p foo' would print 6598 6599 $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} 6600 6601 and with `set print union off' in effect it would print 6602 6603 $1 = {it = Tree, form = {...}} 6604 6605 `set print union' affects programs written in C-like languages and 6606 in Pascal. 6607 6608 These settings are of interest when debugging C++ programs: 6609 6610 `set print demangle' 6611 `set print demangle on' 6612 Print C++ names in their source form rather than in the encoded 6613 ("mangled") form passed to the assembler and linker for type-safe 6614 linkage. The default is on. 6615 6616 `show print demangle' 6617 Show whether C++ names are printed in mangled or demangled form. 6618 6619 `set print asm-demangle' 6620 `set print asm-demangle on' 6621 Print C++ names in their source form rather than their mangled 6622 form, even in assembler code printouts such as instruction 6623 disassemblies. The default is off. 6624 6625 `show print asm-demangle' 6626 Show whether C++ names in assembly listings are printed in mangled 6627 or demangled form. 6628 6629 `set demangle-style STYLE' 6630 Choose among several encoding schemes used by different compilers 6631 to represent C++ names. The choices for STYLE are currently: 6632 6633 `auto' 6634 Allow GDB to choose a decoding style by inspecting your 6635 program. 6636 6637 `gnu' 6638 Decode based on the GNU C++ compiler (`g++') encoding 6639 algorithm. This is the default. 6640 6641 `hp' 6642 Decode based on the HP ANSI C++ (`aCC') encoding algorithm. 6643 6644 `lucid' 6645 Decode based on the Lucid C++ compiler (`lcc') encoding 6646 algorithm. 6647 6648 `arm' 6649 Decode using the algorithm in the `C++ Annotated Reference 6650 Manual'. *Warning:* this setting alone is not sufficient to 6651 allow debugging `cfront'-generated executables. GDB would 6652 require further enhancement to permit that. 6653 6654 If you omit STYLE, you will see a list of possible formats. 6655 6656 `show demangle-style' 6657 Display the encoding style currently in use for decoding C++ 6658 symbols. 6659 6660 `set print object' 6661 `set print object on' 6662 When displaying a pointer to an object, identify the _actual_ 6663 (derived) type of the object rather than the _declared_ type, using 6664 the virtual function table. 6665 6666 `set print object off' 6667 Display only the declared type of objects, without reference to the 6668 virtual function table. This is the default setting. 6669 6670 `show print object' 6671 Show whether actual, or declared, object types are displayed. 6672 6673 `set print static-members' 6674 `set print static-members on' 6675 Print static members when displaying a C++ object. The default is 6676 on. 6677 6678 `set print static-members off' 6679 Do not print static members when displaying a C++ object. 6680 6681 `show print static-members' 6682 Show whether C++ static members are printed or not. 6683 6684 `set print pascal_static-members' 6685 `set print pascal_static-members on' 6686 Print static members when displaying a Pascal object. The default 6687 is on. 6688 6689 `set print pascal_static-members off' 6690 Do not print static members when displaying a Pascal object. 6691 6692 `show print pascal_static-members' 6693 Show whether Pascal static members are printed or not. 6694 6695 `set print vtbl' 6696 `set print vtbl on' 6697 Pretty print C++ virtual function tables. The default is off. 6698 (The `vtbl' commands do not work on programs compiled with the HP 6699 ANSI C++ compiler (`aCC').) 6700 6701 `set print vtbl off' 6702 Do not pretty print C++ virtual function tables. 6703 6704 `show print vtbl' 6705 Show whether C++ virtual function tables are pretty printed, or 6706 not. 6707 6708 6709 File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Print Settings, Up: Data 6710 6711 10.9 Value History 6712 ================== 6713 6714 Values printed by the `print' command are saved in the GDB "value 6715 history". This allows you to refer to them in other expressions. 6716 Values are kept until the symbol table is re-read or discarded (for 6717 example with the `file' or `symbol-file' commands). When the symbol 6718 table changes, the value history is discarded, since the values may 6719 contain pointers back to the types defined in the symbol table. 6720 6721 The values printed are given "history numbers" by which you can 6722 refer to them. These are successive integers starting with one. 6723 `print' shows you the history number assigned to a value by printing 6724 `$NUM = ' before the value; here NUM is the history number. 6725 6726 To refer to any previous value, use `$' followed by the value's 6727 history number. The way `print' labels its output is designed to 6728 remind you of this. Just `$' refers to the most recent value in the 6729 history, and `$$' refers to the value before that. `$$N' refers to the 6730 Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is 6731 equivalent to `$$', and `$$0' is equivalent to `$'. 6732 6733 For example, suppose you have just printed a pointer to a structure 6734 and want to see the contents of the structure. It suffices to type 6735 6736 p *$ 6737 6738 If you have a chain of structures where the component `next' points 6739 to the next one, you can print the contents of the next one with this: 6740 6741 p *$.next 6742 6743 You can print successive links in the chain by repeating this 6744 command--which you can do by just typing <RET>. 6745 6746 Note that the history records values, not expressions. If the value 6747 of `x' is 4 and you type these commands: 6748 6749 print x 6750 set x=5 6751 6752 then the value recorded in the value history by the `print' command 6753 remains 4 even though the value of `x' has changed. 6754 6755 `show values' 6756 Print the last ten values in the value history, with their item 6757 numbers. This is like `p $$9' repeated ten times, except that 6758 `show values' does not change the history. 6759 6760 `show values N' 6761 Print ten history values centered on history item number N. 6762 6763 `show values +' 6764 Print ten history values just after the values last printed. If 6765 no more values are available, `show values +' produces no display. 6766 6767 Pressing <RET> to repeat `show values N' has exactly the same effect 6768 as `show values +'. 6769 6770 6771 File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data 6772 6773 10.10 Convenience Variables 6774 =========================== 6775 6776 GDB provides "convenience variables" that you can use within GDB to 6777 hold on to a value and refer to it later. These variables exist 6778 entirely within GDB; they are not part of your program, and setting a 6779 convenience variable has no direct effect on further execution of your 6780 program. That is why you can use them freely. 6781 6782 Convenience variables are prefixed with `$'. Any name preceded by 6783 `$' can be used for a convenience variable, unless it is one of the 6784 predefined machine-specific register names (*note Registers: 6785 Registers.). (Value history references, in contrast, are _numbers_ 6786 preceded by `$'. *Note Value History: Value History.) 6787 6788 You can save a value in a convenience variable with an assignment 6789 expression, just as you would set a variable in your program. For 6790 example: 6791 6792 set $foo = *object_ptr 6793 6794 would save in `$foo' the value contained in the object pointed to by 6795 `object_ptr'. 6796 6797 Using a convenience variable for the first time creates it, but its 6798 value is `void' until you assign a new value. You can alter the value 6799 with another assignment at any time. 6800 6801 Convenience variables have no fixed types. You can assign a 6802 convenience variable any type of value, including structures and 6803 arrays, even if that variable already has a value of a different type. 6804 The convenience variable, when used as an expression, has the type of 6805 its current value. 6806 6807 `show convenience' 6808 Print a list of convenience variables used so far, and their 6809 values. Abbreviated `show conv'. 6810 6811 `init-if-undefined $VARIABLE = EXPRESSION' 6812 Set a convenience variable if it has not already been set. This 6813 is useful for user-defined commands that keep some state. It is 6814 similar, in concept, to using local static variables with 6815 initializers in C (except that convenience variables are global). 6816 It can also be used to allow users to override default values used 6817 in a command script. 6818 6819 If the variable is already defined then the expression is not 6820 evaluated so any side-effects do not occur. 6821 6822 One of the ways to use a convenience variable is as a counter to be 6823 incremented or a pointer to be advanced. For example, to print a field 6824 from successive elements of an array of structures: 6825 6826 set $i = 0 6827 print bar[$i++]->contents 6828 6829 Repeat that command by typing <RET>. 6830 6831 Some convenience variables are created automatically by GDB and given 6832 values likely to be useful. 6833 6834 `$_' 6835 The variable `$_' is automatically set by the `x' command to the 6836 last address examined (*note Examining Memory: Memory.). Other 6837 commands which provide a default address for `x' to examine also 6838 set `$_' to that address; these commands include `info line' and 6839 `info breakpoint'. The type of `$_' is `void *' except when set 6840 by the `x' command, in which case it is a pointer to the type of 6841 `$__'. 6842 6843 `$__' 6844 The variable `$__' is automatically set by the `x' command to the 6845 value found in the last address examined. Its type is chosen to 6846 match the format in which the data was printed. 6847 6848 `$_exitcode' 6849 The variable `$_exitcode' is automatically set to the exit code 6850 when the program being debugged terminates. 6851 6852 `$_siginfo' 6853 The variable `$_siginfo' contains extra signal information (*note 6854 extra signal information::). Note that `$_siginfo' could be 6855 empty, if the application has not yet received any signals. For 6856 example, it will be empty before you execute the `run' command. 6857 6858 On HP-UX systems, if you refer to a function or variable name that 6859 begins with a dollar sign, GDB searches for a user or system name 6860 first, before it searches for a convenience variable. 6861 6862 GDB also supplies some "convenience functions". These have a syntax 6863 similar to convenience variables. A convenience function can be used 6864 in an expression just like an ordinary function; however, a convenience 6865 function is implemented internally to GDB. 6866 6867 `help function' 6868 Print a list of all convenience functions. 6869 6870 6871 File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data 6872 6873 10.11 Registers 6874 =============== 6875 6876 You can refer to machine register contents, in expressions, as variables 6877 with names starting with `$'. The names of registers are different for 6878 each machine; use `info registers' to see the names used on your 6879 machine. 6880 6881 `info registers' 6882 Print the names and values of all registers except floating-point 6883 and vector registers (in the selected stack frame). 6884 6885 `info all-registers' 6886 Print the names and values of all registers, including 6887 floating-point and vector registers (in the selected stack frame). 6888 6889 `info registers REGNAME ...' 6890 Print the "relativized" value of each specified register REGNAME. 6891 As discussed in detail below, register values are normally 6892 relative to the selected stack frame. REGNAME may be any register 6893 name valid on the machine you are using, with or without the 6894 initial `$'. 6895 6896 GDB has four "standard" register names that are available (in 6897 expressions) on most machines--whenever they do not conflict with an 6898 architecture's canonical mnemonics for registers. The register names 6899 `$pc' and `$sp' are used for the program counter register and the stack 6900 pointer. `$fp' is used for a register that contains a pointer to the 6901 current stack frame, and `$ps' is used for a register that contains the 6902 processor status. For example, you could print the program counter in 6903 hex with 6904 6905 p/x $pc 6906 6907 or print the instruction to be executed next with 6908 6909 x/i $pc 6910 6911 or add four to the stack pointer(1) with 6912 6913 set $sp += 4 6914 6915 Whenever possible, these four standard register names are available 6916 on your machine even though the machine has different canonical 6917 mnemonics, so long as there is no conflict. The `info registers' 6918 command shows the canonical names. For example, on the SPARC, `info 6919 registers' displays the processor status register as `$psr' but you can 6920 also refer to it as `$ps'; and on x86-based machines `$ps' is an alias 6921 for the EFLAGS register. 6922 6923 GDB always considers the contents of an ordinary register as an 6924 integer when the register is examined in this way. Some machines have 6925 special registers which can hold nothing but floating point; these 6926 registers are considered to have floating point values. There is no way 6927 to refer to the contents of an ordinary register as floating point value 6928 (although you can _print_ it as a floating point value with `print/f 6929 $REGNAME'). 6930 6931 Some registers have distinct "raw" and "virtual" data formats. This 6932 means that the data format in which the register contents are saved by 6933 the operating system is not the same one that your program normally 6934 sees. For example, the registers of the 68881 floating point 6935 coprocessor are always saved in "extended" (raw) format, but all C 6936 programs expect to work with "double" (virtual) format. In such cases, 6937 GDB normally works with the virtual format only (the format that makes 6938 sense for your program), but the `info registers' command prints the 6939 data in both formats. 6940 6941 Some machines have special registers whose contents can be 6942 interpreted in several different ways. For example, modern x86-based 6943 machines have SSE and MMX registers that can hold several values packed 6944 together in several different formats. GDB refers to such registers in 6945 `struct' notation: 6946 6947 (gdb) print $xmm1 6948 $1 = { 6949 v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044}, 6950 v2_double = {9.92129282474342e-303, 2.7585945287983262e-313}, 6951 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", 6952 v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0}, 6953 v4_int32 = {0, 20657912, 11, 13}, 6954 v2_int64 = {88725056443645952, 55834574859}, 6955 uint128 = 0x0000000d0000000b013b36f800000000 6956 } 6957 6958 To set values of such registers, you need to tell GDB which view of the 6959 register you wish to change, as if you were assigning value to a 6960 `struct' member: 6961 6962 (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF 6963 6964 Normally, register values are relative to the selected stack frame 6965 (*note Selecting a Frame: Selection.). This means that you get the 6966 value that the register would contain if all stack frames farther in 6967 were exited and their saved registers restored. In order to see the 6968 true contents of hardware registers, you must select the innermost 6969 frame (with `frame 0'). 6970 6971 However, GDB must deduce where registers are saved, from the machine 6972 code generated by your compiler. If some registers are not saved, or if 6973 GDB is unable to locate the saved registers, the selected stack frame 6974 makes no difference. 6975 6976 ---------- Footnotes ---------- 6977 6978 (1) This is a way of removing one word from the stack, on machines 6979 where stacks grow downward in memory (most machines, nowadays). This 6980 assumes that the innermost stack frame is selected; setting `$sp' is 6981 not allowed when other stack frames are selected. To pop entire frames 6982 off the stack, regardless of machine architecture, use `return'; see 6983 *Note Returning from a Function: Returning. 6984 6985 6986 File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data 6987 6988 10.12 Floating Point Hardware 6989 ============================= 6990 6991 Depending on the configuration, GDB may be able to give you more 6992 information about the status of the floating point hardware. 6993 6994 `info float' 6995 Display hardware-dependent information about the floating point 6996 unit. The exact contents and layout vary depending on the 6997 floating point chip. Currently, `info float' is supported on the 6998 ARM and x86 machines. 6999 7000 7001 File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data 7002 7003 10.13 Vector Unit 7004 ================= 7005 7006 Depending on the configuration, GDB may be able to give you more 7007 information about the status of the vector unit. 7008 7009 `info vector' 7010 Display information about the vector unit. The exact contents and 7011 layout vary depending on the hardware. 7012 7013 7014 File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data 7015 7016 10.14 Operating System Auxiliary Information 7017 ============================================ 7018 7019 GDB provides interfaces to useful OS facilities that can help you debug 7020 your program. 7021 7022 When GDB runs on a "Posix system" (such as GNU or Unix machines), it 7023 interfaces with the inferior via the `ptrace' system call. The 7024 operating system creates a special sata structure, called `struct 7025 user', for this interface. You can use the command `info udot' to 7026 display the contents of this data structure. 7027 7028 `info udot' 7029 Display the contents of the `struct user' maintained by the OS 7030 kernel for the program being debugged. GDB displays the contents 7031 of `struct user' as a list of hex numbers, similar to the 7032 `examine' command. 7033 7034 Some operating systems supply an "auxiliary vector" to programs at 7035 startup. This is akin to the arguments and environment that you 7036 specify for a program, but contains a system-dependent variety of 7037 binary values that tell system libraries important details about the 7038 hardware, operating system, and process. Each value's purpose is 7039 identified by an integer tag; the meanings are well-known but 7040 system-specific. Depending on the configuration and operating system 7041 facilities, GDB may be able to show you this information. For remote 7042 targets, this functionality may further depend on the remote stub's 7043 support of the `qXfer:auxv:read' packet, see *Note qXfer auxiliary 7044 vector read::. 7045 7046 `info auxv' 7047 Display the auxiliary vector of the inferior, which can be either a 7048 live process or a core dump file. GDB prints each tag value 7049 numerically, and also shows names and text descriptions for 7050 recognized tags. Some values in the vector are numbers, some bit 7051 masks, and some pointers to strings or other data. GDB displays 7052 each value in the most appropriate form for a recognized tag, and 7053 in hexadecimal for an unrecognized tag. 7054 7055 On some targets, GDB can access operating-system-specific information 7056 and display it to user, without interpretation. For remote targets, 7057 this functionality depends on the remote stub's support of the 7058 `qXfer:osdata:read' packet, see *Note qXfer osdata read::. 7059 7060 `info os processes' 7061 Display the list of processes on the target. For each process, 7062 GDB prints the process identifier, the name of the user, and the 7063 command corresponding to the process. 7064 7065 7066 File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data 7067 7068 10.15 Memory Region Attributes 7069 ============================== 7070 7071 "Memory region attributes" allow you to describe special handling 7072 required by regions of your target's memory. GDB uses attributes to 7073 determine whether to allow certain types of memory accesses; whether to 7074 use specific width accesses; and whether to cache target memory. By 7075 default the description of memory regions is fetched from the target 7076 (if the current target supports this), but the user can override the 7077 fetched regions. 7078 7079 Defined memory regions can be individually enabled and disabled. 7080 When a memory region is disabled, GDB uses the default attributes when 7081 accessing memory in that region. Similarly, if no memory regions have 7082 been defined, GDB uses the default attributes when accessing all memory. 7083 7084 When a memory region is defined, it is given a number to identify it; 7085 to enable, disable, or remove a memory region, you specify that number. 7086 7087 `mem LOWER UPPER ATTRIBUTES...' 7088 Define a memory region bounded by LOWER and UPPER with attributes 7089 ATTRIBUTES..., and add it to the list of regions monitored by GDB. 7090 Note that UPPER == 0 is a special case: it is treated as the 7091 target's maximum memory address. (0xffff on 16 bit targets, 7092 0xffffffff on 32 bit targets, etc.) 7093 7094 `mem auto' 7095 Discard any user changes to the memory regions and use 7096 target-supplied regions, if available, or no regions if the target 7097 does not support. 7098 7099 `delete mem NUMS...' 7100 Remove memory regions NUMS... from the list of regions monitored 7101 by GDB. 7102 7103 `disable mem NUMS...' 7104 Disable monitoring of memory regions NUMS.... A disabled memory 7105 region is not forgotten. It may be enabled again later. 7106 7107 `enable mem NUMS...' 7108 Enable monitoring of memory regions NUMS.... 7109 7110 `info mem' 7111 Print a table of all defined memory regions, with the following 7112 columns for each region: 7113 7114 _Memory Region Number_ 7115 7116 _Enabled or Disabled._ 7117 Enabled memory regions are marked with `y'. Disabled memory 7118 regions are marked with `n'. 7119 7120 _Lo Address_ 7121 The address defining the inclusive lower bound of the memory 7122 region. 7123 7124 _Hi Address_ 7125 The address defining the exclusive upper bound of the memory 7126 region. 7127 7128 _Attributes_ 7129 The list of attributes set for this memory region. 7130 7131 10.15.1 Attributes 7132 ------------------ 7133 7134 10.15.1.1 Memory Access Mode 7135 ............................ 7136 7137 The access mode attributes set whether GDB may make read or write 7138 accesses to a memory region. 7139 7140 While these attributes prevent GDB from performing invalid memory 7141 accesses, they do nothing to prevent the target system, I/O DMA, etc. 7142 from accessing memory. 7143 7144 `ro' 7145 Memory is read only. 7146 7147 `wo' 7148 Memory is write only. 7149 7150 `rw' 7151 Memory is read/write. This is the default. 7152 7153 10.15.1.2 Memory Access Size 7154 ............................ 7155 7156 The access size attribute tells GDB to use specific sized accesses in 7157 the memory region. Often memory mapped device registers require 7158 specific sized accesses. If no access size attribute is specified, GDB 7159 may use accesses of any size. 7160 7161 `8' 7162 Use 8 bit memory accesses. 7163 7164 `16' 7165 Use 16 bit memory accesses. 7166 7167 `32' 7168 Use 32 bit memory accesses. 7169 7170 `64' 7171 Use 64 bit memory accesses. 7172 7173 10.15.1.3 Data Cache 7174 .................... 7175 7176 The data cache attributes set whether GDB will cache target memory. 7177 While this generally improves performance by reducing debug protocol 7178 overhead, it can lead to incorrect results because GDB does not know 7179 about volatile variables or memory mapped device registers. 7180 7181 `cache' 7182 Enable GDB to cache target memory. 7183 7184 `nocache' 7185 Disable GDB from caching target memory. This is the default. 7186 7187 10.15.2 Memory Access Checking 7188 ------------------------------ 7189 7190 GDB can be instructed to refuse accesses to memory that is not 7191 explicitly described. This can be useful if accessing such regions has 7192 undesired effects for a specific target, or to provide better error 7193 checking. The following commands control this behaviour. 7194 7195 `set mem inaccessible-by-default [on|off]' 7196 If `on' is specified, make GDB treat memory not explicitly 7197 described by the memory ranges as non-existent and refuse accesses 7198 to such memory. The checks are only performed if there's at least 7199 one memory range defined. If `off' is specified, make GDB treat 7200 the memory not explicitly described by the memory ranges as RAM. 7201 The default value is `on'. 7202 7203 `show mem inaccessible-by-default' 7204 Show the current handling of accesses to unknown memory. 7205 7206 7207 File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data 7208 7209 10.16 Copy Between Memory and a File 7210 ==================================== 7211 7212 You can use the commands `dump', `append', and `restore' to copy data 7213 between target memory and a file. The `dump' and `append' commands 7214 write data to a file, and the `restore' command reads data from a file 7215 back into the inferior's memory. Files may be in binary, Motorola 7216 S-record, Intel hex, or Tektronix Hex format; however, GDB can only 7217 append to binary files. 7218 7219 `dump [FORMAT] memory FILENAME START_ADDR END_ADDR' 7220 `dump [FORMAT] value FILENAME EXPR' 7221 Dump the contents of memory from START_ADDR to END_ADDR, or the 7222 value of EXPR, to FILENAME in the given format. 7223 7224 The FORMAT parameter may be any one of: 7225 `binary' 7226 Raw binary form. 7227 7228 `ihex' 7229 Intel hex format. 7230 7231 `srec' 7232 Motorola S-record format. 7233 7234 `tekhex' 7235 Tektronix Hex format. 7236 7237 GDB uses the same definitions of these formats as the GNU binary 7238 utilities, like `objdump' and `objcopy'. If FORMAT is omitted, 7239 GDB dumps the data in raw binary form. 7240 7241 `append [binary] memory FILENAME START_ADDR END_ADDR' 7242 `append [binary] value FILENAME EXPR' 7243 Append the contents of memory from START_ADDR to END_ADDR, or the 7244 value of EXPR, to the file FILENAME, in raw binary form. (GDB can 7245 only append data to files in raw binary form.) 7246 7247 `restore FILENAME [binary] BIAS START END' 7248 Restore the contents of file FILENAME into memory. The `restore' 7249 command can automatically recognize any known BFD file format, 7250 except for raw binary. To restore a raw binary file you must 7251 specify the optional keyword `binary' after the filename. 7252 7253 If BIAS is non-zero, its value will be added to the addresses 7254 contained in the file. Binary files always start at address zero, 7255 so they will be restored at address BIAS. Other bfd files have a 7256 built-in location; they will be restored at offset BIAS from that 7257 location. 7258 7259 If START and/or END are non-zero, then only data between file 7260 offset START and file offset END will be restored. These offsets 7261 are relative to the addresses in the file, before the BIAS 7262 argument is applied. 7263 7264 7265 7266 File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data 7267 7268 10.17 How to Produce a Core File from Your Program 7269 ================================================== 7270 7271 A "core file" or "core dump" is a file that records the memory image of 7272 a running process and its process status (register values etc.). Its 7273 primary use is post-mortem debugging of a program that crashed while it 7274 ran outside a debugger. A program that crashes automatically produces 7275 a core file, unless this feature is disabled by the user. *Note 7276 Files::, for information on invoking GDB in the post-mortem debugging 7277 mode. 7278 7279 Occasionally, you may wish to produce a core file of the program you 7280 are debugging in order to preserve a snapshot of its state. GDB has a 7281 special command for that. 7282 7283 `generate-core-file [FILE]' 7284 `gcore [FILE]' 7285 Produce a core dump of the inferior process. The optional argument 7286 FILE specifies the file name where to put the core dump. If not 7287 specified, the file name defaults to `core.PID', where PID is the 7288 inferior process ID. 7289 7290 Note that this command is implemented only for some systems (as of 7291 this writing, GNU/Linux, FreeBSD, Solaris, Unixware, and S390). 7292 7293 7294 File: gdb.info, Node: Character Sets, Next: Caching Remote Data, Prev: Core File Generation, Up: Data 7295 7296 10.18 Character Sets 7297 ==================== 7298 7299 If the program you are debugging uses a different character set to 7300 represent characters and strings than the one GDB uses itself, GDB can 7301 automatically translate between the character sets for you. The 7302 character set GDB uses we call the "host character set"; the one the 7303 inferior program uses we call the "target character set". 7304 7305 For example, if you are running GDB on a GNU/Linux system, which 7306 uses the ISO Latin 1 character set, but you are using GDB's remote 7307 protocol (*note Remote Debugging::) to debug a program running on an 7308 IBM mainframe, which uses the EBCDIC character set, then the host 7309 character set is Latin-1, and the target character set is EBCDIC. If 7310 you give GDB the command `set target-charset EBCDIC-US', then GDB 7311 translates between EBCDIC and Latin 1 as you print character or string 7312 values, or use character and string literals in expressions. 7313 7314 GDB has no way to automatically recognize which character set the 7315 inferior program uses; you must tell it, using the `set target-charset' 7316 command, described below. 7317 7318 Here are the commands for controlling GDB's character set support: 7319 7320 `set target-charset CHARSET' 7321 Set the current target character set to CHARSET. To display the 7322 list of supported target character sets, type 7323 `set target-charset <TAB><TAB>'. 7324 7325 `set host-charset CHARSET' 7326 Set the current host character set to CHARSET. 7327 7328 By default, GDB uses a host character set appropriate to the 7329 system it is running on; you can override that default using the 7330 `set host-charset' command. On some systems, GDB cannot 7331 automatically determine the appropriate host character set. In 7332 this case, GDB uses `UTF-8'. 7333 7334 GDB can only use certain character sets as its host character set. 7335 If you type `set target-charset <TAB><TAB>', GDB will list the 7336 host character sets it supports. 7337 7338 `set charset CHARSET' 7339 Set the current host and target character sets to CHARSET. As 7340 above, if you type `set charset <TAB><TAB>', GDB will list the 7341 names of the character sets that can be used for both host and 7342 target. 7343 7344 `show charset' 7345 Show the names of the current host and target character sets. 7346 7347 `show host-charset' 7348 Show the name of the current host character set. 7349 7350 `show target-charset' 7351 Show the name of the current target character set. 7352 7353 `set target-wide-charset CHARSET' 7354 Set the current target's wide character set to CHARSET. This is 7355 the character set used by the target's `wchar_t' type. To display 7356 the list of supported wide character sets, type 7357 `set target-wide-charset <TAB><TAB>'. 7358 7359 `show target-wide-charset' 7360 Show the name of the current target's wide character set. 7361 7362 Here is an example of GDB's character set support in action. Assume 7363 that the following source code has been placed in the file 7364 `charset-test.c': 7365 7366 #include <stdio.h> 7367 7368 char ascii_hello[] 7369 = {72, 101, 108, 108, 111, 44, 32, 119, 7370 111, 114, 108, 100, 33, 10, 0}; 7371 char ibm1047_hello[] 7372 = {200, 133, 147, 147, 150, 107, 64, 166, 7373 150, 153, 147, 132, 90, 37, 0}; 7374 7375 main () 7376 { 7377 printf ("Hello, world!\n"); 7378 } 7379 7380 In this program, `ascii_hello' and `ibm1047_hello' are arrays 7381 containing the string `Hello, world!' followed by a newline, encoded in 7382 the ASCII and IBM1047 character sets. 7383 7384 We compile the program, and invoke the debugger on it: 7385 7386 $ gcc -g charset-test.c -o charset-test 7387 $ gdb -nw charset-test 7388 GNU gdb 2001-12-19-cvs 7389 Copyright 2001 Free Software Foundation, Inc. 7390 ... 7391 (gdb) 7392 7393 We can use the `show charset' command to see what character sets GDB 7394 is currently using to interpret and display characters and strings: 7395 7396 (gdb) show charset 7397 The current host and target character set is `ISO-8859-1'. 7398 (gdb) 7399 7400 For the sake of printing this manual, let's use ASCII as our initial 7401 character set: 7402 (gdb) set charset ASCII 7403 (gdb) show charset 7404 The current host and target character set is `ASCII'. 7405 (gdb) 7406 7407 Let's assume that ASCII is indeed the correct character set for our 7408 host system -- in other words, let's assume that if GDB prints 7409 characters using the ASCII character set, our terminal will display 7410 them properly. Since our current target character set is also ASCII, 7411 the contents of `ascii_hello' print legibly: 7412 7413 (gdb) print ascii_hello 7414 $1 = 0x401698 "Hello, world!\n" 7415 (gdb) print ascii_hello[0] 7416 $2 = 72 'H' 7417 (gdb) 7418 7419 GDB uses the target character set for character and string literals 7420 you use in expressions: 7421 7422 (gdb) print '+' 7423 $3 = 43 '+' 7424 (gdb) 7425 7426 The ASCII character set uses the number 43 to encode the `+' 7427 character. 7428 7429 GDB relies on the user to tell it which character set the target 7430 program uses. If we print `ibm1047_hello' while our target character 7431 set is still ASCII, we get jibberish: 7432 7433 (gdb) print ibm1047_hello 7434 $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" 7435 (gdb) print ibm1047_hello[0] 7436 $5 = 200 '\310' 7437 (gdb) 7438 7439 If we invoke the `set target-charset' followed by <TAB><TAB>, GDB 7440 tells us the character sets it supports: 7441 7442 (gdb) set target-charset 7443 ASCII EBCDIC-US IBM1047 ISO-8859-1 7444 (gdb) set target-charset 7445 7446 We can select IBM1047 as our target character set, and examine the 7447 program's strings again. Now the ASCII string is wrong, but GDB 7448 translates the contents of `ibm1047_hello' from the target character 7449 set, IBM1047, to the host character set, ASCII, and they display 7450 correctly: 7451 7452 (gdb) set target-charset IBM1047 7453 (gdb) show charset 7454 The current host character set is `ASCII'. 7455 The current target character set is `IBM1047'. 7456 (gdb) print ascii_hello 7457 $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" 7458 (gdb) print ascii_hello[0] 7459 $7 = 72 '\110' 7460 (gdb) print ibm1047_hello 7461 $8 = 0x4016a8 "Hello, world!\n" 7462 (gdb) print ibm1047_hello[0] 7463 $9 = 200 'H' 7464 (gdb) 7465 7466 As above, GDB uses the target character set for character and string 7467 literals you use in expressions: 7468 7469 (gdb) print '+' 7470 $10 = 78 '+' 7471 (gdb) 7472 7473 The IBM1047 character set uses the number 78 to encode the `+' 7474 character. 7475 7476 7477 File: gdb.info, Node: Caching Remote Data, Next: Searching Memory, Prev: Character Sets, Up: Data 7478 7479 10.19 Caching Data of Remote Targets 7480 ==================================== 7481 7482 GDB caches data exchanged between the debugger and a remote target 7483 (*note Remote Debugging::). Such caching generally improves 7484 performance, because it reduces the overhead of the remote protocol by 7485 bundling memory reads and writes into large chunks. Unfortunately, 7486 simply caching everything would lead to incorrect results, since GDB 7487 does not necessarily know anything about volatile values, memory-mapped 7488 I/O addresses, etc. Furthermore, in non-stop mode (*note Non-Stop 7489 Mode::) memory can be changed _while_ a gdb command is executing. 7490 Therefore, by default, GDB only caches data known to be on the stack(1). 7491 Other regions of memory can be explicitly marked as cacheable; see 7492 *note Memory Region Attributes::. 7493 7494 `set remotecache on' 7495 `set remotecache off' 7496 This option no longer does anything; it exists for compatibility 7497 with old scripts. 7498 7499 `show remotecache' 7500 Show the current state of the obsolete remotecache flag. 7501 7502 `set stack-cache on' 7503 `set stack-cache off' 7504 Enable or disable caching of stack accesses. When `ON', use 7505 caching. By default, this option is `ON'. 7506 7507 `show stack-cache' 7508 Show the current state of data caching for memory accesses. 7509 7510 `info dcache [line]' 7511 Print the information about the data cache performance. The 7512 information displayed includes the dcache width and depth, and for 7513 each cache line, its number, address, and how many times it was 7514 referenced. This command is useful for debugging the data cache 7515 operation. 7516 7517 If a line number is specified, the contents of that line will be 7518 printed in hex. 7519 7520 ---------- Footnotes ---------- 7521 7522 (1) In non-stop mode, it is moderately rare for a running thread to 7523 modify the stack of a stopped thread in a way that would interfere with 7524 a backtrace, and caching of stack reads provides a significant speed up 7525 of remote backtraces. 7526 7527 7528 File: gdb.info, Node: Searching Memory, Prev: Caching Remote Data, Up: Data 7529 7530 10.20 Search Memory 7531 =================== 7532 7533 Memory can be searched for a particular sequence of bytes with the 7534 `find' command. 7535 7536 `find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]' 7537 `find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]' 7538 Search memory for the sequence of bytes specified by VAL1, VAL2, 7539 etc. The search begins at address START_ADDR and continues for 7540 either LEN bytes or through to END_ADDR inclusive. 7541 7542 S and N are optional parameters. They may be specified in either 7543 order, apart or together. 7544 7545 S, search query size 7546 The size of each search query value. 7547 7548 `b' 7549 bytes 7550 7551 `h' 7552 halfwords (two bytes) 7553 7554 `w' 7555 words (four bytes) 7556 7557 `g' 7558 giant words (eight bytes) 7559 7560 All values are interpreted in the current language. This means, 7561 for example, that if the current source language is C/C++ then 7562 searching for the string "hello" includes the trailing '\0'. 7563 7564 If the value size is not specified, it is taken from the value's 7565 type in the current language. This is useful when one wants to 7566 specify the search pattern as a mixture of types. Note that this 7567 means, for example, that in the case of C-like languages a search 7568 for an untyped 0x42 will search for `(int) 0x42' which is 7569 typically four bytes. 7570 7571 N, maximum number of finds 7572 The maximum number of matches to print. The default is to print 7573 all finds. 7574 7575 You can use strings as search values. Quote them with double-quotes 7576 (`"'). The string value is copied into the search pattern byte by 7577 byte, regardless of the endianness of the target and the size 7578 specification. 7579 7580 The address of each match found is printed as well as a count of the 7581 number of matches found. 7582 7583 The address of the last value found is stored in convenience variable 7584 `$_'. A count of the number of matches is stored in `$numfound'. 7585 7586 For example, if stopped at the `printf' in this function: 7587 7588 void 7589 hello () 7590 { 7591 static char hello[] = "hello-hello"; 7592 static struct { char c; short s; int i; } 7593 __attribute__ ((packed)) mixed 7594 = { 'c', 0x1234, 0x87654321 }; 7595 printf ("%s\n", hello); 7596 } 7597 7598 you get during debugging: 7599 7600 (gdb) find &hello[0], +sizeof(hello), "hello" 7601 0x804956d <hello.1620+6> 7602 1 pattern found 7603 (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' 7604 0x8049567 <hello.1620> 7605 0x804956d <hello.1620+6> 7606 2 patterns found 7607 (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' 7608 0x8049567 <hello.1620> 7609 1 pattern found 7610 (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 7611 0x8049560 <mixed.1625> 7612 1 pattern found 7613 (gdb) print $numfound 7614 $1 = 1 7615 (gdb) print $_ 7616 $2 = (void *) 0x8049560 7617 7618 7619 File: gdb.info, Node: Optimized Code, Next: Macros, Prev: Data, Up: Top 7620 7621 11 Debugging Optimized Code 7622 *************************** 7623 7624 Almost all compilers support optimization. With optimization disabled, 7625 the compiler generates assembly code that corresponds directly to your 7626 source code, in a simplistic way. As the compiler applies more 7627 powerful optimizations, the generated assembly code diverges from your 7628 original source code. With help from debugging information generated 7629 by the compiler, GDB can map from the running program back to 7630 constructs from your original source. 7631 7632 GDB is more accurate with optimization disabled. If you can 7633 recompile without optimization, it is easier to follow the progress of 7634 your program during debugging. But, there are many cases where you may 7635 need to debug an optimized version. 7636 7637 When you debug a program compiled with `-g -O', remember that the 7638 optimizer has rearranged your code; the debugger shows you what is 7639 really there. Do not be too surprised when the execution path does not 7640 exactly match your source file! An extreme example: if you define a 7641 variable, but never use it, GDB never sees that variable--because the 7642 compiler optimizes it out of existence. 7643 7644 Some things do not work as well with `-g -O' as with just `-g', 7645 particularly on machines with instruction scheduling. If in doubt, 7646 recompile with `-g' alone, and if this fixes the problem, please report 7647 it to us as a bug (including a test case!). *Note Variables::, for 7648 more information about debugging optimized code. 7649 7650 * Menu: 7651 7652 * Inline Functions:: How GDB presents inlining 7653 7654 7655 File: gdb.info, Node: Inline Functions, Up: Optimized Code 7656 7657 11.1 Inline Functions 7658 ===================== 7659 7660 "Inlining" is an optimization that inserts a copy of the function body 7661 directly at each call site, instead of jumping to a shared routine. 7662 GDB displays inlined functions just like non-inlined functions. They 7663 appear in backtraces. You can view their arguments and local 7664 variables, step into them with `step', skip them with `next', and 7665 escape from them with `finish'. You can check whether a function was 7666 inlined by using the `info frame' command. 7667 7668 For GDB to support inlined functions, the compiler must record 7669 information about inlining in the debug information -- GCC using the 7670 DWARF 2 format does this, and several other compilers do also. GDB 7671 only supports inlined functions when using DWARF 2. Versions of GCC 7672 before 4.1 do not emit two required attributes (`DW_AT_call_file' and 7673 `DW_AT_call_line'); GDB does not display inlined function calls with 7674 earlier versions of GCC. It instead displays the arguments and local 7675 variables of inlined functions as local variables in the caller. 7676 7677 The body of an inlined function is directly included at its call 7678 site; unlike a non-inlined function, there are no instructions devoted 7679 to the call. GDB still pretends that the call site and the start of 7680 the inlined function are different instructions. Stepping to the call 7681 site shows the call site, and then stepping again shows the first line 7682 of the inlined function, even though no additional instructions are 7683 executed. 7684 7685 This makes source-level debugging much clearer; you can see both the 7686 context of the call and then the effect of the call. Only stepping by 7687 a single instruction using `stepi' or `nexti' does not do this; single 7688 instruction steps always show the inlined body. 7689 7690 There are some ways that GDB does not pretend that inlined function 7691 calls are the same as normal calls: 7692 7693 * You cannot set breakpoints on inlined functions. GDB either 7694 reports that there is no symbol with that name, or else sets the 7695 breakpoint only on non-inlined copies of the function. This 7696 limitation will be removed in a future version of GDB; until then, 7697 set a breakpoint by line number on the first line of the inlined 7698 function instead. 7699 7700 * Setting breakpoints at the call site of an inlined function may not 7701 work, because the call site does not contain any code. GDB may 7702 incorrectly move the breakpoint to the next line of the enclosing 7703 function, after the call. This limitation will be removed in a 7704 future version of GDB; until then, set a breakpoint on an earlier 7705 line or inside the inlined function instead. 7706 7707 * GDB cannot locate the return value of inlined calls after using 7708 the `finish' command. This is a limitation of compiler-generated 7709 debugging information; after `finish', you can step to the next 7710 line and print a variable where your program stored the return 7711 value. 7712 7713 7714 7715 File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Optimized Code, Up: Top 7716 7717 12 C Preprocessor Macros 7718 ************************ 7719 7720 Some languages, such as C and C++, provide a way to define and invoke 7721 "preprocessor macros" which expand into strings of tokens. GDB can 7722 evaluate expressions containing macro invocations, show the result of 7723 macro expansion, and show a macro's definition, including where it was 7724 defined. 7725 7726 You may need to compile your program specially to provide GDB with 7727 information about preprocessor macros. Most compilers do not include 7728 macros in their debugging information, even when you compile with the 7729 `-g' flag. *Note Compilation::. 7730 7731 A program may define a macro at one point, remove that definition 7732 later, and then provide a different definition after that. Thus, at 7733 different points in the program, a macro may have different 7734 definitions, or have no definition at all. If there is a current stack 7735 frame, GDB uses the macros in scope at that frame's source code line. 7736 Otherwise, GDB uses the macros in scope at the current listing location; 7737 see *Note List::. 7738 7739 Whenever GDB evaluates an expression, it always expands any macro 7740 invocations present in the expression. GDB also provides the following 7741 commands for working with macros explicitly. 7742 7743 `macro expand EXPRESSION' 7744 `macro exp EXPRESSION' 7745 Show the results of expanding all preprocessor macro invocations in 7746 EXPRESSION. Since GDB simply expands macros, but does not parse 7747 the result, EXPRESSION need not be a valid expression; it can be 7748 any string of tokens. 7749 7750 `macro expand-once EXPRESSION' 7751 `macro exp1 EXPRESSION' 7752 (This command is not yet implemented.) Show the results of 7753 expanding those preprocessor macro invocations that appear 7754 explicitly in EXPRESSION. Macro invocations appearing in that 7755 expansion are left unchanged. This command allows you to see the 7756 effect of a particular macro more clearly, without being confused 7757 by further expansions. Since GDB simply expands macros, but does 7758 not parse the result, EXPRESSION need not be a valid expression; it 7759 can be any string of tokens. 7760 7761 `info macro MACRO' 7762 Show the definition of the macro named MACRO, and describe the 7763 source location or compiler command-line where that definition was 7764 established. 7765 7766 `macro define MACRO REPLACEMENT-LIST' 7767 `macro define MACRO(ARGLIST) REPLACEMENT-LIST' 7768 Introduce a definition for a preprocessor macro named MACRO, 7769 invocations of which are replaced by the tokens given in 7770 REPLACEMENT-LIST. The first form of this command defines an 7771 "object-like" macro, which takes no arguments; the second form 7772 defines a "function-like" macro, which takes the arguments given in 7773 ARGLIST. 7774 7775 A definition introduced by this command is in scope in every 7776 expression evaluated in GDB, until it is removed with the `macro 7777 undef' command, described below. The definition overrides all 7778 definitions for MACRO present in the program being debugged, as 7779 well as any previous user-supplied definition. 7780 7781 `macro undef MACRO' 7782 Remove any user-supplied definition for the macro named MACRO. 7783 This command only affects definitions provided with the `macro 7784 define' command, described above; it cannot remove definitions 7785 present in the program being debugged. 7786 7787 `macro list' 7788 List all the macros defined using the `macro define' command. 7789 7790 Here is a transcript showing the above commands in action. First, we 7791 show our source files: 7792 7793 $ cat sample.c 7794 #include <stdio.h> 7795 #include "sample.h" 7796 7797 #define M 42 7798 #define ADD(x) (M + x) 7799 7800 main () 7801 { 7802 #define N 28 7803 printf ("Hello, world!\n"); 7804 #undef N 7805 printf ("We're so creative.\n"); 7806 #define N 1729 7807 printf ("Goodbye, world!\n"); 7808 } 7809 $ cat sample.h 7810 #define Q < 7811 $ 7812 7813 Now, we compile the program using the GNU C compiler, GCC. We pass 7814 the `-gdwarf-2' and `-g3' flags to ensure the compiler includes 7815 information about preprocessor macros in the debugging information. 7816 7817 $ gcc -gdwarf-2 -g3 sample.c -o sample 7818 $ 7819 7820 Now, we start GDB on our sample program: 7821 7822 $ gdb -nw sample 7823 GNU gdb 2002-05-06-cvs 7824 Copyright 2002 Free Software Foundation, Inc. 7825 GDB is free software, ... 7826 (gdb) 7827 7828 We can expand macros and examine their definitions, even when the 7829 program is not running. GDB uses the current listing position to 7830 decide which macro definitions are in scope: 7831 7832 (gdb) list main 7833 3 7834 4 #define M 42 7835 5 #define ADD(x) (M + x) 7836 6 7837 7 main () 7838 8 { 7839 9 #define N 28 7840 10 printf ("Hello, world!\n"); 7841 11 #undef N 7842 12 printf ("We're so creative.\n"); 7843 (gdb) info macro ADD 7844 Defined at /home/jimb/gdb/macros/play/sample.c:5 7845 #define ADD(x) (M + x) 7846 (gdb) info macro Q 7847 Defined at /home/jimb/gdb/macros/play/sample.h:1 7848 included at /home/jimb/gdb/macros/play/sample.c:2 7849 #define Q < 7850 (gdb) macro expand ADD(1) 7851 expands to: (42 + 1) 7852 (gdb) macro expand-once ADD(1) 7853 expands to: once (M + 1) 7854 (gdb) 7855 7856 In the example above, note that `macro expand-once' expands only the 7857 macro invocation explicit in the original text -- the invocation of 7858 `ADD' -- but does not expand the invocation of the macro `M', which was 7859 introduced by `ADD'. 7860 7861 Once the program is running, GDB uses the macro definitions in force 7862 at the source line of the current stack frame: 7863 7864 (gdb) break main 7865 Breakpoint 1 at 0x8048370: file sample.c, line 10. 7866 (gdb) run 7867 Starting program: /home/jimb/gdb/macros/play/sample 7868 7869 Breakpoint 1, main () at sample.c:10 7870 10 printf ("Hello, world!\n"); 7871 (gdb) 7872 7873 At line 10, the definition of the macro `N' at line 9 is in force: 7874 7875 (gdb) info macro N 7876 Defined at /home/jimb/gdb/macros/play/sample.c:9 7877 #define N 28 7878 (gdb) macro expand N Q M 7879 expands to: 28 < 42 7880 (gdb) print N Q M 7881 $1 = 1 7882 (gdb) 7883 7884 As we step over directives that remove `N''s definition, and then 7885 give it a new definition, GDB finds the definition (or lack thereof) in 7886 force at each point: 7887 7888 (gdb) next 7889 Hello, world! 7890 12 printf ("We're so creative.\n"); 7891 (gdb) info macro N 7892 The symbol `N' has no definition as a C/C++ preprocessor macro 7893 at /home/jimb/gdb/macros/play/sample.c:12 7894 (gdb) next 7895 We're so creative. 7896 14 printf ("Goodbye, world!\n"); 7897 (gdb) info macro N 7898 Defined at /home/jimb/gdb/macros/play/sample.c:13 7899 #define N 1729 7900 (gdb) macro expand N Q M 7901 expands to: 1729 < 42 7902 (gdb) print N Q M 7903 $2 = 0 7904 (gdb) 7905 7906 In addition to source files, macros can be defined on the 7907 compilation command line using the `-DNAME=VALUE' syntax. For macros 7908 defined in such a way, GDB displays the location of their definition as 7909 line zero of the source file submitted to the compiler. 7910 7911 (gdb) info macro __STDC__ 7912 Defined at /home/jimb/gdb/macros/play/sample.c:0 7913 -D__STDC__=1 7914 (gdb) 7915 7916 7917 File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top 7918 7919 13 Tracepoints 7920 ************** 7921 7922 In some applications, it is not feasible for the debugger to interrupt 7923 the program's execution long enough for the developer to learn anything 7924 helpful about its behavior. If the program's correctness depends on 7925 its real-time behavior, delays introduced by a debugger might cause the 7926 program to change its behavior drastically, or perhaps fail, even when 7927 the code itself is correct. It is useful to be able to observe the 7928 program's behavior without interrupting it. 7929 7930 Using GDB's `trace' and `collect' commands, you can specify 7931 locations in the program, called "tracepoints", and arbitrary 7932 expressions to evaluate when those tracepoints are reached. Later, 7933 using the `tfind' command, you can examine the values those expressions 7934 had when the program hit the tracepoints. The expressions may also 7935 denote objects in memory--structures or arrays, for example--whose 7936 values GDB should record; while visiting a particular tracepoint, you 7937 may inspect those objects as if they were in memory at that moment. 7938 However, because GDB records these values without interacting with you, 7939 it can do so quickly and unobtrusively, hopefully not disturbing the 7940 program's behavior. 7941 7942 The tracepoint facility is currently available only for remote 7943 targets. *Note Targets::. In addition, your remote target must know 7944 how to collect trace data. This functionality is implemented in the 7945 remote stub; however, none of the stubs distributed with GDB support 7946 tracepoints as of this writing. The format of the remote packets used 7947 to implement tracepoints are described in *Note Tracepoint Packets::. 7948 7949 It is also possible to get trace data from a file, in a manner 7950 reminiscent of corefiles; you specify the filename, and use `tfind' to 7951 search through the file. *Note Trace Files::, for more details. 7952 7953 This chapter describes the tracepoint commands and features. 7954 7955 * Menu: 7956 7957 * Set Tracepoints:: 7958 * Analyze Collected Data:: 7959 * Tracepoint Variables:: 7960 * Trace Files:: 7961 7962 7963 File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints 7964 7965 13.1 Commands to Set Tracepoints 7966 ================================ 7967 7968 Before running such a "trace experiment", an arbitrary number of 7969 tracepoints can be set. A tracepoint is actually a special type of 7970 breakpoint (*note Set Breaks::), so you can manipulate it using 7971 standard breakpoint commands. For instance, as with breakpoints, 7972 tracepoint numbers are successive integers starting from one, and many 7973 of the commands associated with tracepoints take the tracepoint number 7974 as their argument, to identify which tracepoint to work on. 7975 7976 For each tracepoint, you can specify, in advance, some arbitrary set 7977 of data that you want the target to collect in the trace buffer when it 7978 hits that tracepoint. The collected data can include registers, local 7979 variables, or global data. Later, you can use GDB commands to examine 7980 the values these data had at the time the tracepoint was hit. 7981 7982 Tracepoints do not support every breakpoint feature. Conditional 7983 expressions and ignore counts on tracepoints have no effect, and 7984 tracepoints cannot run GDB commands when they are hit. Tracepoints may 7985 not be thread-specific either. 7986 7987 Some targets may support "fast tracepoints", which are inserted in a 7988 different way (such as with a jump instead of a trap), that is faster 7989 but possibly restricted in where they may be installed. 7990 7991 This section describes commands to set tracepoints and associated 7992 conditions and actions. 7993 7994 * Menu: 7995 7996 * Create and Delete Tracepoints:: 7997 * Enable and Disable Tracepoints:: 7998 * Tracepoint Passcounts:: 7999 * Tracepoint Conditions:: 8000 * Trace State Variables:: 8001 * Tracepoint Actions:: 8002 * Listing Tracepoints:: 8003 * Starting and Stopping Trace Experiments:: 8004 8005 8006 File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints 8007 8008 13.1.1 Create and Delete Tracepoints 8009 ------------------------------------ 8010 8011 `trace LOCATION' 8012 The `trace' command is very similar to the `break' command. Its 8013 argument LOCATION can be a source line, a function name, or an 8014 address in the target program. *Note Specify Location::. The 8015 `trace' command defines a tracepoint, which is a point in the 8016 target program where the debugger will briefly stop, collect some 8017 data, and then allow the program to continue. Setting a 8018 tracepoint or changing its actions doesn't take effect until the 8019 next `tstart' command, and once a trace experiment is running, 8020 further changes will not have any effect until the next trace 8021 experiment starts. 8022 8023 Here are some examples of using the `trace' command: 8024 8025 (gdb) trace foo.c:121 // a source file and line number 8026 8027 (gdb) trace +2 // 2 lines forward 8028 8029 (gdb) trace my_function // first source line of function 8030 8031 (gdb) trace *my_function // EXACT start address of function 8032 8033 (gdb) trace *0x2117c4 // an address 8034 8035 You can abbreviate `trace' as `tr'. 8036 8037 `trace LOCATION if COND' 8038 Set a tracepoint with condition COND; evaluate the expression COND 8039 each time the tracepoint is reached, and collect data only if the 8040 value is nonzero--that is, if COND evaluates as true. *Note 8041 Tracepoint Conditions: Tracepoint Conditions, for more information 8042 on tracepoint conditions. 8043 8044 `ftrace LOCATION [ if COND ]' 8045 The `ftrace' command sets a fast tracepoint. For targets that 8046 support them, fast tracepoints will use a more efficient but 8047 possibly less general technique to trigger data collection, such 8048 as a jump instruction instead of a trap, or some sort of hardware 8049 support. It may not be possible to create a fast tracepoint at 8050 the desired location, in which case the command will exit with an 8051 explanatory message. 8052 8053 GDB handles arguments to `ftrace' exactly as for `trace'. 8054 8055 The convenience variable `$tpnum' records the tracepoint number of 8056 the most recently set tracepoint. 8057 8058 `delete tracepoint [NUM]' 8059 Permanently delete one or more tracepoints. With no argument, the 8060 default is to delete all tracepoints. Note that the regular 8061 `delete' command can remove tracepoints also. 8062 8063 Examples: 8064 8065 (gdb) delete trace 1 2 3 // remove three tracepoints 8066 8067 (gdb) delete trace // remove all tracepoints 8068 8069 You can abbreviate this command as `del tr'. 8070 8071 8072 File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints 8073 8074 13.1.2 Enable and Disable Tracepoints 8075 ------------------------------------- 8076 8077 These commands are deprecated; they are equivalent to plain `disable' 8078 and `enable'. 8079 8080 `disable tracepoint [NUM]' 8081 Disable tracepoint NUM, or all tracepoints if no argument NUM is 8082 given. A disabled tracepoint will have no effect during the next 8083 trace experiment, but it is not forgotten. You can re-enable a 8084 disabled tracepoint using the `enable tracepoint' command. 8085 8086 `enable tracepoint [NUM]' 8087 Enable tracepoint NUM, or all tracepoints. The enabled 8088 tracepoints will become effective the next time a trace experiment 8089 is run. 8090 8091 8092 File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Conditions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints 8093 8094 13.1.3 Tracepoint Passcounts 8095 ---------------------------- 8096 8097 `passcount [N [NUM]]' 8098 Set the "passcount" of a tracepoint. The passcount is a way to 8099 automatically stop a trace experiment. If a tracepoint's 8100 passcount is N, then the trace experiment will be automatically 8101 stopped on the N'th time that tracepoint is hit. If the 8102 tracepoint number NUM is not specified, the `passcount' command 8103 sets the passcount of the most recently defined tracepoint. If no 8104 passcount is given, the trace experiment will run until stopped 8105 explicitly by the user. 8106 8107 Examples: 8108 8109 (gdb) passcount 5 2 // Stop on the 5th execution of 8110 `// tracepoint 2' 8111 8112 (gdb) passcount 12 // Stop on the 12th execution of the 8113 `// most recently defined tracepoint.' 8114 (gdb) trace foo 8115 (gdb) pass 3 8116 (gdb) trace bar 8117 (gdb) pass 2 8118 (gdb) trace baz 8119 (gdb) pass 1 // Stop tracing when foo has been 8120 `// executed 3 times OR when bar has' 8121 `// been executed 2 times' 8122 `// OR when baz has been executed 1 time.' 8123 8124 8125 8126 File: gdb.info, Node: Tracepoint Conditions, Next: Trace State Variables, Prev: Tracepoint Passcounts, Up: Set Tracepoints 8127 8128 13.1.4 Tracepoint Conditions 8129 ---------------------------- 8130 8131 The simplest sort of tracepoint collects data every time your program 8132 reaches a specified place. You can also specify a "condition" for a 8133 tracepoint. A condition is just a Boolean expression in your 8134 programming language (*note Expressions: Expressions.). A tracepoint 8135 with a condition evaluates the expression each time your program 8136 reaches it, and data collection happens only if the condition is true. 8137 8138 Tracepoint conditions can be specified when a tracepoint is set, by 8139 using `if' in the arguments to the `trace' command. *Note Setting 8140 Tracepoints: Create and Delete Tracepoints. They can also be set or 8141 changed at any time with the `condition' command, just as with 8142 breakpoints. 8143 8144 Unlike breakpoint conditions, GDB does not actually evaluate the 8145 conditional expression itself. Instead, GDB encodes the expression 8146 into an agent expression (*note Agent Expressions:: suitable for 8147 execution on the target, independently of GDB. Global variables become 8148 raw memory locations, locals become stack accesses, and so forth. 8149 8150 For instance, suppose you have a function that is usually called 8151 frequently, but should not be called after an error has occurred. You 8152 could use the following tracepoint command to collect data about calls 8153 of that function that happen while the error code is propagating 8154 through the program; an unconditional tracepoint could end up 8155 collecting thousands of useless trace frames that you would have to 8156 search through. 8157 8158 (gdb) trace normal_operation if errcode > 0 8159 8160 8161 File: gdb.info, Node: Trace State Variables, Next: Tracepoint Actions, Prev: Tracepoint Conditions, Up: Set Tracepoints 8162 8163 13.1.5 Trace State Variables 8164 ---------------------------- 8165 8166 A "trace state variable" is a special type of variable that is created 8167 and managed by target-side code. The syntax is the same as that for 8168 GDB's convenience variables (a string prefixed with "$"), but they are 8169 stored on the target. They must be created explicitly, using a 8170 `tvariable' command. They are always 64-bit signed integers. 8171 8172 Trace state variables are remembered by GDB, and downloaded to the 8173 target along with tracepoint information when the trace experiment 8174 starts. There are no intrinsic limits on the number of trace state 8175 variables, beyond memory limitations of the target. 8176 8177 Although trace state variables are managed by the target, you can use 8178 them in print commands and expressions as if they were convenience 8179 variables; GDB will get the current value from the target while the 8180 trace experiment is running. Trace state variables share the same 8181 namespace as other "$" variables, which means that you cannot have 8182 trace state variables with names like `$23' or `$pc', nor can you have 8183 a trace state variable and a convenience variable with the same name. 8184 8185 `tvariable $NAME [ = EXPRESSION ]' 8186 The `tvariable' command creates a new trace state variable named 8187 `$NAME', and optionally gives it an initial value of EXPRESSION. 8188 EXPRESSION is evaluated when this command is entered; the result 8189 will be converted to an integer if possible, otherwise GDB will 8190 report an error. A subsequent `tvariable' command specifying the 8191 same name does not create a variable, but instead assigns the 8192 supplied initial value to the existing variable of that name, 8193 overwriting any previous initial value. The default initial value 8194 is 0. 8195 8196 `info tvariables' 8197 List all the trace state variables along with their initial values. 8198 Their current values may also be displayed, if the trace 8199 experiment is currently running. 8200 8201 `delete tvariable [ $NAME ... ]' 8202 Delete the given trace state variables, or all of them if no 8203 arguments are specified. 8204 8205 8206 8207 File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Trace State Variables, Up: Set Tracepoints 8208 8209 13.1.6 Tracepoint Action Lists 8210 ------------------------------ 8211 8212 `actions [NUM]' 8213 This command will prompt for a list of actions to be taken when the 8214 tracepoint is hit. If the tracepoint number NUM is not specified, 8215 this command sets the actions for the one that was most recently 8216 defined (so that you can define a tracepoint and then say 8217 `actions' without bothering about its number). You specify the 8218 actions themselves on the following lines, one action at a time, 8219 and terminate the actions list with a line containing just `end'. 8220 So far, the only defined actions are `collect' and 8221 `while-stepping'. 8222 8223 To remove all actions from a tracepoint, type `actions NUM' and 8224 follow it immediately with `end'. 8225 8226 (gdb) collect DATA // collect some data 8227 8228 (gdb) while-stepping 5 // single-step 5 times, collect data 8229 8230 (gdb) end // signals the end of actions. 8231 8232 In the following example, the action list begins with `collect' 8233 commands indicating the things to be collected when the tracepoint 8234 is hit. Then, in order to single-step and collect additional data 8235 following the tracepoint, a `while-stepping' command is used, 8236 followed by the list of things to be collected while stepping. The 8237 `while-stepping' command is terminated by its own separate `end' 8238 command. Lastly, the action list is terminated by an `end' 8239 command. 8240 8241 (gdb) trace foo 8242 (gdb) actions 8243 Enter actions for tracepoint 1, one per line: 8244 > collect bar,baz 8245 > collect $regs 8246 > while-stepping 12 8247 > collect $fp, $sp 8248 > end 8249 end 8250 8251 `collect EXPR1, EXPR2, ...' 8252 Collect values of the given expressions when the tracepoint is hit. 8253 This command accepts a comma-separated list of any valid 8254 expressions. In addition to global, static, or local variables, 8255 the following special arguments are supported: 8256 8257 `$regs' 8258 collect all registers 8259 8260 `$args' 8261 collect all function arguments 8262 8263 `$locals' 8264 collect all local variables. 8265 8266 You can give several consecutive `collect' commands, each one with 8267 a single argument, or one `collect' command with several arguments 8268 separated by commas: the effect is the same. 8269 8270 The command `info scope' (*note info scope: Symbols.) is 8271 particularly useful for figuring out what data to collect. 8272 8273 `teval EXPR1, EXPR2, ...' 8274 Evaluate the given expressions when the tracepoint is hit. This 8275 command accepts a comma-separated list of expressions. The results 8276 are discarded, so this is mainly useful for assigning values to 8277 trace state variables (*note Trace State Variables::) without 8278 adding those values to the trace buffer, as would be the case if 8279 the `collect' action were used. 8280 8281 `while-stepping N' 8282 Perform N single-step traces after the tracepoint, collecting new 8283 data at each step. The `while-stepping' command is followed by 8284 the list of what to collect while stepping (followed by its own 8285 `end' command): 8286 8287 > while-stepping 12 8288 > collect $regs, myglobal 8289 > end 8290 > 8291 8292 You may abbreviate `while-stepping' as `ws' or `stepping'. 8293 8294 `set default-collect EXPR1, EXPR2, ...' 8295 This variable is a list of expressions to collect at each 8296 tracepoint hit. It is effectively an additional `collect' action 8297 prepended to every tracepoint action list. The expressions are 8298 parsed individually for each tracepoint, so for instance a 8299 variable named `xyz' may be interpreted as a global for one 8300 tracepoint, and a local for another, as appropriate to the 8301 tracepoint's location. 8302 8303 `show default-collect' 8304 Show the list of expressions that are collected by default at each 8305 tracepoint hit. 8306 8307 8308 8309 File: gdb.info, Node: Listing Tracepoints, Next: Starting and Stopping Trace Experiments, Prev: Tracepoint Actions, Up: Set Tracepoints 8310 8311 13.1.7 Listing Tracepoints 8312 -------------------------- 8313 8314 `info tracepoints [NUM]' 8315 Display information about the tracepoint NUM. If you don't 8316 specify a tracepoint number, displays information about all the 8317 tracepoints defined so far. The format is similar to that used for 8318 `info breakpoints'; in fact, `info tracepoints' is the same 8319 command, simply restricting itself to tracepoints. 8320 8321 A tracepoint's listing may include additional information specific 8322 to tracing: 8323 8324 * its passcount as given by the `passcount N' command 8325 8326 * its step count as given by the `while-stepping N' command 8327 8328 * its action list as given by the `actions' command. The 8329 actions are prefixed with an `A' so as to distinguish them 8330 from commands. 8331 8332 (gdb) info trace 8333 Num Type Disp Enb Address What 8334 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 8335 pass count 1200 8336 step count 20 8337 A while-stepping 20 8338 A collect globfoo, $regs 8339 A end 8340 A collect globfoo2 8341 A end 8342 (gdb) 8343 8344 This command can be abbreviated `info tp'. 8345 8346 8347 File: gdb.info, Node: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints 8348 8349 13.1.8 Starting and Stopping Trace Experiments 8350 ---------------------------------------------- 8351 8352 `tstart' 8353 This command takes no arguments. It starts the trace experiment, 8354 and begins collecting data. This has the side effect of 8355 discarding all the data collected in the trace buffer during the 8356 previous trace experiment. 8357 8358 `tstop' 8359 This command takes no arguments. It ends the trace experiment, and 8360 stops collecting data. 8361 8362 *Note*: a trace experiment and data collection may stop 8363 automatically if any tracepoint's passcount is reached (*note 8364 Tracepoint Passcounts::), or if the trace buffer becomes full. 8365 8366 `tstatus' 8367 This command displays the status of the current trace data 8368 collection. 8369 8370 Here is an example of the commands we described so far: 8371 8372 (gdb) trace gdb_c_test 8373 (gdb) actions 8374 Enter actions for tracepoint #1, one per line. 8375 > collect $regs,$locals,$args 8376 > while-stepping 11 8377 > collect $regs 8378 > end 8379 > end 8380 (gdb) tstart 8381 [time passes ...] 8382 (gdb) tstop 8383 8384 You can choose to continue running the trace experiment even if GDB 8385 disconnects from the target, voluntarily or involuntarily. For 8386 commands such as `detach', the debugger will ask what you want to do 8387 with the trace. But for unexpected terminations (GDB crash, network 8388 outage), it would be unfortunate to lose hard-won trace data, so the 8389 variable `disconnected-tracing' lets you decide whether the trace should 8390 continue running without GDB. 8391 8392 `set disconnected-tracing on' 8393 `set disconnected-tracing off' 8394 Choose whether a tracing run should continue to run if GDB has 8395 disconnected from the target. Note that `detach' or `quit' will 8396 ask you directly what to do about a running trace no matter what 8397 this variable's setting, so the variable is mainly useful for 8398 handling unexpected situations, such as loss of the network. 8399 8400 `show disconnected-tracing' 8401 Show the current choice for disconnected tracing. 8402 8403 8404 When you reconnect to the target, the trace experiment may or may not 8405 still be running; it might have filled the trace buffer in the 8406 meantime, or stopped for one of the other reasons. If it is running, 8407 it will continue after reconnection. 8408 8409 Upon reconnection, the target will upload information about the 8410 tracepoints in effect. GDB will then compare that information to the 8411 set of tracepoints currently defined, and attempt to match them up, 8412 allowing for the possibility that the numbers may have changed due to 8413 creation and deletion in the meantime. If one of the target's 8414 tracepoints does not match any in GDB, the debugger will create a new 8415 tracepoint, so that you have a number with which to specify that 8416 tracepoint. This matching-up process is necessarily heuristic, and it 8417 may result in useless tracepoints being created; you may simply delete 8418 them if they are of no use. 8419 8420 8421 File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints 8422 8423 13.2 Using the Collected Data 8424 ============================= 8425 8426 After the tracepoint experiment ends, you use GDB commands for 8427 examining the trace data. The basic idea is that each tracepoint 8428 collects a trace "snapshot" every time it is hit and another snapshot 8429 every time it single-steps. All these snapshots are consecutively 8430 numbered from zero and go into a buffer, and you can examine them 8431 later. The way you examine them is to "focus" on a specific trace 8432 snapshot. When the remote stub is focused on a trace snapshot, it will 8433 respond to all GDB requests for memory and registers by reading from 8434 the buffer which belongs to that snapshot, rather than from _real_ 8435 memory or registers of the program being debugged. This means that 8436 *all* GDB commands (`print', `info registers', `backtrace', etc.) will 8437 behave as if we were currently debugging the program state as it was 8438 when the tracepoint occurred. Any requests for data that are not in 8439 the buffer will fail. 8440 8441 * Menu: 8442 8443 * tfind:: How to select a trace snapshot 8444 * tdump:: How to display all data for a snapshot 8445 * save-tracepoints:: How to save tracepoints for a future run 8446 8447 8448 File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data 8449 8450 13.2.1 `tfind N' 8451 ---------------- 8452 8453 The basic command for selecting a trace snapshot from the buffer is 8454 `tfind N', which finds trace snapshot number N, counting from zero. If 8455 no argument N is given, the next snapshot is selected. 8456 8457 Here are the various forms of using the `tfind' command. 8458 8459 `tfind start' 8460 Find the first snapshot in the buffer. This is a synonym for 8461 `tfind 0' (since 0 is the number of the first snapshot). 8462 8463 `tfind none' 8464 Stop debugging trace snapshots, resume _live_ debugging. 8465 8466 `tfind end' 8467 Same as `tfind none'. 8468 8469 `tfind' 8470 No argument means find the next trace snapshot. 8471 8472 `tfind -' 8473 Find the previous trace snapshot before the current one. This 8474 permits retracing earlier steps. 8475 8476 `tfind tracepoint NUM' 8477 Find the next snapshot associated with tracepoint NUM. Search 8478 proceeds forward from the last examined trace snapshot. If no 8479 argument NUM is given, it means find the next snapshot collected 8480 for the same tracepoint as the current snapshot. 8481 8482 `tfind pc ADDR' 8483 Find the next snapshot associated with the value ADDR of the 8484 program counter. Search proceeds forward from the last examined 8485 trace snapshot. If no argument ADDR is given, it means find the 8486 next snapshot with the same value of PC as the current snapshot. 8487 8488 `tfind outside ADDR1, ADDR2' 8489 Find the next snapshot whose PC is outside the given range of 8490 addresses (exclusive). 8491 8492 `tfind range ADDR1, ADDR2' 8493 Find the next snapshot whose PC is between ADDR1 and ADDR2 8494 (inclusive). 8495 8496 `tfind line [FILE:]N' 8497 Find the next snapshot associated with the source line N. If the 8498 optional argument FILE is given, refer to line N in that source 8499 file. Search proceeds forward from the last examined trace 8500 snapshot. If no argument N is given, it means find the next line 8501 other than the one currently being examined; thus saying `tfind 8502 line' repeatedly can appear to have the same effect as stepping 8503 from line to line in a _live_ debugging session. 8504 8505 The default arguments for the `tfind' commands are specifically 8506 designed to make it easy to scan through the trace buffer. For 8507 instance, `tfind' with no argument selects the next trace snapshot, and 8508 `tfind -' with no argument selects the previous trace snapshot. So, by 8509 giving one `tfind' command, and then simply hitting <RET> repeatedly 8510 you can examine all the trace snapshots in order. Or, by saying `tfind 8511 -' and then hitting <RET> repeatedly you can examine the snapshots in 8512 reverse order. The `tfind line' command with no argument selects the 8513 snapshot for the next source line executed. The `tfind pc' command with 8514 no argument selects the next snapshot with the same program counter 8515 (PC) as the current frame. The `tfind tracepoint' command with no 8516 argument selects the next trace snapshot collected by the same 8517 tracepoint as the current one. 8518 8519 In addition to letting you scan through the trace buffer manually, 8520 these commands make it easy to construct GDB scripts that scan through 8521 the trace buffer and print out whatever collected data you are 8522 interested in. Thus, if we want to examine the PC, FP, and SP 8523 registers from each trace frame in the buffer, we can say this: 8524 8525 (gdb) tfind start 8526 (gdb) while ($trace_frame != -1) 8527 > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ 8528 $trace_frame, $pc, $sp, $fp 8529 > tfind 8530 > end 8531 8532 Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 8533 Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 8534 Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 8535 Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 8536 Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 8537 Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 8538 Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 8539 Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 8540 Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 8541 Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 8542 Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 8543 8544 Or, if we want to examine the variable `X' at each source line in 8545 the buffer: 8546 8547 (gdb) tfind start 8548 (gdb) while ($trace_frame != -1) 8549 > printf "Frame %d, X == %d\n", $trace_frame, X 8550 > tfind line 8551 > end 8552 8553 Frame 0, X = 1 8554 Frame 7, X = 2 8555 Frame 13, X = 255 8556 8557 8558 File: gdb.info, Node: tdump, Next: save-tracepoints, Prev: tfind, Up: Analyze Collected Data 8559 8560 13.2.2 `tdump' 8561 -------------- 8562 8563 This command takes no arguments. It prints all the data collected at 8564 the current trace snapshot. 8565 8566 (gdb) trace 444 8567 (gdb) actions 8568 Enter actions for tracepoint #2, one per line: 8569 > collect $regs, $locals, $args, gdb_long_test 8570 > end 8571 8572 (gdb) tstart 8573 8574 (gdb) tfind line 444 8575 #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) 8576 at gdb_test.c:444 8577 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) 8578 8579 (gdb) tdump 8580 Data collected at tracepoint 2, trace frame 1: 8581 d0 0xc4aa0085 -995491707 8582 d1 0x18 24 8583 d2 0x80 128 8584 d3 0x33 51 8585 d4 0x71aea3d 119204413 8586 d5 0x22 34 8587 d6 0xe0 224 8588 d7 0x380035 3670069 8589 a0 0x19e24a 1696330 8590 a1 0x3000668 50333288 8591 a2 0x100 256 8592 a3 0x322000 3284992 8593 a4 0x3000698 50333336 8594 a5 0x1ad3cc 1758156 8595 fp 0x30bf3c 0x30bf3c 8596 sp 0x30bf34 0x30bf34 8597 ps 0x0 0 8598 pc 0x20b2c8 0x20b2c8 8599 fpcontrol 0x0 0 8600 fpstatus 0x0 0 8601 fpiaddr 0x0 0 8602 p = 0x20e5b4 "gdb-test" 8603 p1 = (void *) 0x11 8604 p2 = (void *) 0x22 8605 p3 = (void *) 0x33 8606 p4 = (void *) 0x44 8607 p5 = (void *) 0x55 8608 p6 = (void *) 0x66 8609 gdb_long_test = 17 '\021' 8610 8611 (gdb) 8612 8613 8614 File: gdb.info, Node: save-tracepoints, Prev: tdump, Up: Analyze Collected Data 8615 8616 13.2.3 `save-tracepoints FILENAME' 8617 ---------------------------------- 8618 8619 This command saves all current tracepoint definitions together with 8620 their actions and passcounts, into a file `FILENAME' suitable for use 8621 in a later debugging session. To read the saved tracepoint 8622 definitions, use the `source' command (*note Command Files::). 8623 8624 8625 File: gdb.info, Node: Tracepoint Variables, Next: Trace Files, Prev: Analyze Collected Data, Up: Tracepoints 8626 8627 13.3 Convenience Variables for Tracepoints 8628 ========================================== 8629 8630 `(int) $trace_frame' 8631 The current trace snapshot (a.k.a. "frame") number, or -1 if no 8632 snapshot is selected. 8633 8634 `(int) $tracepoint' 8635 The tracepoint for the current trace snapshot. 8636 8637 `(int) $trace_line' 8638 The line number for the current trace snapshot. 8639 8640 `(char []) $trace_file' 8641 The source file for the current trace snapshot. 8642 8643 `(char []) $trace_func' 8644 The name of the function containing `$tracepoint'. 8645 8646 Note: `$trace_file' is not suitable for use in `printf', use 8647 `output' instead. 8648 8649 Here's a simple example of using these convenience variables for 8650 stepping through all the trace snapshots and printing some of their 8651 data. Note that these are not the same as trace state variables, which 8652 are managed by the target. 8653 8654 (gdb) tfind start 8655 8656 (gdb) while $trace_frame != -1 8657 > output $trace_file 8658 > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint 8659 > tfind 8660 > end 8661 8662 8663 File: gdb.info, Node: Trace Files, Prev: Tracepoint Variables, Up: Tracepoints 8664 8665 13.4 Using Trace Files 8666 ====================== 8667 8668 In some situations, the target running a trace experiment may no longer 8669 be available; perhaps it crashed, or the hardware was needed for a 8670 different activity. To handle these cases, you can arrange to dump the 8671 trace data into a file, and later use that file as a source of trace 8672 data, via the `target tfile' command. 8673 8674 `tsave [ -r ] FILENAME' 8675 Save the trace data to FILENAME. By default, this command assumes 8676 that FILENAME refers to the host filesystem, so if necessary GDB 8677 will copy raw trace data up from the target and then save it. If 8678 the target supports it, you can also supply the optional argument 8679 `-r' ("remote") to direct the target to save the data directly 8680 into FILENAME in its own filesystem, which may be more efficient 8681 if the trace buffer is very large. (Note, however, that `target 8682 tfile' can only read from files accessible to the host.) 8683 8684 `target tfile FILENAME' 8685 Use the file named FILENAME as a source of trace data. Commands 8686 that examine data work as they do with a live target, but it is not 8687 possible to run any new trace experiments. `tstatus' will report 8688 the state of the trace run at the moment the data was saved, as 8689 well as the current trace frame you are examining. FILENAME must 8690 be on a filesystem accessible to the host. 8691 8692 8693 8694 File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top 8695 8696 14 Debugging Programs That Use Overlays 8697 *************************************** 8698 8699 If your program is too large to fit completely in your target system's 8700 memory, you can sometimes use "overlays" to work around this problem. 8701 GDB provides some support for debugging programs that use overlays. 8702 8703 * Menu: 8704 8705 * How Overlays Work:: A general explanation of overlays. 8706 * Overlay Commands:: Managing overlays in GDB. 8707 * Automatic Overlay Debugging:: GDB can find out which overlays are 8708 mapped by asking the inferior. 8709 * Overlay Sample Program:: A sample program using overlays. 8710 8711 8712 File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays 8713 8714 14.1 How Overlays Work 8715 ====================== 8716 8717 Suppose you have a computer whose instruction address space is only 64 8718 kilobytes long, but which has much more memory which can be accessed by 8719 other means: special instructions, segment registers, or memory 8720 management hardware, for example. Suppose further that you want to 8721 adapt a program which is larger than 64 kilobytes to run on this system. 8722 8723 One solution is to identify modules of your program which are 8724 relatively independent, and need not call each other directly; call 8725 these modules "overlays". Separate the overlays from the main program, 8726 and place their machine code in the larger memory. Place your main 8727 program in instruction memory, but leave at least enough space there to 8728 hold the largest overlay as well. 8729 8730 Now, to call a function located in an overlay, you must first copy 8731 that overlay's machine code from the large memory into the space set 8732 aside for it in the instruction memory, and then jump to its entry point 8733 there. 8734 8735 Data Instruction Larger 8736 Address Space Address Space Address Space 8737 +-----------+ +-----------+ +-----------+ 8738 | | | | | | 8739 +-----------+ +-----------+ +-----------+<-- overlay 1 8740 | program | | main | .----| overlay 1 | load address 8741 | variables | | program | | +-----------+ 8742 | and heap | | | | | | 8743 +-----------+ | | | +-----------+<-- overlay 2 8744 | | +-----------+ | | | load address 8745 +-----------+ | | | .-| overlay 2 | 8746 | | | | | | 8747 mapped --->+-----------+ | | +-----------+ 8748 address | | | | | | 8749 | overlay | <-' | | | 8750 | area | <---' +-----------+<-- overlay 3 8751 | | <---. | | load address 8752 +-----------+ `--| overlay 3 | 8753 | | | | 8754 +-----------+ | | 8755 +-----------+ 8756 | | 8757 +-----------+ 8758 8759 A code overlay 8760 8761 The diagram (*note A code overlay::) shows a system with separate 8762 data and instruction address spaces. To map an overlay, the program 8763 copies its code from the larger address space to the instruction 8764 address space. Since the overlays shown here all use the same mapped 8765 address, only one may be mapped at a time. For a system with a single 8766 address space for data and instructions, the diagram would be similar, 8767 except that the program variables and heap would share an address space 8768 with the main program and the overlay area. 8769 8770 An overlay loaded into instruction memory and ready for use is 8771 called a "mapped" overlay; its "mapped address" is its address in the 8772 instruction memory. An overlay not present (or only partially present) 8773 in instruction memory is called "unmapped"; its "load address" is its 8774 address in the larger memory. The mapped address is also called the 8775 "virtual memory address", or "VMA"; the load address is also called the 8776 "load memory address", or "LMA". 8777 8778 Unfortunately, overlays are not a completely transparent way to 8779 adapt a program to limited instruction memory. They introduce a new 8780 set of global constraints you must keep in mind as you design your 8781 program: 8782 8783 * Before calling or returning to a function in an overlay, your 8784 program must make sure that overlay is actually mapped. 8785 Otherwise, the call or return will transfer control to the right 8786 address, but in the wrong overlay, and your program will probably 8787 crash. 8788 8789 * If the process of mapping an overlay is expensive on your system, 8790 you will need to choose your overlays carefully to minimize their 8791 effect on your program's performance. 8792 8793 * The executable file you load onto your system must contain each 8794 overlay's instructions, appearing at the overlay's load address, 8795 not its mapped address. However, each overlay's instructions must 8796 be relocated and its symbols defined as if the overlay were at its 8797 mapped address. You can use GNU linker scripts to specify 8798 different load and relocation addresses for pieces of your 8799 program; see *Note Overlay Description: (ld.info)Overlay 8800 Description. 8801 8802 * The procedure for loading executable files onto your system must 8803 be able to load their contents into the larger address space as 8804 well as the instruction and data spaces. 8805 8806 8807 The overlay system described above is rather simple, and could be 8808 improved in many ways: 8809 8810 * If your system has suitable bank switch registers or memory 8811 management hardware, you could use those facilities to make an 8812 overlay's load area contents simply appear at their mapped address 8813 in instruction space. This would probably be faster than copying 8814 the overlay to its mapped area in the usual way. 8815 8816 * If your overlays are small enough, you could set aside more than 8817 one overlay area, and have more than one overlay mapped at a time. 8818 8819 * You can use overlays to manage data, as well as instructions. In 8820 general, data overlays are even less transparent to your design 8821 than code overlays: whereas code overlays only require care when 8822 you call or return to functions, data overlays require care every 8823 time you access the data. Also, if you change the contents of a 8824 data overlay, you must copy its contents back out to its load 8825 address before you can copy a different data overlay into the same 8826 mapped area. 8827 8828 8829 8830 File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays 8831 8832 14.2 Overlay Commands 8833 ===================== 8834 8835 To use GDB's overlay support, each overlay in your program must 8836 correspond to a separate section of the executable file. The section's 8837 virtual memory address and load memory address must be the overlay's 8838 mapped and load addresses. Identifying overlays with sections allows 8839 GDB to determine the appropriate address of a function or variable, 8840 depending on whether the overlay is mapped or not. 8841 8842 GDB's overlay commands all start with the word `overlay'; you can 8843 abbreviate this as `ov' or `ovly'. The commands are: 8844 8845 `overlay off' 8846 Disable GDB's overlay support. When overlay support is disabled, 8847 GDB assumes that all functions and variables are always present at 8848 their mapped addresses. By default, GDB's overlay support is 8849 disabled. 8850 8851 `overlay manual' 8852 Enable "manual" overlay debugging. In this mode, GDB relies on 8853 you to tell it which overlays are mapped, and which are not, using 8854 the `overlay map-overlay' and `overlay unmap-overlay' commands 8855 described below. 8856 8857 `overlay map-overlay OVERLAY' 8858 `overlay map OVERLAY' 8859 Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of 8860 the object file section containing the overlay. When an overlay 8861 is mapped, GDB assumes it can find the overlay's functions and 8862 variables at their mapped addresses. GDB assumes that any other 8863 overlays whose mapped ranges overlap that of OVERLAY are now 8864 unmapped. 8865 8866 `overlay unmap-overlay OVERLAY' 8867 `overlay unmap OVERLAY' 8868 Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the 8869 name of the object file section containing the overlay. When an 8870 overlay is unmapped, GDB assumes it can find the overlay's 8871 functions and variables at their load addresses. 8872 8873 `overlay auto' 8874 Enable "automatic" overlay debugging. In this mode, GDB consults 8875 a data structure the overlay manager maintains in the inferior to 8876 see which overlays are mapped. For details, see *Note Automatic 8877 Overlay Debugging::. 8878 8879 `overlay load-target' 8880 `overlay load' 8881 Re-read the overlay table from the inferior. Normally, GDB 8882 re-reads the table GDB automatically each time the inferior stops, 8883 so this command should only be necessary if you have changed the 8884 overlay mapping yourself using GDB. This command is only useful 8885 when using automatic overlay debugging. 8886 8887 `overlay list-overlays' 8888 `overlay list' 8889 Display a list of the overlays currently mapped, along with their 8890 mapped addresses, load addresses, and sizes. 8891 8892 8893 Normally, when GDB prints a code address, it includes the name of 8894 the function the address falls in: 8895 8896 (gdb) print main 8897 $3 = {int ()} 0x11a0 <main> 8898 When overlay debugging is enabled, GDB recognizes code in unmapped 8899 overlays, and prints the names of unmapped functions with asterisks 8900 around them. For example, if `foo' is a function in an unmapped 8901 overlay, GDB prints it this way: 8902 8903 (gdb) overlay list 8904 No sections are mapped. 8905 (gdb) print foo 8906 $5 = {int (int)} 0x100000 <*foo*> 8907 When `foo''s overlay is mapped, GDB prints the function's name 8908 normally: 8909 8910 (gdb) overlay list 8911 Section .ov.foo.text, loaded at 0x100000 - 0x100034, 8912 mapped at 0x1016 - 0x104a 8913 (gdb) print foo 8914 $6 = {int (int)} 0x1016 <foo> 8915 8916 When overlay debugging is enabled, GDB can find the correct address 8917 for functions and variables in an overlay, whether or not the overlay 8918 is mapped. This allows most GDB commands, like `break' and 8919 `disassemble', to work normally, even on unmapped code. However, GDB's 8920 breakpoint support has some limitations: 8921 8922 * You can set breakpoints in functions in unmapped overlays, as long 8923 as GDB can write to the overlay at its load address. 8924 8925 * GDB can not set hardware or simulator-based breakpoints in 8926 unmapped overlays. However, if you set a breakpoint at the end of 8927 your overlay manager (and tell GDB which overlays are now mapped, 8928 if you are using manual overlay management), GDB will re-set its 8929 breakpoints properly. 8930 8931 8932 File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays 8933 8934 14.3 Automatic Overlay Debugging 8935 ================================ 8936 8937 GDB can automatically track which overlays are mapped and which are 8938 not, given some simple co-operation from the overlay manager in the 8939 inferior. If you enable automatic overlay debugging with the `overlay 8940 auto' command (*note Overlay Commands::), GDB looks in the inferior's 8941 memory for certain variables describing the current state of the 8942 overlays. 8943 8944 Here are the variables your overlay manager must define to support 8945 GDB's automatic overlay debugging: 8946 8947 `_ovly_table': 8948 This variable must be an array of the following structures: 8949 8950 struct 8951 { 8952 /* The overlay's mapped address. */ 8953 unsigned long vma; 8954 8955 /* The size of the overlay, in bytes. */ 8956 unsigned long size; 8957 8958 /* The overlay's load address. */ 8959 unsigned long lma; 8960 8961 /* Non-zero if the overlay is currently mapped; 8962 zero otherwise. */ 8963 unsigned long mapped; 8964 } 8965 8966 `_novlys': 8967 This variable must be a four-byte signed integer, holding the total 8968 number of elements in `_ovly_table'. 8969 8970 8971 To decide whether a particular overlay is mapped or not, GDB looks 8972 for an entry in `_ovly_table' whose `vma' and `lma' members equal the 8973 VMA and LMA of the overlay's section in the executable file. When GDB 8974 finds a matching entry, it consults the entry's `mapped' member to 8975 determine whether the overlay is currently mapped. 8976 8977 In addition, your overlay manager may define a function called 8978 `_ovly_debug_event'. If this function is defined, GDB will silently 8979 set a breakpoint there. If the overlay manager then calls this 8980 function whenever it has changed the overlay table, this will enable 8981 GDB to accurately keep track of which overlays are in program memory, 8982 and update any breakpoints that may be set in overlays. This will 8983 allow breakpoints to work even if the overlays are kept in ROM or other 8984 non-writable memory while they are not being executed. 8985 8986 8987 File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays 8988 8989 14.4 Overlay Sample Program 8990 =========================== 8991 8992 When linking a program which uses overlays, you must place the overlays 8993 at their load addresses, while relocating them to run at their mapped 8994 addresses. To do this, you must write a linker script (*note Overlay 8995 Description: (ld.info)Overlay Description.). Unfortunately, since 8996 linker scripts are specific to a particular host system, target 8997 architecture, and target memory layout, this manual cannot provide 8998 portable sample code demonstrating GDB's overlay support. 8999 9000 However, the GDB source distribution does contain an overlaid 9001 program, with linker scripts for a few systems, as part of its test 9002 suite. The program consists of the following files from 9003 `gdb/testsuite/gdb.base': 9004 9005 `overlays.c' 9006 The main program file. 9007 9008 `ovlymgr.c' 9009 A simple overlay manager, used by `overlays.c'. 9010 9011 `foo.c' 9012 `bar.c' 9013 `baz.c' 9014 `grbx.c' 9015 Overlay modules, loaded and used by `overlays.c'. 9016 9017 `d10v.ld' 9018 `m32r.ld' 9019 Linker scripts for linking the test program on the `d10v-elf' and 9020 `m32r-elf' targets. 9021 9022 You can build the test program using the `d10v-elf' GCC 9023 cross-compiler like this: 9024 9025 $ d10v-elf-gcc -g -c overlays.c 9026 $ d10v-elf-gcc -g -c ovlymgr.c 9027 $ d10v-elf-gcc -g -c foo.c 9028 $ d10v-elf-gcc -g -c bar.c 9029 $ d10v-elf-gcc -g -c baz.c 9030 $ d10v-elf-gcc -g -c grbx.c 9031 $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ 9032 baz.o grbx.o -Wl,-Td10v.ld -o overlays 9033 9034 The build process is identical for any other architecture, except 9035 that you must substitute the appropriate compiler and linker script for 9036 the target system for `d10v-elf-gcc' and `d10v.ld'. 9037 9038 9039 File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, Up: Top 9040 9041 15 Using GDB with Different Languages 9042 ************************************* 9043 9044 Although programming languages generally have common aspects, they are 9045 rarely expressed in the same manner. For instance, in ANSI C, 9046 dereferencing a pointer `p' is accomplished by `*p', but in Modula-2, 9047 it is accomplished by `p^'. Values can also be represented (and 9048 displayed) differently. Hex numbers in C appear as `0x1ae', while in 9049 Modula-2 they appear as `1AEH'. 9050 9051 Language-specific information is built into GDB for some languages, 9052 allowing you to express operations like the above in your program's 9053 native language, and allowing GDB to output values in a manner 9054 consistent with the syntax of your program's native language. The 9055 language you use to build expressions is called the "working language". 9056 9057 * Menu: 9058 9059 * Setting:: Switching between source languages 9060 * Show:: Displaying the language 9061 * Checks:: Type and range checks 9062 * Supported Languages:: Supported languages 9063 * Unsupported Languages:: Unsupported languages 9064 9065 9066 File: gdb.info, Node: Setting, Next: Show, Up: Languages 9067 9068 15.1 Switching Between Source Languages 9069 ======================================= 9070 9071 There are two ways to control the working language--either have GDB set 9072 it automatically, or select it manually yourself. You can use the `set 9073 language' command for either purpose. On startup, GDB defaults to 9074 setting the language automatically. The working language is used to 9075 determine how expressions you type are interpreted, how values are 9076 printed, etc. 9077 9078 In addition to the working language, every source file that GDB 9079 knows about has its own working language. For some object file 9080 formats, the compiler might indicate which language a particular source 9081 file is in. However, most of the time GDB infers the language from the 9082 name of the file. The language of a source file controls whether C++ 9083 names are demangled--this way `backtrace' can show each frame 9084 appropriately for its own language. There is no way to set the 9085 language of a source file from within GDB, but you can set the language 9086 associated with a filename extension. *Note Displaying the Language: 9087 Show. 9088 9089 This is most commonly a problem when you use a program, such as 9090 `cfront' or `f2c', that generates C but is written in another language. 9091 In that case, make the program use `#line' directives in its C output; 9092 that way GDB will know the correct language of the source code of the 9093 original program, and will display that source code, not the generated 9094 C code. 9095 9096 * Menu: 9097 9098 * Filenames:: Filename extensions and languages. 9099 * Manually:: Setting the working language manually 9100 * Automatically:: Having GDB infer the source language 9101 9102 9103 File: gdb.info, Node: Filenames, Next: Manually, Up: Setting 9104 9105 15.1.1 List of Filename Extensions and Languages 9106 ------------------------------------------------ 9107 9108 If a source file name ends in one of the following extensions, then GDB 9109 infers that its language is the one indicated. 9110 9111 `.ada' 9112 `.ads' 9113 `.adb' 9114 `.a' 9115 Ada source file. 9116 9117 `.c' 9118 C source file 9119 9120 `.C' 9121 `.cc' 9122 `.cp' 9123 `.cpp' 9124 `.cxx' 9125 `.c++' 9126 C++ source file 9127 9128 `.m' 9129 Objective-C source file 9130 9131 `.f' 9132 `.F' 9133 Fortran source file 9134 9135 `.mod' 9136 Modula-2 source file 9137 9138 `.s' 9139 `.S' 9140 Assembler source file. This actually behaves almost like C, but 9141 GDB does not skip over function prologues when stepping. 9142 9143 In addition, you may set the language associated with a filename 9144 extension. *Note Displaying the Language: Show. 9145 9146 9147 File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting 9148 9149 15.1.2 Setting the Working Language 9150 ----------------------------------- 9151 9152 If you allow GDB to set the language automatically, expressions are 9153 interpreted the same way in your debugging session and your program. 9154 9155 If you wish, you may set the language manually. To do this, issue 9156 the command `set language LANG', where LANG is the name of a language, 9157 such as `c' or `modula-2'. For a list of the supported languages, type 9158 `set language'. 9159 9160 Setting the language manually prevents GDB from updating the working 9161 language automatically. This can lead to confusion if you try to debug 9162 a program when the working language is not the same as the source 9163 language, when an expression is acceptable to both languages--but means 9164 different things. For instance, if the current source file were 9165 written in C, and GDB was parsing Modula-2, a command such as: 9166 9167 print a = b + c 9168 9169 might not have the effect you intended. In C, this means to add `b' 9170 and `c' and place the result in `a'. The result printed would be the 9171 value of `a'. In Modula-2, this means to compare `a' to the result of 9172 `b+c', yielding a `BOOLEAN' value. 9173 9174 9175 File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting 9176 9177 15.1.3 Having GDB Infer the Source Language 9178 ------------------------------------------- 9179 9180 To have GDB set the working language automatically, use `set language 9181 local' or `set language auto'. GDB then infers the working language. 9182 That is, when your program stops in a frame (usually by encountering a 9183 breakpoint), GDB sets the working language to the language recorded for 9184 the function in that frame. If the language for a frame is unknown 9185 (that is, if the function or block corresponding to the frame was 9186 defined in a source file that does not have a recognized extension), 9187 the current working language is not changed, and GDB issues a warning. 9188 9189 This may not seem necessary for most programs, which are written 9190 entirely in one source language. However, program modules and libraries 9191 written in one source language can be used by a main program written in 9192 a different source language. Using `set language auto' in this case 9193 frees you from having to set the working language manually. 9194 9195 9196 File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages 9197 9198 15.2 Displaying the Language 9199 ============================ 9200 9201 The following commands help you find out which language is the working 9202 language, and also what language source files were written in. 9203 9204 `show language' 9205 Display the current working language. This is the language you 9206 can use with commands such as `print' to build and compute 9207 expressions that may involve variables in your program. 9208 9209 `info frame' 9210 Display the source language for this frame. This language becomes 9211 the working language if you use an identifier from this frame. 9212 *Note Information about a Frame: Frame Info, to identify the other 9213 information listed here. 9214 9215 `info source' 9216 Display the source language of this source file. *Note Examining 9217 the Symbol Table: Symbols, to identify the other information 9218 listed here. 9219 9220 In unusual circumstances, you may have source files with extensions 9221 not in the standard list. You can then set the extension associated 9222 with a language explicitly: 9223 9224 `set extension-language EXT LANGUAGE' 9225 Tell GDB that source files with extension EXT are to be assumed as 9226 written in the source language LANGUAGE. 9227 9228 `info extensions' 9229 List all the filename extensions and the associated languages. 9230 9231 9232 File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages 9233 9234 15.3 Type and Range Checking 9235 ============================ 9236 9237 _Warning:_ In this release, the GDB commands for type and range 9238 checking are included, but they do not yet have any effect. This 9239 section documents the intended facilities. 9240 9241 Some languages are designed to guard you against making seemingly 9242 common errors through a series of compile- and run-time checks. These 9243 include checking the type of arguments to functions and operators, and 9244 making sure mathematical overflows are caught at run time. Checks such 9245 as these help to ensure a program's correctness once it has been 9246 compiled by eliminating type mismatches, and providing active checks 9247 for range errors when your program is running. 9248 9249 GDB can check for conditions like the above if you wish. Although 9250 GDB does not check the statements in your program, it can check 9251 expressions entered directly into GDB for evaluation via the `print' 9252 command, for example. As with the working language, GDB can also 9253 decide whether or not to check automatically based on your program's 9254 source language. *Note Supported Languages: Supported Languages, for 9255 the default settings of supported languages. 9256 9257 * Menu: 9258 9259 * Type Checking:: An overview of type checking 9260 * Range Checking:: An overview of range checking 9261 9262 9263 File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks 9264 9265 15.3.1 An Overview of Type Checking 9266 ----------------------------------- 9267 9268 Some languages, such as Modula-2, are strongly typed, meaning that the 9269 arguments to operators and functions have to be of the correct type, 9270 otherwise an error occurs. These checks prevent type mismatch errors 9271 from ever causing any run-time problems. For example, 9272 9273 1 + 2 => 3 9274 but 9275 error--> 1 + 2.3 9276 9277 The second example fails because the `CARDINAL' 1 is not 9278 type-compatible with the `REAL' 2.3. 9279 9280 For the expressions you use in GDB commands, you can tell the GDB 9281 type checker to skip checking; to treat any mismatches as errors and 9282 abandon the expression; or to only issue warnings when type mismatches 9283 occur, but evaluate the expression anyway. When you choose the last of 9284 these, GDB evaluates expressions like the second example above, but 9285 also issues a warning. 9286 9287 Even if you turn type checking off, there may be other reasons 9288 related to type that prevent GDB from evaluating an expression. For 9289 instance, GDB does not know how to add an `int' and a `struct foo'. 9290 These particular type errors have nothing to do with the language in 9291 use, and usually arise from expressions, such as the one described 9292 above, which make little sense to evaluate anyway. 9293 9294 Each language defines to what degree it is strict about type. For 9295 instance, both Modula-2 and C require the arguments to arithmetical 9296 operators to be numbers. In C, enumerated types and pointers can be 9297 represented as numbers, so that they are valid arguments to mathematical 9298 operators. *Note Supported Languages: Supported Languages, for further 9299 details on specific languages. 9300 9301 GDB provides some additional commands for controlling the type 9302 checker: 9303 9304 `set check type auto' 9305 Set type checking on or off based on the current working language. 9306 *Note Supported Languages: Supported Languages, for the default 9307 settings for each language. 9308 9309 `set check type on' 9310 `set check type off' 9311 Set type checking on or off, overriding the default setting for the 9312 current working language. Issue a warning if the setting does not 9313 match the language default. If any type mismatches occur in 9314 evaluating an expression while type checking is on, GDB prints a 9315 message and aborts evaluation of the expression. 9316 9317 `set check type warn' 9318 Cause the type checker to issue warnings, but to always attempt to 9319 evaluate the expression. Evaluating the expression may still be 9320 impossible for other reasons. For example, GDB cannot add numbers 9321 and structures. 9322 9323 `show type' 9324 Show the current setting of the type checker, and whether or not 9325 GDB is setting it automatically. 9326 9327 9328 File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks 9329 9330 15.3.2 An Overview of Range Checking 9331 ------------------------------------ 9332 9333 In some languages (such as Modula-2), it is an error to exceed the 9334 bounds of a type; this is enforced with run-time checks. Such range 9335 checking is meant to ensure program correctness by making sure 9336 computations do not overflow, or indices on an array element access do 9337 not exceed the bounds of the array. 9338 9339 For expressions you use in GDB commands, you can tell GDB to treat 9340 range errors in one of three ways: ignore them, always treat them as 9341 errors and abandon the expression, or issue warnings but evaluate the 9342 expression anyway. 9343 9344 A range error can result from numerical overflow, from exceeding an 9345 array index bound, or when you type a constant that is not a member of 9346 any type. Some languages, however, do not treat overflows as an error. 9347 In many implementations of C, mathematical overflow causes the result 9348 to "wrap around" to lower values--for example, if M is the largest 9349 integer value, and S is the smallest, then 9350 9351 M + 1 => S 9352 9353 This, too, is specific to individual languages, and in some cases 9354 specific to individual compilers or machines. *Note Supported 9355 Languages: Supported Languages, for further details on specific 9356 languages. 9357 9358 GDB provides some additional commands for controlling the range 9359 checker: 9360 9361 `set check range auto' 9362 Set range checking on or off based on the current working language. 9363 *Note Supported Languages: Supported Languages, for the default 9364 settings for each language. 9365 9366 `set check range on' 9367 `set check range off' 9368 Set range checking on or off, overriding the default setting for 9369 the current working language. A warning is issued if the setting 9370 does not match the language default. If a range error occurs and 9371 range checking is on, then a message is printed and evaluation of 9372 the expression is aborted. 9373 9374 `set check range warn' 9375 Output messages when the GDB range checker detects a range error, 9376 but attempt to evaluate the expression anyway. Evaluating the 9377 expression may still be impossible for other reasons, such as 9378 accessing memory that the process does not own (a typical example 9379 from many Unix systems). 9380 9381 `show range' 9382 Show the current setting of the range checker, and whether or not 9383 it is being set automatically by GDB. 9384 9385 9386 File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages 9387 9388 15.4 Supported Languages 9389 ======================== 9390 9391 GDB supports C, C++, Objective-C, Fortran, Java, Pascal, assembly, 9392 Modula-2, and Ada. Some GDB features may be used in expressions 9393 regardless of the language you use: the GDB `@' and `::' operators, and 9394 the `{type}addr' construct (*note Expressions: Expressions.) can be 9395 used with the constructs of any supported language. 9396 9397 The following sections detail to what degree each source language is 9398 supported by GDB. These sections are not meant to be language 9399 tutorials or references, but serve only as a reference guide to what the 9400 GDB expression parser accepts, and what input and output formats should 9401 look like for different languages. There are many good books written 9402 on each of these languages; please look to these for a language 9403 reference or tutorial. 9404 9405 * Menu: 9406 9407 * C:: C and C++ 9408 * Objective-C:: Objective-C 9409 * Fortran:: Fortran 9410 * Pascal:: Pascal 9411 * Modula-2:: Modula-2 9412 * Ada:: Ada 9413 9414 9415 File: gdb.info, Node: C, Next: Objective-C, Up: Supported Languages 9416 9417 15.4.1 C and C++ 9418 ---------------- 9419 9420 Since C and C++ are so closely related, many features of GDB apply to 9421 both languages. Whenever this is the case, we discuss those languages 9422 together. 9423 9424 The C++ debugging facilities are jointly implemented by the C++ 9425 compiler and GDB. Therefore, to debug your C++ code effectively, you 9426 must compile your C++ programs with a supported C++ compiler, such as 9427 GNU `g++', or the HP ANSI C++ compiler (`aCC'). 9428 9429 For best results when using GNU C++, use the DWARF 2 debugging 9430 format; if it doesn't work on your system, try the stabs+ debugging 9431 format. You can select those formats explicitly with the `g++' 9432 command-line options `-gdwarf-2' and `-gstabs+'. *Note Options for 9433 Debugging Your Program or GCC: (gcc.info)Debugging Options. 9434 9435 * Menu: 9436 9437 * C Operators:: C and C++ operators 9438 * C Constants:: C and C++ constants 9439 * C Plus Plus Expressions:: C++ expressions 9440 * C Defaults:: Default settings for C and C++ 9441 * C Checks:: C and C++ type and range checks 9442 * Debugging C:: GDB and C 9443 * Debugging C Plus Plus:: GDB features for C++ 9444 * Decimal Floating Point:: Numbers in Decimal Floating Point format 9445 9446 9447 File: gdb.info, Node: C Operators, Next: C Constants, Up: C 9448 9449 15.4.1.1 C and C++ Operators 9450 ............................ 9451 9452 Operators must be defined on values of specific types. For instance, 9453 `+' is defined on numbers, but not on structures. Operators are often 9454 defined on groups of types. 9455 9456 For the purposes of C and C++, the following definitions hold: 9457 9458 * _Integral types_ include `int' with any of its storage-class 9459 specifiers; `char'; `enum'; and, for C++, `bool'. 9460 9461 * _Floating-point types_ include `float', `double', and `long 9462 double' (if supported by the target platform). 9463 9464 * _Pointer types_ include all types defined as `(TYPE *)'. 9465 9466 * _Scalar types_ include all of the above. 9467 9468 9469 The following operators are supported. They are listed here in order 9470 of increasing precedence: 9471 9472 `,' 9473 The comma or sequencing operator. Expressions in a 9474 comma-separated list are evaluated from left to right, with the 9475 result of the entire expression being the last expression 9476 evaluated. 9477 9478 `=' 9479 Assignment. The value of an assignment expression is the value 9480 assigned. Defined on scalar types. 9481 9482 `OP=' 9483 Used in an expression of the form `A OP= B', and translated to 9484 `A = A OP B'. `OP=' and `=' have the same precedence. OP is any 9485 one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*', 9486 `/', `%'. 9487 9488 `?:' 9489 The ternary operator. `A ? B : C' can be thought of as: if A 9490 then B else C. A should be of an integral type. 9491 9492 `||' 9493 Logical OR. Defined on integral types. 9494 9495 `&&' 9496 Logical AND. Defined on integral types. 9497 9498 `|' 9499 Bitwise OR. Defined on integral types. 9500 9501 `^' 9502 Bitwise exclusive-OR. Defined on integral types. 9503 9504 `&' 9505 Bitwise AND. Defined on integral types. 9506 9507 `==, !=' 9508 Equality and inequality. Defined on scalar types. The value of 9509 these expressions is 0 for false and non-zero for true. 9510 9511 `<, >, <=, >=' 9512 Less than, greater than, less than or equal, greater than or equal. 9513 Defined on scalar types. The value of these expressions is 0 for 9514 false and non-zero for true. 9515 9516 `<<, >>' 9517 left shift, and right shift. Defined on integral types. 9518 9519 `@' 9520 The GDB "artificial array" operator (*note Expressions: 9521 Expressions.). 9522 9523 `+, -' 9524 Addition and subtraction. Defined on integral types, 9525 floating-point types and pointer types. 9526 9527 `*, /, %' 9528 Multiplication, division, and modulus. Multiplication and 9529 division are defined on integral and floating-point types. 9530 Modulus is defined on integral types. 9531 9532 `++, --' 9533 Increment and decrement. When appearing before a variable, the 9534 operation is performed before the variable is used in an 9535 expression; when appearing after it, the variable's value is used 9536 before the operation takes place. 9537 9538 `*' 9539 Pointer dereferencing. Defined on pointer types. Same precedence 9540 as `++'. 9541 9542 `&' 9543 Address operator. Defined on variables. Same precedence as `++'. 9544 9545 For debugging C++, GDB implements a use of `&' beyond what is 9546 allowed in the C++ language itself: you can use `&(&REF)' to 9547 examine the address where a C++ reference variable (declared with 9548 `&REF') is stored. 9549 9550 `-' 9551 Negative. Defined on integral and floating-point types. Same 9552 precedence as `++'. 9553 9554 `!' 9555 Logical negation. Defined on integral types. Same precedence as 9556 `++'. 9557 9558 `~' 9559 Bitwise complement operator. Defined on integral types. Same 9560 precedence as `++'. 9561 9562 `., ->' 9563 Structure member, and pointer-to-structure member. For 9564 convenience, GDB regards the two as equivalent, choosing whether 9565 to dereference a pointer based on the stored type information. 9566 Defined on `struct' and `union' data. 9567 9568 `.*, ->*' 9569 Dereferences of pointers to members. 9570 9571 `[]' 9572 Array indexing. `A[I]' is defined as `*(A+I)'. Same precedence 9573 as `->'. 9574 9575 `()' 9576 Function parameter list. Same precedence as `->'. 9577 9578 `::' 9579 C++ scope resolution operator. Defined on `struct', `union', and 9580 `class' types. 9581 9582 `::' 9583 Doubled colons also represent the GDB scope operator (*note 9584 Expressions: Expressions.). Same precedence as `::', above. 9585 9586 If an operator is redefined in the user code, GDB usually attempts 9587 to invoke the redefined version instead of using the operator's 9588 predefined meaning. 9589 9590 9591 File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C 9592 9593 15.4.1.2 C and C++ Constants 9594 ............................ 9595 9596 GDB allows you to express the constants of C and C++ in the following 9597 ways: 9598 9599 * Integer constants are a sequence of digits. Octal constants are 9600 specified by a leading `0' (i.e. zero), and hexadecimal constants 9601 by a leading `0x' or `0X'. Constants may also end with a letter 9602 `l', specifying that the constant should be treated as a `long' 9603 value. 9604 9605 * Floating point constants are a sequence of digits, followed by a 9606 decimal point, followed by a sequence of digits, and optionally 9607 followed by an exponent. An exponent is of the form: 9608 `e[[+]|-]NNN', where NNN is another sequence of digits. The `+' 9609 is optional for positive exponents. A floating-point constant may 9610 also end with a letter `f' or `F', specifying that the constant 9611 should be treated as being of the `float' (as opposed to the 9612 default `double') type; or with a letter `l' or `L', which 9613 specifies a `long double' constant. 9614 9615 * Enumerated constants consist of enumerated identifiers, or their 9616 integral equivalents. 9617 9618 * Character constants are a single character surrounded by single 9619 quotes (`''), or a number--the ordinal value of the corresponding 9620 character (usually its ASCII value). Within quotes, the single 9621 character may be represented by a letter or by "escape sequences", 9622 which are of the form `\NNN', where NNN is the octal representation 9623 of the character's ordinal value; or of the form `\X', where `X' 9624 is a predefined special character--for example, `\n' for newline. 9625 9626 * String constants are a sequence of character constants surrounded 9627 by double quotes (`"'). Any valid character constant (as described 9628 above) may appear. Double quotes within the string must be 9629 preceded by a backslash, so for instance `"a\"b'c"' is a string of 9630 five characters. 9631 9632 * Pointer constants are an integral value. You can also write 9633 pointers to constants using the C operator `&'. 9634 9635 * Array constants are comma-separated lists surrounded by braces `{' 9636 and `}'; for example, `{1,2,3}' is a three-element array of 9637 integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and 9638 `{&"hi", &"there", &"fred"}' is a three-element array of pointers. 9639 9640 9641 File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C 9642 9643 15.4.1.3 C++ Expressions 9644 ........................ 9645 9646 GDB expression handling can interpret most C++ expressions. 9647 9648 _Warning:_ GDB can only debug C++ code if you use the proper 9649 compiler and the proper debug format. Currently, GDB works best 9650 when debugging C++ code that is compiled with GCC 2.95.3 or with 9651 GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'. 9652 DWARF 2 is preferred over stabs+. Most configurations of GCC emit 9653 either DWARF 2 or stabs+ as their default debug format, so you 9654 usually don't need to specify a debug format explicitly. Other 9655 compilers and/or debug formats are likely to work badly or not at 9656 all when using GDB to debug C++ code. 9657 9658 1. Member function calls are allowed; you can use expressions like 9659 9660 count = aml->GetOriginal(x, y) 9661 9662 2. While a member function is active (in the selected stack frame), 9663 your expressions have the same namespace available as the member 9664 function; that is, GDB allows implicit references to the class 9665 instance pointer `this' following the same rules as C++. 9666 9667 3. You can call overloaded functions; GDB resolves the function call 9668 to the right definition, with some restrictions. GDB does not 9669 perform overload resolution involving user-defined type 9670 conversions, calls to constructors, or instantiations of templates 9671 that do not exist in the program. It also cannot handle ellipsis 9672 argument lists or default arguments. 9673 9674 It does perform integral conversions and promotions, floating-point 9675 promotions, arithmetic conversions, pointer conversions, 9676 conversions of class objects to base classes, and standard 9677 conversions such as those of functions or arrays to pointers; it 9678 requires an exact match on the number of function arguments. 9679 9680 Overload resolution is always performed, unless you have specified 9681 `set overload-resolution off'. *Note GDB Features for C++: 9682 Debugging C Plus Plus. 9683 9684 You must specify `set overload-resolution off' in order to use an 9685 explicit function signature to call an overloaded function, as in 9686 p 'foo(char,int)'('x', 13) 9687 9688 The GDB command-completion facility can simplify this; see *Note 9689 Command Completion: Completion. 9690 9691 4. GDB understands variables declared as C++ references; you can use 9692 them in expressions just as you do in C++ source--they are 9693 automatically dereferenced. 9694 9695 In the parameter list shown when GDB displays a frame, the values 9696 of reference variables are not displayed (unlike other variables); 9697 this avoids clutter, since references are often used for large 9698 structures. The _address_ of a reference variable is always 9699 shown, unless you have specified `set print address off'. 9700 9701 5. GDB supports the C++ name resolution operator `::'--your 9702 expressions can use it just as expressions in your program do. 9703 Since one scope may be defined in another, you can use `::' 9704 repeatedly if necessary, for example in an expression like 9705 `SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by 9706 reference to source files, in both C and C++ debugging (*note 9707 Program Variables: Variables.). 9708 9709 In addition, when used with HP's C++ compiler, GDB supports calling 9710 virtual functions correctly, printing out virtual bases of objects, 9711 calling functions in a base subobject, casting objects, and invoking 9712 user-defined operators. 9713 9714 9715 File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C 9716 9717 15.4.1.4 C and C++ Defaults 9718 ........................... 9719 9720 If you allow GDB to set type and range checking automatically, they 9721 both default to `off' whenever the working language changes to C or 9722 C++. This happens regardless of whether you or GDB selects the working 9723 language. 9724 9725 If you allow GDB to set the language automatically, it recognizes 9726 source files whose names end with `.c', `.C', or `.cc', etc, and when 9727 GDB enters code compiled from one of these files, it sets the working 9728 language to C or C++. *Note Having GDB Infer the Source Language: 9729 Automatically, for further details. 9730 9731 9732 File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C 9733 9734 15.4.1.5 C and C++ Type and Range Checks 9735 ........................................ 9736 9737 By default, when GDB parses C or C++ expressions, type checking is not 9738 used. However, if you turn type checking on, GDB considers two 9739 variables type equivalent if: 9740 9741 * The two variables are structured and have the same structure, 9742 union, or enumerated tag. 9743 9744 * The two variables have the same type name, or types that have been 9745 declared equivalent through `typedef'. 9746 9747 9748 Range checking, if turned on, is done on mathematical operations. 9749 Array indices are not checked, since they are often used to index a 9750 pointer that is not itself an array. 9751 9752 9753 File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C 9754 9755 15.4.1.6 GDB and C 9756 .................. 9757 9758 The `set print union' and `show print union' commands apply to the 9759 `union' type. When set to `on', any `union' that is inside a `struct' 9760 or `class' is also printed. Otherwise, it appears as `{...}'. 9761 9762 The `@' operator aids in the debugging of dynamic arrays, formed 9763 with pointers and a memory allocation function. *Note Expressions: 9764 Expressions. 9765 9766 9767 File: gdb.info, Node: Debugging C Plus Plus, Next: Decimal Floating Point, Prev: Debugging C, Up: C 9768 9769 15.4.1.7 GDB Features for C++ 9770 ............................. 9771 9772 Some GDB commands are particularly useful with C++, and some are 9773 designed specifically for use with C++. Here is a summary: 9774 9775 `breakpoint menus' 9776 When you want a breakpoint in a function whose name is overloaded, 9777 GDB has the capability to display a menu of possible breakpoint 9778 locations to help you specify which function definition you want. 9779 *Note Ambiguous Expressions: Ambiguous Expressions. 9780 9781 `rbreak REGEX' 9782 Setting breakpoints using regular expressions is helpful for 9783 setting breakpoints on overloaded functions that are not members 9784 of any special classes. *Note Setting Breakpoints: Set Breaks. 9785 9786 `catch throw' 9787 `catch catch' 9788 Debug C++ exception handling using these commands. *Note Setting 9789 Catchpoints: Set Catchpoints. 9790 9791 `ptype TYPENAME' 9792 Print inheritance relationships as well as other information for 9793 type TYPENAME. *Note Examining the Symbol Table: Symbols. 9794 9795 `set print demangle' 9796 `show print demangle' 9797 `set print asm-demangle' 9798 `show print asm-demangle' 9799 Control whether C++ symbols display in their source form, both when 9800 displaying code as C++ source and when displaying disassemblies. 9801 *Note Print Settings: Print Settings. 9802 9803 `set print object' 9804 `show print object' 9805 Choose whether to print derived (actual) or declared types of 9806 objects. *Note Print Settings: Print Settings. 9807 9808 `set print vtbl' 9809 `show print vtbl' 9810 Control the format for printing virtual function tables. *Note 9811 Print Settings: Print Settings. (The `vtbl' commands do not work 9812 on programs compiled with the HP ANSI C++ compiler (`aCC').) 9813 9814 `set overload-resolution on' 9815 Enable overload resolution for C++ expression evaluation. The 9816 default is on. For overloaded functions, GDB evaluates the 9817 arguments and searches for a function whose signature matches the 9818 argument types, using the standard C++ conversion rules (see *Note 9819 C++ Expressions: C Plus Plus Expressions, for details). If it 9820 cannot find a match, it emits a message. 9821 9822 `set overload-resolution off' 9823 Disable overload resolution for C++ expression evaluation. For 9824 overloaded functions that are not class member functions, GDB 9825 chooses the first function of the specified name that it finds in 9826 the symbol table, whether or not its arguments are of the correct 9827 type. For overloaded functions that are class member functions, 9828 GDB searches for a function whose signature _exactly_ matches the 9829 argument types. 9830 9831 `show overload-resolution' 9832 Show the current setting of overload resolution. 9833 9834 `Overloaded symbol names' 9835 You can specify a particular definition of an overloaded symbol, 9836 using the same notation that is used to declare such symbols in 9837 C++: type `SYMBOL(TYPES)' rather than just SYMBOL. You can also 9838 use the GDB command-line word completion facilities to list the 9839 available choices, or to finish the type list for you. *Note 9840 Command Completion: Completion, for details on how to do this. 9841 9842 9843 File: gdb.info, Node: Decimal Floating Point, Prev: Debugging C Plus Plus, Up: C 9844 9845 15.4.1.8 Decimal Floating Point format 9846 ...................................... 9847 9848 GDB can examine, set and perform computations with numbers in decimal 9849 floating point format, which in the C language correspond to the 9850 `_Decimal32', `_Decimal64' and `_Decimal128' types as specified by the 9851 extension to support decimal floating-point arithmetic. 9852 9853 There are two encodings in use, depending on the architecture: BID 9854 (Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed 9855 Decimal) for PowerPC. GDB will use the appropriate encoding for the 9856 configured target. 9857 9858 Because of a limitation in `libdecnumber', the library used by GDB 9859 to manipulate decimal floating point numbers, it is not possible to 9860 convert (using a cast, for example) integers wider than 32-bit to 9861 decimal float. 9862 9863 In addition, in order to imitate GDB's behaviour with binary floating 9864 point computations, error checking in decimal float operations ignores 9865 underflow, overflow and divide by zero exceptions. 9866 9867 In the PowerPC architecture, GDB provides a set of pseudo-registers 9868 to inspect `_Decimal128' values stored in floating point registers. 9869 See *Note PowerPC: PowerPC. for more details. 9870 9871 9872 File: gdb.info, Node: Objective-C, Next: Fortran, Prev: C, Up: Supported Languages 9873 9874 15.4.2 Objective-C 9875 ------------------ 9876 9877 This section provides information about some commands and command 9878 options that are useful for debugging Objective-C code. See also *Note 9879 info classes: Symbols, and *Note info selectors: Symbols, for a few 9880 more commands specific to Objective-C support. 9881 9882 * Menu: 9883 9884 * Method Names in Commands:: 9885 * The Print Command with Objective-C:: 9886 9887 9888 File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C 9889 9890 15.4.2.1 Method Names in Commands 9891 ................................. 9892 9893 The following commands have been extended to accept Objective-C method 9894 names as line specifications: 9895 9896 * `clear' 9897 9898 * `break' 9899 9900 * `info line' 9901 9902 * `jump' 9903 9904 * `list' 9905 9906 A fully qualified Objective-C method name is specified as 9907 9908 -[CLASS METHODNAME] 9909 9910 where the minus sign is used to indicate an instance method and a 9911 plus sign (not shown) is used to indicate a class method. The class 9912 name CLASS and method name METHODNAME are enclosed in brackets, similar 9913 to the way messages are specified in Objective-C source code. For 9914 example, to set a breakpoint at the `create' instance method of class 9915 `Fruit' in the program currently being debugged, enter: 9916 9917 break -[Fruit create] 9918 9919 To list ten program lines around the `initialize' class method, 9920 enter: 9921 9922 list +[NSText initialize] 9923 9924 In the current version of GDB, the plus or minus sign is required. 9925 In future versions of GDB, the plus or minus sign will be optional, but 9926 you can use it to narrow the search. It is also possible to specify 9927 just a method name: 9928 9929 break create 9930 9931 You must specify the complete method name, including any colons. If 9932 your program's source files contain more than one `create' method, 9933 you'll be presented with a numbered list of classes that implement that 9934 method. Indicate your choice by number, or type `0' to exit if none 9935 apply. 9936 9937 As another example, to clear a breakpoint established at the 9938 `makeKeyAndOrderFront:' method of the `NSWindow' class, enter: 9939 9940 clear -[NSWindow makeKeyAndOrderFront:] 9941 9942 9943 File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C 9944 9945 15.4.2.2 The Print Command With Objective-C 9946 ........................................... 9947 9948 The print command has also been extended to accept methods. For 9949 example: 9950 9951 print -[OBJECT hash] 9952 9953 will tell GDB to send the `hash' message to OBJECT and print the 9954 result. Also, an additional command has been added, `print-object' or 9955 `po' for short, which is meant to print the description of an object. 9956 However, this command may only work with certain Objective-C libraries 9957 that have a particular hook function, `_NSPrintForDebugger', defined. 9958 9959 9960 File: gdb.info, Node: Fortran, Next: Pascal, Prev: Objective-C, Up: Supported Languages 9961 9962 15.4.3 Fortran 9963 -------------- 9964 9965 GDB can be used to debug programs written in Fortran, but it currently 9966 supports only the features of Fortran 77 language. 9967 9968 Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers 9969 among them) append an underscore to the names of variables and 9970 functions. When you debug programs compiled by those compilers, you 9971 will need to refer to variables and functions with a trailing 9972 underscore. 9973 9974 * Menu: 9975 9976 * Fortran Operators:: Fortran operators and expressions 9977 * Fortran Defaults:: Default settings for Fortran 9978 * Special Fortran Commands:: Special GDB commands for Fortran 9979 9980 9981 File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran 9982 9983 15.4.3.1 Fortran Operators and Expressions 9984 .......................................... 9985 9986 Operators must be defined on values of specific types. For instance, 9987 `+' is defined on numbers, but not on characters or other non- 9988 arithmetic types. Operators are often defined on groups of types. 9989 9990 `**' 9991 The exponentiation operator. It raises the first operand to the 9992 power of the second one. 9993 9994 `:' 9995 The range operator. Normally used in the form of array(low:high) 9996 to represent a section of array. 9997 9998 `%' 9999 The access component operator. Normally used to access elements 10000 in derived types. Also suitable for unions. As unions aren't 10001 part of regular Fortran, this can only happen when accessing a 10002 register that uses a gdbarch-defined union type. 10003 10004 10005 File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran 10006 10007 15.4.3.2 Fortran Defaults 10008 ......................... 10009 10010 Fortran symbols are usually case-insensitive, so GDB by default uses 10011 case-insensitive matches for Fortran symbols. You can change that with 10012 the `set case-insensitive' command, see *Note Symbols::, for the 10013 details. 10014 10015 10016 File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Defaults, Up: Fortran 10017 10018 15.4.3.3 Special Fortran Commands 10019 ................................. 10020 10021 GDB has some commands to support Fortran-specific features, such as 10022 displaying common blocks. 10023 10024 `info common [COMMON-NAME]' 10025 This command prints the values contained in the Fortran `COMMON' 10026 block whose name is COMMON-NAME. With no argument, the names of 10027 all `COMMON' blocks visible at the current program location are 10028 printed. 10029 10030 10031 File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported Languages 10032 10033 15.4.4 Pascal 10034 ------------- 10035 10036 Debugging Pascal programs which use sets, subranges, file variables, or 10037 nested functions does not currently work. GDB does not support 10038 entering expressions, printing values, or similar features using Pascal 10039 syntax. 10040 10041 The Pascal-specific command `set print pascal_static-members' 10042 controls whether static members of Pascal objects are displayed. *Note 10043 pascal_static-members: Print Settings. 10044 10045 10046 File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported Languages 10047 10048 15.4.5 Modula-2 10049 --------------- 10050 10051 The extensions made to GDB to support Modula-2 only support output from 10052 the GNU Modula-2 compiler (which is currently being developed). Other 10053 Modula-2 compilers are not currently supported, and attempting to debug 10054 executables produced by them is most likely to give an error as GDB 10055 reads in the executable's symbol table. 10056 10057 * Menu: 10058 10059 * M2 Operators:: Built-in operators 10060 * Built-In Func/Proc:: Built-in functions and procedures 10061 * M2 Constants:: Modula-2 constants 10062 * M2 Types:: Modula-2 types 10063 * M2 Defaults:: Default settings for Modula-2 10064 * Deviations:: Deviations from standard Modula-2 10065 * M2 Checks:: Modula-2 type and range checks 10066 * M2 Scope:: The scope operators `::' and `.' 10067 * GDB/M2:: GDB and Modula-2 10068 10069 10070 File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 10071 10072 15.4.5.1 Operators 10073 .................. 10074 10075 Operators must be defined on values of specific types. For instance, 10076 `+' is defined on numbers, but not on structures. Operators are often 10077 defined on groups of types. For the purposes of Modula-2, the 10078 following definitions hold: 10079 10080 * _Integral types_ consist of `INTEGER', `CARDINAL', and their 10081 subranges. 10082 10083 * _Character types_ consist of `CHAR' and its subranges. 10084 10085 * _Floating-point types_ consist of `REAL'. 10086 10087 * _Pointer types_ consist of anything declared as `POINTER TO TYPE'. 10088 10089 * _Scalar types_ consist of all of the above. 10090 10091 * _Set types_ consist of `SET' and `BITSET' types. 10092 10093 * _Boolean types_ consist of `BOOLEAN'. 10094 10095 The following operators are supported, and appear in order of 10096 increasing precedence: 10097 10098 `,' 10099 Function argument or array index separator. 10100 10101 `:=' 10102 Assignment. The value of VAR `:=' VALUE is VALUE. 10103 10104 `<, >' 10105 Less than, greater than on integral, floating-point, or enumerated 10106 types. 10107 10108 `<=, >=' 10109 Less than or equal to, greater than or equal to on integral, 10110 floating-point and enumerated types, or set inclusion on set 10111 types. Same precedence as `<'. 10112 10113 `=, <>, #' 10114 Equality and two ways of expressing inequality, valid on scalar 10115 types. Same precedence as `<'. In GDB scripts, only `<>' is 10116 available for inequality, since `#' conflicts with the script 10117 comment character. 10118 10119 `IN' 10120 Set membership. Defined on set types and the types of their 10121 members. Same precedence as `<'. 10122 10123 `OR' 10124 Boolean disjunction. Defined on boolean types. 10125 10126 `AND, &' 10127 Boolean conjunction. Defined on boolean types. 10128 10129 `@' 10130 The GDB "artificial array" operator (*note Expressions: 10131 Expressions.). 10132 10133 `+, -' 10134 Addition and subtraction on integral and floating-point types, or 10135 union and difference on set types. 10136 10137 `*' 10138 Multiplication on integral and floating-point types, or set 10139 intersection on set types. 10140 10141 `/' 10142 Division on floating-point types, or symmetric set difference on 10143 set types. Same precedence as `*'. 10144 10145 `DIV, MOD' 10146 Integer division and remainder. Defined on integral types. Same 10147 precedence as `*'. 10148 10149 `-' 10150 Negative. Defined on `INTEGER' and `REAL' data. 10151 10152 `^' 10153 Pointer dereferencing. Defined on pointer types. 10154 10155 `NOT' 10156 Boolean negation. Defined on boolean types. Same precedence as 10157 `^'. 10158 10159 `.' 10160 `RECORD' field selector. Defined on `RECORD' data. Same 10161 precedence as `^'. 10162 10163 `[]' 10164 Array indexing. Defined on `ARRAY' data. Same precedence as `^'. 10165 10166 `()' 10167 Procedure argument list. Defined on `PROCEDURE' objects. Same 10168 precedence as `^'. 10169 10170 `::, .' 10171 GDB and Modula-2 scope operators. 10172 10173 _Warning:_ Set expressions and their operations are not yet 10174 supported, so GDB treats the use of the operator `IN', or the use 10175 of operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>=' 10176 on sets as an error. 10177 10178 10179 File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 10180 10181 15.4.5.2 Built-in Functions and Procedures 10182 .......................................... 10183 10184 Modula-2 also makes available several built-in procedures and functions. 10185 In describing these, the following metavariables are used: 10186 10187 A 10188 represents an `ARRAY' variable. 10189 10190 C 10191 represents a `CHAR' constant or variable. 10192 10193 I 10194 represents a variable or constant of integral type. 10195 10196 M 10197 represents an identifier that belongs to a set. Generally used in 10198 the same function with the metavariable S. The type of S should 10199 be `SET OF MTYPE' (where MTYPE is the type of M). 10200 10201 N 10202 represents a variable or constant of integral or floating-point 10203 type. 10204 10205 R 10206 represents a variable or constant of floating-point type. 10207 10208 T 10209 represents a type. 10210 10211 V 10212 represents a variable. 10213 10214 X 10215 represents a variable or constant of one of many types. See the 10216 explanation of the function for details. 10217 10218 All Modula-2 built-in procedures also return a result, described 10219 below. 10220 10221 `ABS(N)' 10222 Returns the absolute value of N. 10223 10224 `CAP(C)' 10225 If C is a lower case letter, it returns its upper case equivalent, 10226 otherwise it returns its argument. 10227 10228 `CHR(I)' 10229 Returns the character whose ordinal value is I. 10230 10231 `DEC(V)' 10232 Decrements the value in the variable V by one. Returns the new 10233 value. 10234 10235 `DEC(V,I)' 10236 Decrements the value in the variable V by I. Returns the new 10237 value. 10238 10239 `EXCL(M,S)' 10240 Removes the element M from the set S. Returns the new set. 10241 10242 `FLOAT(I)' 10243 Returns the floating point equivalent of the integer I. 10244 10245 `HIGH(A)' 10246 Returns the index of the last member of A. 10247 10248 `INC(V)' 10249 Increments the value in the variable V by one. Returns the new 10250 value. 10251 10252 `INC(V,I)' 10253 Increments the value in the variable V by I. Returns the new 10254 value. 10255 10256 `INCL(M,S)' 10257 Adds the element M to the set S if it is not already there. 10258 Returns the new set. 10259 10260 `MAX(T)' 10261 Returns the maximum value of the type T. 10262 10263 `MIN(T)' 10264 Returns the minimum value of the type T. 10265 10266 `ODD(I)' 10267 Returns boolean TRUE if I is an odd number. 10268 10269 `ORD(X)' 10270 Returns the ordinal value of its argument. For example, the 10271 ordinal value of a character is its ASCII value (on machines 10272 supporting the ASCII character set). X must be of an ordered 10273 type, which include integral, character and enumerated types. 10274 10275 `SIZE(X)' 10276 Returns the size of its argument. X can be a variable or a type. 10277 10278 `TRUNC(R)' 10279 Returns the integral part of R. 10280 10281 `TSIZE(X)' 10282 Returns the size of its argument. X can be a variable or a type. 10283 10284 `VAL(T,I)' 10285 Returns the member of the type T whose ordinal value is I. 10286 10287 _Warning:_ Sets and their operations are not yet supported, so 10288 GDB treats the use of procedures `INCL' and `EXCL' as an error. 10289 10290 10291 File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2 10292 10293 15.4.5.3 Constants 10294 .................. 10295 10296 GDB allows you to express the constants of Modula-2 in the following 10297 ways: 10298 10299 * Integer constants are simply a sequence of digits. When used in an 10300 expression, a constant is interpreted to be type-compatible with 10301 the rest of the expression. Hexadecimal integers are specified by 10302 a trailing `H', and octal integers by a trailing `B'. 10303 10304 * Floating point constants appear as a sequence of digits, followed 10305 by a decimal point and another sequence of digits. An optional 10306 exponent can then be specified, in the form `E[+|-]NNN', where 10307 `[+|-]NNN' is the desired exponent. All of the digits of the 10308 floating point constant must be valid decimal (base 10) digits. 10309 10310 * Character constants consist of a single character enclosed by a 10311 pair of like quotes, either single (`'') or double (`"'). They may 10312 also be expressed by their ordinal value (their ASCII value, 10313 usually) followed by a `C'. 10314 10315 * String constants consist of a sequence of characters enclosed by a 10316 pair of like quotes, either single (`'') or double (`"'). Escape 10317 sequences in the style of C are also allowed. *Note C and C++ 10318 Constants: C Constants, for a brief explanation of escape 10319 sequences. 10320 10321 * Enumerated constants consist of an enumerated identifier. 10322 10323 * Boolean constants consist of the identifiers `TRUE' and `FALSE'. 10324 10325 * Pointer constants consist of integral values only. 10326 10327 * Set constants are not yet supported. 10328 10329 10330 File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 10331 10332 15.4.5.4 Modula-2 Types 10333 ....................... 10334 10335 Currently GDB can print the following data types in Modula-2 syntax: 10336 array types, record types, set types, pointer types, procedure types, 10337 enumerated types, subrange types and base types. You can also print 10338 the contents of variables declared using these type. This section 10339 gives a number of simple source code examples together with sample GDB 10340 sessions. 10341 10342 The first example contains the following section of code: 10343 10344 VAR 10345 s: SET OF CHAR ; 10346 r: [20..40] ; 10347 10348 and you can request GDB to interrogate the type and value of `r' and 10349 `s'. 10350 10351 (gdb) print s 10352 {'A'..'C', 'Z'} 10353 (gdb) ptype s 10354 SET OF CHAR 10355 (gdb) print r 10356 21 10357 (gdb) ptype r 10358 [20..40] 10359 10360 Likewise if your source code declares `s' as: 10361 10362 VAR 10363 s: SET ['A'..'Z'] ; 10364 10365 then you may query the type of `s' by: 10366 10367 (gdb) ptype s 10368 type = SET ['A'..'Z'] 10369 10370 Note that at present you cannot interactively manipulate set 10371 expressions using the debugger. 10372 10373 The following example shows how you might declare an array in 10374 Modula-2 and how you can interact with GDB to print its type and 10375 contents: 10376 10377 VAR 10378 s: ARRAY [-10..10] OF CHAR ; 10379 10380 (gdb) ptype s 10381 ARRAY [-10..10] OF CHAR 10382 10383 Note that the array handling is not yet complete and although the 10384 type is printed correctly, expression handling still assumes that all 10385 arrays have a lower bound of zero and not `-10' as in the example above. 10386 10387 Here are some more type related Modula-2 examples: 10388 10389 TYPE 10390 colour = (blue, red, yellow, green) ; 10391 t = [blue..yellow] ; 10392 VAR 10393 s: t ; 10394 BEGIN 10395 s := blue ; 10396 10397 The GDB interaction shows how you can query the data type and value of 10398 a variable. 10399 10400 (gdb) print s 10401 $1 = blue 10402 (gdb) ptype t 10403 type = [blue..yellow] 10404 10405 In this example a Modula-2 array is declared and its contents 10406 displayed. Observe that the contents are written in the same way as 10407 their `C' counterparts. 10408 10409 VAR 10410 s: ARRAY [1..5] OF CARDINAL ; 10411 BEGIN 10412 s[1] := 1 ; 10413 10414 (gdb) print s 10415 $1 = {1, 0, 0, 0, 0} 10416 (gdb) ptype s 10417 type = ARRAY [1..5] OF CARDINAL 10418 10419 The Modula-2 language interface to GDB also understands pointer 10420 types as shown in this example: 10421 10422 VAR 10423 s: POINTER TO ARRAY [1..5] OF CARDINAL ; 10424 BEGIN 10425 NEW(s) ; 10426 s^[1] := 1 ; 10427 10428 and you can request that GDB describes the type of `s'. 10429 10430 (gdb) ptype s 10431 type = POINTER TO ARRAY [1..5] OF CARDINAL 10432 10433 GDB handles compound types as we can see in this example. Here we 10434 combine array types, record types, pointer types and subrange types: 10435 10436 TYPE 10437 foo = RECORD 10438 f1: CARDINAL ; 10439 f2: CHAR ; 10440 f3: myarray ; 10441 END ; 10442 10443 myarray = ARRAY myrange OF CARDINAL ; 10444 myrange = [-2..2] ; 10445 VAR 10446 s: POINTER TO ARRAY myrange OF foo ; 10447 10448 and you can ask GDB to describe the type of `s' as shown below. 10449 10450 (gdb) ptype s 10451 type = POINTER TO ARRAY [-2..2] OF foo = RECORD 10452 f1 : CARDINAL; 10453 f2 : CHAR; 10454 f3 : ARRAY [-2..2] OF CARDINAL; 10455 END 10456 10457 10458 File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 10459 10460 15.4.5.5 Modula-2 Defaults 10461 .......................... 10462 10463 If type and range checking are set automatically by GDB, they both 10464 default to `on' whenever the working language changes to Modula-2. 10465 This happens regardless of whether you or GDB selected the working 10466 language. 10467 10468 If you allow GDB to set the language automatically, then entering 10469 code compiled from a file whose name ends with `.mod' sets the working 10470 language to Modula-2. *Note Having GDB Infer the Source Language: 10471 Automatically, for further details. 10472 10473 10474 File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 10475 10476 15.4.5.6 Deviations from Standard Modula-2 10477 .......................................... 10478 10479 A few changes have been made to make Modula-2 programs easier to debug. 10480 This is done primarily via loosening its type strictness: 10481 10482 * Unlike in standard Modula-2, pointer constants can be formed by 10483 integers. This allows you to modify pointer variables during 10484 debugging. (In standard Modula-2, the actual address contained in 10485 a pointer variable is hidden from you; it can only be modified 10486 through direct assignment to another pointer variable or 10487 expression that returned a pointer.) 10488 10489 * C escape sequences can be used in strings and characters to 10490 represent non-printable characters. GDB prints out strings with 10491 these escape sequences embedded. Single non-printable characters 10492 are printed using the `CHR(NNN)' format. 10493 10494 * The assignment operator (`:=') returns the value of its right-hand 10495 argument. 10496 10497 * All built-in procedures both modify _and_ return their argument. 10498 10499 10500 File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 10501 10502 15.4.5.7 Modula-2 Type and Range Checks 10503 ....................................... 10504 10505 _Warning:_ in this release, GDB does not yet perform type or range 10506 checking. 10507 10508 GDB considers two Modula-2 variables type equivalent if: 10509 10510 * They are of types that have been declared equivalent via a `TYPE 10511 T1 = T2' statement 10512 10513 * They have been declared on the same line. (Note: This is true of 10514 the GNU Modula-2 compiler, but it may not be true of other 10515 compilers.) 10516 10517 As long as type checking is enabled, any attempt to combine variables 10518 whose types are not equivalent is an error. 10519 10520 Range checking is done on all mathematical operations, assignment, 10521 array index bounds, and all built-in functions and procedures. 10522 10523 10524 File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 10525 10526 15.4.5.8 The Scope Operators `::' and `.' 10527 ......................................... 10528 10529 There are a few subtle differences between the Modula-2 scope operator 10530 (`.') and the GDB scope operator (`::'). The two have similar syntax: 10531 10532 10533 MODULE . ID 10534 SCOPE :: ID 10535 10536 where SCOPE is the name of a module or a procedure, MODULE the name of 10537 a module, and ID is any declared identifier within your program, except 10538 another module. 10539 10540 Using the `::' operator makes GDB search the scope specified by 10541 SCOPE for the identifier ID. If it is not found in the specified 10542 scope, then GDB searches all scopes enclosing the one specified by 10543 SCOPE. 10544 10545 Using the `.' operator makes GDB search the current scope for the 10546 identifier specified by ID that was imported from the definition module 10547 specified by MODULE. With this operator, it is an error if the 10548 identifier ID was not imported from definition module MODULE, or if ID 10549 is not an identifier in MODULE. 10550 10551 10552 File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 10553 10554 15.4.5.9 GDB and Modula-2 10555 ......................... 10556 10557 Some GDB commands have little use when debugging Modula-2 programs. 10558 Five subcommands of `set print' and `show print' apply specifically to 10559 C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'. 10560 The first four apply to C++, and the last to the C `union' type, which 10561 has no direct analogue in Modula-2. 10562 10563 The `@' operator (*note Expressions: Expressions.), while available 10564 with any language, is not useful with Modula-2. Its intent is to aid 10565 the debugging of "dynamic arrays", which cannot be created in Modula-2 10566 as they can in C or C++. However, because an address can be specified 10567 by an integral constant, the construct `{TYPE}ADREXP' is still useful. 10568 10569 In GDB scripts, the Modula-2 inequality operator `#' is interpreted 10570 as the beginning of a comment. Use `<>' instead. 10571 10572 10573 File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages 10574 10575 15.4.6 Ada 10576 ---------- 10577 10578 The extensions made to GDB for Ada only support output from the GNU Ada 10579 (GNAT) compiler. Other Ada compilers are not currently supported, and 10580 attempting to debug executables produced by them is most likely to be 10581 difficult. 10582 10583 * Menu: 10584 10585 * Ada Mode Intro:: General remarks on the Ada syntax 10586 and semantics supported by Ada mode 10587 in GDB. 10588 * Omissions from Ada:: Restrictions on the Ada expression syntax. 10589 * Additions to Ada:: Extensions of the Ada expression syntax. 10590 * Stopping Before Main Program:: Debugging the program during elaboration. 10591 * Ada Tasks:: Listing and setting breakpoints in tasks. 10592 * Ada Tasks and Core Files:: Tasking Support when Debugging Core Files 10593 * Ada Glitches:: Known peculiarities of Ada mode. 10594 10595 10596 File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada 10597 10598 15.4.6.1 Introduction 10599 ..................... 10600 10601 The Ada mode of GDB supports a fairly large subset of Ada expression 10602 syntax, with some extensions. The philosophy behind the design of this 10603 subset is 10604 10605 * That GDB should provide basic literals and access to operations for 10606 arithmetic, dereferencing, field selection, indexing, and 10607 subprogram calls, leaving more sophisticated computations to 10608 subprograms written into the program (which therefore may be 10609 called from GDB). 10610 10611 * That type safety and strict adherence to Ada language restrictions 10612 are not particularly important to the GDB user. 10613 10614 * That brevity is important to the GDB user. 10615 10616 Thus, for brevity, the debugger acts as if all names declared in 10617 user-written packages are directly visible, even if they are not visible 10618 according to Ada rules, thus making it unnecessary to fully qualify most 10619 names with their packages, regardless of context. Where this causes 10620 ambiguity, GDB asks the user's intent. 10621 10622 The debugger will start in Ada mode if it detects an Ada main 10623 program. As for other languages, it will enter Ada mode when stopped 10624 in a program that was translated from an Ada source file. 10625 10626 While in Ada mode, you may use `-' for comments. This is useful 10627 mostly for documenting command files. The standard GDB comment (`#') 10628 still works at the beginning of a line in Ada mode, but not in the 10629 middle (to allow based literals). 10630 10631 The debugger supports limited overloading. Given a subprogram call 10632 in which the function symbol has multiple definitions, it will use the 10633 number of actual parameters and some information about their types to 10634 attempt to narrow the set of definitions. It also makes very limited 10635 use of context, preferring procedures to functions in the context of 10636 the `call' command, and functions to procedures elsewhere. 10637 10638 10639 File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada 10640 10641 15.4.6.2 Omissions from Ada 10642 ........................... 10643 10644 Here are the notable omissions from the subset: 10645 10646 * Only a subset of the attributes are supported: 10647 10648 - 'First, 'Last, and 'Length on array objects (not on types 10649 and subtypes). 10650 10651 - 'Min and 'Max. 10652 10653 - 'Pos and 'Val. 10654 10655 - 'Tag. 10656 10657 - 'Range on array objects (not subtypes), but only as the right 10658 operand of the membership (`in') operator. 10659 10660 - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT 10661 extension). 10662 10663 - 'Address. 10664 10665 * The names in `Characters.Latin_1' are not available and 10666 concatenation is not implemented. Thus, escape characters in 10667 strings are not currently available. 10668 10669 * Equality tests (`=' and `/=') on arrays test for bitwise equality 10670 of representations. They will generally work correctly for 10671 strings and arrays whose elements have integer or enumeration 10672 types. They may not work correctly for arrays whose element types 10673 have user-defined equality, for arrays of real values (in 10674 particular, IEEE-conformant floating point, because of negative 10675 zeroes and NaNs), and for arrays whose elements contain unused 10676 bits with indeterminate values. 10677 10678 * The other component-by-component array operations (`and', `or', 10679 `xor', `not', and relational tests other than equality) are not 10680 implemented. 10681 10682 * There is limited support for array and record aggregates. They are 10683 permitted only on the right sides of assignments, as in these 10684 examples: 10685 10686 (gdb) set An_Array := (1, 2, 3, 4, 5, 6) 10687 (gdb) set An_Array := (1, others => 0) 10688 (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) 10689 (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) 10690 (gdb) set A_Record := (1, "Peter", True); 10691 (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True) 10692 10693 Changing a discriminant's value by assigning an aggregate has an 10694 undefined effect if that discriminant is used within the record. 10695 However, you can first modify discriminants by directly assigning 10696 to them (which normally would not be allowed in Ada), and then 10697 performing an aggregate assignment. For example, given a variable 10698 `A_Rec' declared to have a type such as: 10699 10700 type Rec (Len : Small_Integer := 0) is record 10701 Id : Integer; 10702 Vals : IntArray (1 .. Len); 10703 end record; 10704 10705 you can assign a value with a different size of `Vals' with two 10706 assignments: 10707 10708 (gdb) set A_Rec.Len := 4 10709 (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) 10710 10711 As this example also illustrates, GDB is very loose about the usual 10712 rules concerning aggregates. You may leave out some of the 10713 components of an array or record aggregate (such as the `Len' 10714 component in the assignment to `A_Rec' above); they will retain 10715 their original values upon assignment. You may freely use dynamic 10716 values as indices in component associations. You may even use 10717 overlapping or redundant component associations, although which 10718 component values are assigned in such cases is not defined. 10719 10720 * Calls to dispatching subprograms are not implemented. 10721 10722 * The overloading algorithm is much more limited (i.e., less 10723 selective) than that of real Ada. It makes only limited use of 10724 the context in which a subexpression appears to resolve its 10725 meaning, and it is much looser in its rules for allowing type 10726 matches. As a result, some function calls will be ambiguous, and 10727 the user will be asked to choose the proper resolution. 10728 10729 * The `new' operator is not implemented. 10730 10731 * Entry calls are not implemented. 10732 10733 * Aside from printing, arithmetic operations on the native VAX 10734 floating-point formats are not supported. 10735 10736 * It is not possible to slice a packed array. 10737 10738 * The names `True' and `False', when not part of a qualified name, 10739 are interpreted as if implicitly prefixed by `Standard', 10740 regardless of context. Should your program redefine these names 10741 in a package or procedure (at best a dubious practice), you will 10742 have to use fully qualified names to access their new definitions. 10743 10744 10745 File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada 10746 10747 15.4.6.3 Additions to Ada 10748 ......................... 10749 10750 As it does for other languages, GDB makes certain generic extensions to 10751 Ada (*note Expressions::): 10752 10753 * If the expression E is a variable residing in memory (typically a 10754 local variable or array element) and N is a positive integer, then 10755 `E@N' displays the values of E and the N-1 adjacent variables 10756 following it in memory as an array. In Ada, this operator is 10757 generally not necessary, since its prime use is in displaying 10758 parts of an array, and slicing will usually do this in Ada. 10759 However, there are occasional uses when debugging programs in 10760 which certain debugging information has been optimized away. 10761 10762 * `B::VAR' means "the variable named VAR that appears in function or 10763 file B." When B is a file name, you must typically surround it in 10764 single quotes. 10765 10766 * The expression `{TYPE} ADDR' means "the variable of type TYPE that 10767 appears at address ADDR." 10768 10769 * A name starting with `$' is a convenience variable (*note 10770 Convenience Vars::) or a machine register (*note Registers::). 10771 10772 In addition, GDB provides a few other shortcuts and outright 10773 additions specific to Ada: 10774 10775 * The assignment statement is allowed as an expression, returning 10776 its right-hand operand as its value. Thus, you may enter 10777 10778 (gdb) set x := y + 3 10779 (gdb) print A(tmp := y + 1) 10780 10781 * The semicolon is allowed as an "operator," returning as its value 10782 the value of its right-hand operand. This allows, for example, 10783 complex conditional breaks: 10784 10785 (gdb) break f 10786 (gdb) condition 1 (report(i); k += 1; A(k) > 100) 10787 10788 * Rather than use catenation and symbolic character names to 10789 introduce special characters into strings, one may instead use a 10790 special bracket notation, which is also used to print strings. A 10791 sequence of characters of the form `["XX"]' within a string or 10792 character literal denotes the (single) character whose numeric 10793 encoding is XX in hexadecimal. The sequence of characters `["""]' 10794 also denotes a single quotation mark in strings. For example, 10795 "One line.["0a"]Next line.["0a"]" 10796 contains an ASCII newline character (`Ada.Characters.Latin_1.LF') 10797 after each period. 10798 10799 * The subtype used as a prefix for the attributes 'Pos, 'Min, and 10800 'Max is optional (and is ignored in any case). For example, it is 10801 valid to write 10802 10803 (gdb) print 'max(x, y) 10804 10805 * When printing arrays, GDB uses positional notation when the array 10806 has a lower bound of 1, and uses a modified named notation 10807 otherwise. For example, a one-dimensional array of three integers 10808 with a lower bound of 3 might print as 10809 10810 (3 => 10, 17, 1) 10811 10812 That is, in contrast to valid Ada, only the first component has a 10813 `=>' clause. 10814 10815 * You may abbreviate attributes in expressions with any unique, 10816 multi-character subsequence of their names (an exact match gets 10817 preference). For example, you may use a'len, a'gth, or a'lh in 10818 place of a'length. 10819 10820 * Since Ada is case-insensitive, the debugger normally maps 10821 identifiers you type to lower case. The GNAT compiler uses 10822 upper-case characters for some of its internal identifiers, which 10823 are normally of no interest to users. For the rare occasions when 10824 you actually have to look at them, enclose them in angle brackets 10825 to avoid the lower-case mapping. For example, 10826 (gdb) print <JMPBUF_SAVE>[0] 10827 10828 * Printing an object of class-wide type or dereferencing an 10829 access-to-class-wide value will display all the components of the 10830 object's specific type (as indicated by its run-time tag). 10831 Likewise, component selection on such a value will operate on the 10832 specific type of the object. 10833 10834 10835 10836 File: gdb.info, Node: Stopping Before Main Program, Next: Ada Tasks, Prev: Additions to Ada, Up: Ada 10837 10838 15.4.6.4 Stopping at the Very Beginning 10839 ....................................... 10840 10841 It is sometimes necessary to debug the program during elaboration, and 10842 before reaching the main procedure. As defined in the Ada Reference 10843 Manual, the elaboration code is invoked from a procedure called 10844 `adainit'. To run your program up to the beginning of elaboration, 10845 simply use the following two commands: `tbreak adainit' and `run'. 10846 10847 10848 File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Stopping Before Main Program, Up: Ada 10849 10850 15.4.6.5 Extensions for Ada Tasks 10851 ................................. 10852 10853 Support for Ada tasks is analogous to that for threads (*note 10854 Threads::). GDB provides the following task-related commands: 10855 10856 `info tasks' 10857 This command shows a list of current Ada tasks, as in the 10858 following example: 10859 10860 (gdb) info tasks 10861 ID TID P-ID Pri State Name 10862 1 8088000 0 15 Child Activation Wait main_task 10863 2 80a4000 1 15 Accept Statement b 10864 3 809a800 1 15 Child Activation Wait a 10865 * 4 80ae800 3 15 Runnable c 10866 10867 In this listing, the asterisk before the last task indicates it to 10868 be the task currently being inspected. 10869 10870 ID 10871 Represents GDB's internal task number. 10872 10873 TID 10874 The Ada task ID. 10875 10876 P-ID 10877 The parent's task ID (GDB's internal task number). 10878 10879 Pri 10880 The base priority of the task. 10881 10882 State 10883 Current state of the task. 10884 10885 `Unactivated' 10886 The task has been created but has not been activated. 10887 It cannot be executing. 10888 10889 `Runnable' 10890 The task is not blocked for any reason known to Ada. 10891 (It may be waiting for a mutex, though.) It is 10892 conceptually "executing" in normal mode. 10893 10894 `Terminated' 10895 The task is terminated, in the sense of ARM 9.3 (5). 10896 Any dependents that were waiting on terminate 10897 alternatives have been awakened and have terminated 10898 themselves. 10899 10900 `Child Activation Wait' 10901 The task is waiting for created tasks to complete 10902 activation. 10903 10904 `Accept Statement' 10905 The task is waiting on an accept or selective wait 10906 statement. 10907 10908 `Waiting on entry call' 10909 The task is waiting on an entry call. 10910 10911 `Async Select Wait' 10912 The task is waiting to start the abortable part of an 10913 asynchronous select statement. 10914 10915 `Delay Sleep' 10916 The task is waiting on a select statement with only a 10917 delay alternative open. 10918 10919 `Child Termination Wait' 10920 The task is sleeping having completed a master within 10921 itself, and is waiting for the tasks dependent on that 10922 master to become terminated or waiting on a terminate 10923 Phase. 10924 10925 `Wait Child in Term Alt' 10926 The task is sleeping waiting for tasks on terminate 10927 alternatives to finish terminating. 10928 10929 `Accepting RV with TASKNO' 10930 The task is accepting a rendez-vous with the task TASKNO. 10931 10932 Name 10933 Name of the task in the program. 10934 10935 10936 `info task TASKNO' 10937 This command shows detailled informations on the specified task, 10938 as in the following example: 10939 (gdb) info tasks 10940 ID TID P-ID Pri State Name 10941 1 8077880 0 15 Child Activation Wait main_task 10942 * 2 807c468 1 15 Runnable task_1 10943 (gdb) info task 2 10944 Ada Task: 0x807c468 10945 Name: task_1 10946 Thread: 0x807f378 10947 Parent: 1 (main_task) 10948 Base Priority: 15 10949 State: Runnable 10950 10951 `task' 10952 This command prints the ID of the current task. 10953 10954 (gdb) info tasks 10955 ID TID P-ID Pri State Name 10956 1 8077870 0 15 Child Activation Wait main_task 10957 * 2 807c458 1 15 Runnable t 10958 (gdb) task 10959 [Current task is 2] 10960 10961 `task TASKNO' 10962 This command is like the `thread THREADNO' command (*note 10963 Threads::). It switches the context of debugging from the current 10964 task to the given task. 10965 10966 (gdb) info tasks 10967 ID TID P-ID Pri State Name 10968 1 8077870 0 15 Child Activation Wait main_task 10969 * 2 807c458 1 15 Runnable t 10970 (gdb) task 1 10971 [Switching to task 1] 10972 #0 0x8067726 in pthread_cond_wait () 10973 (gdb) bt 10974 #0 0x8067726 in pthread_cond_wait () 10975 #1 0x8056714 in system.os_interface.pthread_cond_wait () 10976 #2 0x805cb63 in system.task_primitives.operations.sleep () 10977 #3 0x806153e in system.tasking.stages.activate_tasks () 10978 #4 0x804aacc in un () at un.adb:5 10979 10980 `break LINESPEC task TASKNO' 10981 `break LINESPEC task TASKNO if ...' 10982 These commands are like the `break ... thread ...' command (*note 10983 Thread Stops::). LINESPEC specifies source lines, as described in 10984 *Note Specify Location::. 10985 10986 Use the qualifier `task TASKNO' with a breakpoint command to 10987 specify that you only want GDB to stop the program when a 10988 particular Ada task reaches this breakpoint. TASKNO is one of the 10989 numeric task identifiers assigned by GDB, shown in the first 10990 column of the `info tasks' display. 10991 10992 If you do not specify `task TASKNO' when you set a breakpoint, the 10993 breakpoint applies to _all_ tasks of your program. 10994 10995 You can use the `task' qualifier on conditional breakpoints as 10996 well; in this case, place `task TASKNO' before the breakpoint 10997 condition (before the `if'). 10998 10999 For example, 11000 11001 (gdb) info tasks 11002 ID TID P-ID Pri State Name 11003 1 140022020 0 15 Child Activation Wait main_task 11004 2 140045060 1 15 Accept/Select Wait t2 11005 3 140044840 1 15 Runnable t1 11006 * 4 140056040 1 15 Runnable t3 11007 (gdb) b 15 task 2 11008 Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. 11009 (gdb) cont 11010 Continuing. 11011 task # 1 running 11012 task # 2 running 11013 11014 Breakpoint 5, test_task_debug () at test_task_debug.adb:15 11015 15 flush; 11016 (gdb) info tasks 11017 ID TID P-ID Pri State Name 11018 1 140022020 0 15 Child Activation Wait main_task 11019 * 2 140045060 1 15 Runnable t2 11020 3 140044840 1 15 Runnable t1 11021 4 140056040 1 15 Delay Sleep t3 11022 11023 11024 File: gdb.info, Node: Ada Tasks and Core Files, Next: Ada Glitches, Prev: Ada Tasks, Up: Ada 11025 11026 15.4.6.6 Tasking Support when Debugging Core Files 11027 .................................................. 11028 11029 When inspecting a core file, as opposed to debugging a live program, 11030 tasking support may be limited or even unavailable, depending on the 11031 platform being used. For instance, on x86-linux, the list of tasks is 11032 available, but task switching is not supported. On Tru64, however, 11033 task switching will work as usual. 11034 11035 On certain platforms, including Tru64, the debugger needs to perform 11036 some memory writes in order to provide Ada tasking support. When 11037 inspecting a core file, this means that the core file must be opened 11038 with read-write privileges, using the command `"set write on"' (*note 11039 Patching::). Under these circumstances, you should make a backup copy 11040 of the core file before inspecting it with GDB. 11041 11042 11043 File: gdb.info, Node: Ada Glitches, Prev: Ada Tasks and Core Files, Up: Ada 11044 11045 15.4.6.7 Known Peculiarities of Ada Mode 11046 ........................................ 11047 11048 Besides the omissions listed previously (*note Omissions from Ada::), 11049 we know of several problems with and limitations of Ada mode in GDB, 11050 some of which will be fixed with planned future releases of the debugger 11051 and the GNU Ada compiler. 11052 11053 * Currently, the debugger has insufficient information to determine 11054 whether certain pointers represent pointers to objects or the 11055 objects themselves. Thus, the user may have to tack an extra 11056 `.all' after an expression to get it printed properly. 11057 11058 * Static constants that the compiler chooses not to materialize as 11059 objects in storage are invisible to the debugger. 11060 11061 * Named parameter associations in function argument lists are 11062 ignored (the argument lists are treated as positional). 11063 11064 * Many useful library packages are currently invisible to the 11065 debugger. 11066 11067 * Fixed-point arithmetic, conversions, input, and output is carried 11068 out using floating-point arithmetic, and may give results that 11069 only approximate those on the host machine. 11070 11071 * The GNAT compiler never generates the prefix `Standard' for any of 11072 the standard symbols defined by the Ada language. GDB knows about 11073 this: it will strip the prefix from names when you use it, and 11074 will never look for a name you have so qualified among local 11075 symbols, nor match against symbols in other packages or 11076 subprograms. If you have defined entities anywhere in your 11077 program other than parameters and local variables whose simple 11078 names match names in `Standard', GNAT's lack of qualification here 11079 can cause confusion. When this happens, you can usually resolve 11080 the confusion by qualifying the problematic names with package 11081 `Standard' explicitly. 11082 11083 Older versions of the compiler sometimes generate erroneous debugging 11084 information, resulting in the debugger incorrectly printing the value 11085 of affected entities. In some cases, the debugger is able to work 11086 around an issue automatically. In other cases, the debugger is able to 11087 work around the issue, but the work-around has to be specifically 11088 enabled. 11089 11090 `set ada trust-PAD-over-XVS on' 11091 Configure GDB to strictly follow the GNAT encoding when computing 11092 the value of Ada entities, particularly when `PAD' and `PAD___XVS' 11093 types are involved (see `ada/exp_dbug.ads' in the GCC sources for 11094 a complete description of the encoding used by the GNAT compiler). 11095 This is the default. 11096 11097 `set ada trust-PAD-over-XVS off' 11098 This is related to the encoding using by the GNAT compiler. If 11099 GDB sometimes prints the wrong value for certain entities, 11100 changing `ada trust-PAD-over-XVS' to `off' activates a work-around 11101 which may fix the issue. It is always safe to set `ada 11102 trust-PAD-over-XVS' to `off', but this incurs a slight performance 11103 penalty, so it is recommended to leave this setting to `on' unless 11104 necessary. 11105 11106 11107 11108 File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages 11109 11110 15.5 Unsupported Languages 11111 ========================== 11112 11113 In addition to the other fully-supported programming languages, GDB 11114 also provides a pseudo-language, called `minimal'. It does not 11115 represent a real programming language, but provides a set of 11116 capabilities close to what the C or assembly languages provide. This 11117 should allow most simple operations to be performed while debugging an 11118 application that uses a language currently not supported by GDB. 11119 11120 If the language is set to `auto', GDB will automatically select this 11121 language if the current frame corresponds to an unsupported language. 11122 11123 11124 File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top 11125 11126 16 Examining the Symbol Table 11127 ***************************** 11128 11129 The commands described in this chapter allow you to inquire about the 11130 symbols (names of variables, functions and types) defined in your 11131 program. This information is inherent in the text of your program and 11132 does not change as your program executes. GDB finds it in your 11133 program's symbol table, in the file indicated when you started GDB 11134 (*note Choosing Files: File Options.), or by one of the file-management 11135 commands (*note Commands to Specify Files: Files.). 11136 11137 Occasionally, you may need to refer to symbols that contain unusual 11138 characters, which GDB ordinarily treats as word delimiters. The most 11139 frequent case is in referring to static variables in other source files 11140 (*note Program Variables: Variables.). File names are recorded in 11141 object files as debugging symbols, but GDB would ordinarily parse a 11142 typical file name, like `foo.c', as the three words `foo' `.' `c'. To 11143 allow GDB to recognize `foo.c' as a single symbol, enclose it in single 11144 quotes; for example, 11145 11146 p 'foo.c'::x 11147 11148 looks up the value of `x' in the scope of the file `foo.c'. 11149 11150 `set case-sensitive on' 11151 `set case-sensitive off' 11152 `set case-sensitive auto' 11153 Normally, when GDB looks up symbols, it matches their names with 11154 case sensitivity determined by the current source language. 11155 Occasionally, you may wish to control that. The command `set 11156 case-sensitive' lets you do that by specifying `on' for 11157 case-sensitive matches or `off' for case-insensitive ones. If you 11158 specify `auto', case sensitivity is reset to the default suitable 11159 for the source language. The default is case-sensitive matches 11160 for all languages except for Fortran, for which the default is 11161 case-insensitive matches. 11162 11163 `show case-sensitive' 11164 This command shows the current setting of case sensitivity for 11165 symbols lookups. 11166 11167 `info address SYMBOL' 11168 Describe where the data for SYMBOL is stored. For a register 11169 variable, this says which register it is kept in. For a 11170 non-register local variable, this prints the stack-frame offset at 11171 which the variable is always stored. 11172 11173 Note the contrast with `print &SYMBOL', which does not work at all 11174 for a register variable, and for a stack local variable prints the 11175 exact address of the current instantiation of the variable. 11176 11177 `info symbol ADDR' 11178 Print the name of a symbol which is stored at the address ADDR. 11179 If no symbol is stored exactly at ADDR, GDB prints the nearest 11180 symbol and an offset from it: 11181 11182 (gdb) info symbol 0x54320 11183 _initialize_vx + 396 in section .text 11184 11185 This is the opposite of the `info address' command. You can use 11186 it to find out the name of a variable or a function given its 11187 address. 11188 11189 For dynamically linked executables, the name of executable or 11190 shared library containing the symbol is also printed: 11191 11192 (gdb) info symbol 0x400225 11193 _start + 5 in section .text of /tmp/a.out 11194 (gdb) info symbol 0x2aaaac2811cf 11195 __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 11196 11197 `whatis [ARG]' 11198 Print the data type of ARG, which can be either an expression or a 11199 data type. With no argument, print the data type of `$', the last 11200 value in the value history. If ARG is an expression, it is not 11201 actually evaluated, and any side-effecting operations (such as 11202 assignments or function calls) inside it do not take place. If 11203 ARG is a type name, it may be the name of a type or typedef, or 11204 for C code it may have the form `class CLASS-NAME', `struct 11205 STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'. *Note 11206 Expressions: Expressions. 11207 11208 `ptype [ARG]' 11209 `ptype' accepts the same arguments as `whatis', but prints a 11210 detailed description of the type, instead of just the name of the 11211 type. *Note Expressions: Expressions. 11212 11213 For example, for this variable declaration: 11214 11215 struct complex {double real; double imag;} v; 11216 11217 the two commands give this output: 11218 11219 (gdb) whatis v 11220 type = struct complex 11221 (gdb) ptype v 11222 type = struct complex { 11223 double real; 11224 double imag; 11225 } 11226 11227 As with `whatis', using `ptype' without an argument refers to the 11228 type of `$', the last value in the value history. 11229 11230 Sometimes, programs use opaque data types or incomplete 11231 specifications of complex data structure. If the debug 11232 information included in the program does not allow GDB to display 11233 a full declaration of the data type, it will say `<incomplete 11234 type>'. For example, given these declarations: 11235 11236 struct foo; 11237 struct foo *fooptr; 11238 11239 but no definition for `struct foo' itself, GDB will say: 11240 11241 (gdb) ptype foo 11242 $1 = <incomplete type> 11243 11244 "Incomplete type" is C terminology for data types that are not 11245 completely specified. 11246 11247 `info types REGEXP' 11248 `info types' 11249 Print a brief description of all types whose names match the 11250 regular expression REGEXP (or all types in your program, if you 11251 supply no argument). Each complete typename is matched as though 11252 it were a complete line; thus, `i type value' gives information on 11253 all types in your program whose names include the string `value', 11254 but `i type ^value$' gives information only on types whose complete 11255 name is `value'. 11256 11257 This command differs from `ptype' in two ways: first, like 11258 `whatis', it does not print a detailed description; second, it 11259 lists all source files where a type is defined. 11260 11261 `info scope LOCATION' 11262 List all the variables local to a particular scope. This command 11263 accepts a LOCATION argument--a function name, a source line, or an 11264 address preceded by a `*', and prints all the variables local to 11265 the scope defined by that location. (*Note Specify Location::, for 11266 details about supported forms of LOCATION.) For example: 11267 11268 (gdb) info scope command_line_handler 11269 Scope for command_line_handler: 11270 Symbol rl is an argument at stack/frame offset 8, length 4. 11271 Symbol linebuffer is in static storage at address 0x150a18, length 4. 11272 Symbol linelength is in static storage at address 0x150a1c, length 4. 11273 Symbol p is a local variable in register $esi, length 4. 11274 Symbol p1 is a local variable in register $ebx, length 4. 11275 Symbol nline is a local variable in register $edx, length 4. 11276 Symbol repeat is a local variable at frame offset -8, length 4. 11277 11278 This command is especially useful for determining what data to 11279 collect during a "trace experiment", see *Note collect: Tracepoint 11280 Actions. 11281 11282 `info source' 11283 Show information about the current source file--that is, the 11284 source file for the function containing the current point of 11285 execution: 11286 * the name of the source file, and the directory containing it, 11287 11288 * the directory it was compiled in, 11289 11290 * its length, in lines, 11291 11292 * which programming language it is written in, 11293 11294 * whether the executable includes debugging information for 11295 that file, and if so, what format the information is in 11296 (e.g., STABS, Dwarf 2, etc.), and 11297 11298 * whether the debugging information includes information about 11299 preprocessor macros. 11300 11301 `info sources' 11302 Print the names of all source files in your program for which 11303 there is debugging information, organized into two lists: files 11304 whose symbols have already been read, and files whose symbols will 11305 be read when needed. 11306 11307 `info functions' 11308 Print the names and data types of all defined functions. 11309 11310 `info functions REGEXP' 11311 Print the names and data types of all defined functions whose 11312 names contain a match for regular expression REGEXP. Thus, `info 11313 fun step' finds all functions whose names include `step'; `info 11314 fun ^step' finds those whose names start with `step'. If a 11315 function name contains characters that conflict with the regular 11316 expression language (e.g. `operator*()'), they may be quoted with 11317 a backslash. 11318 11319 `info variables' 11320 Print the names and data types of all variables that are defined 11321 outside of functions (i.e. excluding local variables). 11322 11323 `info variables REGEXP' 11324 Print the names and data types of all variables (except for local 11325 variables) whose names contain a match for regular expression 11326 REGEXP. 11327 11328 `info classes' 11329 `info classes REGEXP' 11330 Display all Objective-C classes in your program, or (with the 11331 REGEXP argument) all those matching a particular regular 11332 expression. 11333 11334 `info selectors' 11335 `info selectors REGEXP' 11336 Display all Objective-C selectors in your program, or (with the 11337 REGEXP argument) all those matching a particular regular 11338 expression. 11339 11340 Some systems allow individual object files that make up your 11341 program to be replaced without stopping and restarting your 11342 program. For example, in VxWorks you can simply recompile a 11343 defective object file and keep on running. If you are running on 11344 one of these systems, you can allow GDB to reload the symbols for 11345 automatically relinked modules: 11346 11347 `set symbol-reloading on' 11348 Replace symbol definitions for the corresponding source file 11349 when an object file with a particular name is seen again. 11350 11351 `set symbol-reloading off' 11352 Do not replace symbol definitions when encountering object 11353 files of the same name more than once. This is the default 11354 state; if you are not running on a system that permits 11355 automatic relinking of modules, you should leave 11356 `symbol-reloading' off, since otherwise GDB may discard 11357 symbols when linking large programs, that may contain several 11358 modules (from different directories or libraries) with the 11359 same name. 11360 11361 `show symbol-reloading' 11362 Show the current `on' or `off' setting. 11363 11364 `set opaque-type-resolution on' 11365 Tell GDB to resolve opaque types. An opaque type is a type 11366 declared as a pointer to a `struct', `class', or `union'--for 11367 example, `struct MyType *'--that is used in one source file 11368 although the full declaration of `struct MyType' is in another 11369 source file. The default is on. 11370 11371 A change in the setting of this subcommand will not take effect 11372 until the next time symbols for a file are loaded. 11373 11374 `set opaque-type-resolution off' 11375 Tell GDB not to resolve opaque types. In this case, the type is 11376 printed as follows: 11377 {<no data fields>} 11378 11379 `show opaque-type-resolution' 11380 Show whether opaque types are resolved or not. 11381 11382 `maint print symbols FILENAME' 11383 `maint print psymbols FILENAME' 11384 `maint print msymbols FILENAME' 11385 Write a dump of debugging symbol data into the file FILENAME. 11386 These commands are used to debug the GDB symbol-reading code. Only 11387 symbols with debugging data are included. If you use `maint print 11388 symbols', GDB includes all the symbols for which it has already 11389 collected full details: that is, FILENAME reflects symbols for 11390 only those files whose symbols GDB has read. You can use the 11391 command `info sources' to find out which files these are. If you 11392 use `maint print psymbols' instead, the dump shows information 11393 about symbols that GDB only knows partially--that is, symbols 11394 defined in files that GDB has skimmed, but not yet read 11395 completely. Finally, `maint print msymbols' dumps just the 11396 minimal symbol information required for each object file from 11397 which GDB has read some symbols. *Note Commands to Specify Files: 11398 Files, for a discussion of how GDB reads symbols (in the 11399 description of `symbol-file'). 11400 11401 `maint info symtabs [ REGEXP ]' 11402 `maint info psymtabs [ REGEXP ]' 11403 List the `struct symtab' or `struct partial_symtab' structures 11404 whose names match REGEXP. If REGEXP is not given, list them all. 11405 The output includes expressions which you can copy into a GDB 11406 debugging this one to examine a particular structure in more 11407 detail. For example: 11408 11409 (gdb) maint info psymtabs dwarf2read 11410 { objfile /home/gnu/build/gdb/gdb 11411 ((struct objfile *) 0x82e69d0) 11412 { psymtab /home/gnu/src/gdb/dwarf2read.c 11413 ((struct partial_symtab *) 0x8474b10) 11414 readin no 11415 fullname (null) 11416 text addresses 0x814d3c8 -- 0x8158074 11417 globals (* (struct partial_symbol **) 0x8507a08 @ 9) 11418 statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) 11419 dependencies (none) 11420 } 11421 } 11422 (gdb) maint info symtabs 11423 (gdb) 11424 We see that there is one partial symbol table whose filename 11425 contains the string `dwarf2read', belonging to the `gdb' 11426 executable; and we see that GDB has not read in any symtabs yet at 11427 all. If we set a breakpoint on a function, that will cause GDB to 11428 read the symtab for the compilation unit containing that function: 11429 11430 (gdb) break dwarf2_psymtab_to_symtab 11431 Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, 11432 line 1574. 11433 (gdb) maint info symtabs 11434 { objfile /home/gnu/build/gdb/gdb 11435 ((struct objfile *) 0x82e69d0) 11436 { symtab /home/gnu/src/gdb/dwarf2read.c 11437 ((struct symtab *) 0x86c1f38) 11438 dirname (null) 11439 fullname (null) 11440 blockvector ((struct blockvector *) 0x86c1bd0) (primary) 11441 linetable ((struct linetable *) 0x8370fa0) 11442 debugformat DWARF 2 11443 } 11444 } 11445 (gdb) 11446 11447 11448 File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top 11449 11450 17 Altering Execution 11451 ********************* 11452 11453 Once you think you have found an error in your program, you might want 11454 to find out for certain whether correcting the apparent error would 11455 lead to correct results in the rest of the run. You can find the 11456 answer by experiment, using the GDB features for altering execution of 11457 the program. 11458 11459 For example, you can store new values into variables or memory 11460 locations, give your program a signal, restart it at a different 11461 address, or even return prematurely from a function. 11462 11463 * Menu: 11464 11465 * Assignment:: Assignment to variables 11466 * Jumping:: Continuing at a different address 11467 * Signaling:: Giving your program a signal 11468 * Returning:: Returning from a function 11469 * Calling:: Calling your program's functions 11470 * Patching:: Patching your program 11471 11472 11473 File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering 11474 11475 17.1 Assignment to Variables 11476 ============================ 11477 11478 To alter the value of a variable, evaluate an assignment expression. 11479 *Note Expressions: Expressions. For example, 11480 11481 print x=4 11482 11483 stores the value 4 into the variable `x', and then prints the value of 11484 the assignment expression (which is 4). *Note Using GDB with Different 11485 Languages: Languages, for more information on operators in supported 11486 languages. 11487 11488 If you are not interested in seeing the value of the assignment, use 11489 the `set' command instead of the `print' command. `set' is really the 11490 same as `print' except that the expression's value is not printed and 11491 is not put in the value history (*note Value History: Value History.). 11492 The expression is evaluated only for its effects. 11493 11494 If the beginning of the argument string of the `set' command appears 11495 identical to a `set' subcommand, use the `set variable' command instead 11496 of just `set'. This command is identical to `set' except for its lack 11497 of subcommands. For example, if your program has a variable `width', 11498 you get an error if you try to set a new value with just `set 11499 width=13', because GDB has the command `set width': 11500 11501 (gdb) whatis width 11502 type = double 11503 (gdb) p width 11504 $4 = 13 11505 (gdb) set width=47 11506 Invalid syntax in expression. 11507 11508 The invalid expression, of course, is `=47'. In order to actually set 11509 the program's variable `width', use 11510 11511 (gdb) set var width=47 11512 11513 Because the `set' command has many subcommands that can conflict 11514 with the names of program variables, it is a good idea to use the `set 11515 variable' command instead of just `set'. For example, if your program 11516 has a variable `g', you run into problems if you try to set a new value 11517 with just `set g=4', because GDB has the command `set gnutarget', 11518 abbreviated `set g': 11519 11520 (gdb) whatis g 11521 type = double 11522 (gdb) p g 11523 $1 = 1 11524 (gdb) set g=4 11525 (gdb) p g 11526 $2 = 1 11527 (gdb) r 11528 The program being debugged has been started already. 11529 Start it from the beginning? (y or n) y 11530 Starting program: /home/smith/cc_progs/a.out 11531 "/home/smith/cc_progs/a.out": can't open to read symbols: 11532 Invalid bfd target. 11533 (gdb) show g 11534 The current BFD target is "=4". 11535 11536 The program variable `g' did not change, and you silently set the 11537 `gnutarget' to an invalid value. In order to set the variable `g', use 11538 11539 (gdb) set var g=4 11540 11541 GDB allows more implicit conversions in assignments than C; you can 11542 freely store an integer value into a pointer variable or vice versa, 11543 and you can convert any structure to any other structure that is the 11544 same length or shorter. 11545 11546 To store values into arbitrary places in memory, use the `{...}' 11547 construct to generate a value of specified type at a specified address 11548 (*note Expressions: Expressions.). For example, `{int}0x83040' refers 11549 to memory location `0x83040' as an integer (which implies a certain size 11550 and representation in memory), and 11551 11552 set {int}0x83040 = 4 11553 11554 stores the value 4 into that memory location. 11555 11556 11557 File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering 11558 11559 17.2 Continuing at a Different Address 11560 ====================================== 11561 11562 Ordinarily, when you continue your program, you do so at the place where 11563 it stopped, with the `continue' command. You can instead continue at 11564 an address of your own choosing, with the following commands: 11565 11566 `jump LINESPEC' 11567 `jump LOCATION' 11568 Resume execution at line LINESPEC or at address given by LOCATION. 11569 Execution stops again immediately if there is a breakpoint there. 11570 *Note Specify Location::, for a description of the different 11571 forms of LINESPEC and LOCATION. It is common practice to use the 11572 `tbreak' command in conjunction with `jump'. *Note Setting 11573 Breakpoints: Set Breaks. 11574 11575 The `jump' command does not change the current stack frame, or the 11576 stack pointer, or the contents of any memory location or any 11577 register other than the program counter. If line LINESPEC is in a 11578 different function from the one currently executing, the results 11579 may be bizarre if the two functions expect different patterns of 11580 arguments or of local variables. For this reason, the `jump' 11581 command requests confirmation if the specified line is not in the 11582 function currently executing. However, even bizarre results are 11583 predictable if you are well acquainted with the machine-language 11584 code of your program. 11585 11586 On many systems, you can get much the same effect as the `jump' 11587 command by storing a new value into the register `$pc'. The difference 11588 is that this does not start your program running; it only changes the 11589 address of where it _will_ run when you continue. For example, 11590 11591 set $pc = 0x485 11592 11593 makes the next `continue' command or stepping command execute at 11594 address `0x485', rather than at the address where your program stopped. 11595 *Note Continuing and Stepping: Continuing and Stepping. 11596 11597 The most common occasion to use the `jump' command is to back 11598 up--perhaps with more breakpoints set--over a portion of a program that 11599 has already executed, in order to examine its execution in more detail. 11600 11601 11602 File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering 11603 11604 17.3 Giving your Program a Signal 11605 ================================= 11606 11607 `signal SIGNAL' 11608 Resume execution where your program stopped, but immediately give 11609 it the signal SIGNAL. SIGNAL can be the name or the number of a 11610 signal. For example, on many systems `signal 2' and `signal 11611 SIGINT' are both ways of sending an interrupt signal. 11612 11613 Alternatively, if SIGNAL is zero, continue execution without 11614 giving a signal. This is useful when your program stopped on 11615 account of a signal and would ordinary see the signal when resumed 11616 with the `continue' command; `signal 0' causes it to resume 11617 without a signal. 11618 11619 `signal' does not repeat when you press <RET> a second time after 11620 executing the command. 11621 11622 Invoking the `signal' command is not the same as invoking the `kill' 11623 utility from the shell. Sending a signal with `kill' causes GDB to 11624 decide what to do with the signal depending on the signal handling 11625 tables (*note Signals::). The `signal' command passes the signal 11626 directly to your program. 11627 11628 11629 File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering 11630 11631 17.4 Returning from a Function 11632 ============================== 11633 11634 `return' 11635 `return EXPRESSION' 11636 You can cancel execution of a function call with the `return' 11637 command. If you give an EXPRESSION argument, its value is used as 11638 the function's return value. 11639 11640 When you use `return', GDB discards the selected stack frame (and 11641 all frames within it). You can think of this as making the discarded 11642 frame return prematurely. If you wish to specify a value to be 11643 returned, give that value as the argument to `return'. 11644 11645 This pops the selected stack frame (*note Selecting a Frame: 11646 Selection.), and any other frames inside of it, leaving its caller as 11647 the innermost remaining frame. That frame becomes selected. The 11648 specified value is stored in the registers used for returning values of 11649 functions. 11650 11651 The `return' command does not resume execution; it leaves the 11652 program stopped in the state that would exist if the function had just 11653 returned. In contrast, the `finish' command (*note Continuing and 11654 Stepping: Continuing and Stepping.) resumes execution until the 11655 selected stack frame returns naturally. 11656 11657 GDB needs to know how the EXPRESSION argument should be set for the 11658 inferior. The concrete registers assignment depends on the OS ABI and 11659 the type being returned by the selected stack frame. For example it is 11660 common for OS ABI to return floating point values in FPU registers 11661 while integer values in CPU registers. Still some ABIs return even 11662 floating point values in CPU registers. Larger integer widths (such as 11663 `long long int') also have specific placement rules. GDB already knows 11664 the OS ABI from its current target so it needs to find out also the 11665 type being returned to make the assignment into the right register(s). 11666 11667 Normally, the selected stack frame has debug info. GDB will always 11668 use the debug info instead of the implicit type of EXPRESSION when the 11669 debug info is available. For example, if you type `return -1', and the 11670 function in the current stack frame is declared to return a `long long 11671 int', GDB transparently converts the implicit `int' value of -1 into a 11672 `long long int': 11673 11674 Breakpoint 1, func () at gdb.base/return-nodebug.c:29 11675 29 return 31; 11676 (gdb) return -1 11677 Make func return now? (y or n) y 11678 #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 11679 43 printf ("result=%lld\n", func ()); 11680 (gdb) 11681 11682 However, if the selected stack frame does not have a debug info, 11683 e.g., if the function was compiled without debug info, GDB has to find 11684 out the type to return from user. Specifying a different type by 11685 mistake may set the value in different inferior registers than the 11686 caller code expects. For example, typing `return -1' with its implicit 11687 type `int' would set only a part of a `long long int' result for a 11688 debug info less function (on 32-bit architectures). Therefore the user 11689 is required to specify the return type by an appropriate cast 11690 explicitly: 11691 11692 Breakpoint 2, 0x0040050b in func () 11693 (gdb) return -1 11694 Return value type not available for selected stack frame. 11695 Please use an explicit cast of the value to return. 11696 (gdb) return (long long int) -1 11697 Make selected stack frame return now? (y or n) y 11698 #0 0x00400526 in main () 11699 (gdb) 11700 11701 11702 File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering 11703 11704 17.5 Calling Program Functions 11705 ============================== 11706 11707 `print EXPR' 11708 Evaluate the expression EXPR and display the resulting value. 11709 EXPR may include calls to functions in the program being debugged. 11710 11711 `call EXPR' 11712 Evaluate the expression EXPR without displaying `void' returned 11713 values. 11714 11715 You can use this variant of the `print' command if you want to 11716 execute a function from your program that does not return anything 11717 (a.k.a. "a void function"), but without cluttering the output with 11718 `void' returned values that GDB will otherwise print. If the 11719 result is not void, it is printed and saved in the value history. 11720 11721 It is possible for the function you call via the `print' or `call' 11722 command to generate a signal (e.g., if there's a bug in the function, 11723 or if you passed it incorrect arguments). What happens in that case is 11724 controlled by the `set unwindonsignal' command. 11725 11726 Similarly, with a C++ program it is possible for the function you 11727 call via the `print' or `call' command to generate an exception that is 11728 not handled due to the constraints of the dummy frame. In this case, 11729 any exception that is raised in the frame, but has an out-of-frame 11730 exception handler will not be found. GDB builds a dummy-frame for the 11731 inferior function call, and the unwinder cannot seek for exception 11732 handlers outside of this dummy-frame. What happens in that case is 11733 controlled by the `set unwind-on-terminating-exception' command. 11734 11735 `set unwindonsignal' 11736 Set unwinding of the stack if a signal is received while in a 11737 function that GDB called in the program being debugged. If set to 11738 on, GDB unwinds the stack it created for the call and restores the 11739 context to what it was before the call. If set to off (the 11740 default), GDB stops in the frame where the signal was received. 11741 11742 `show unwindonsignal' 11743 Show the current setting of stack unwinding in the functions 11744 called by GDB. 11745 11746 `set unwind-on-terminating-exception' 11747 Set unwinding of the stack if a C++ exception is raised, but left 11748 unhandled while in a function that GDB called in the program being 11749 debugged. If set to on (the default), GDB unwinds the stack it 11750 created for the call and restores the context to what it was before 11751 the call. If set to off, GDB the exception is delivered to the 11752 default C++ exception handler and the inferior terminated. 11753 11754 `show unwind-on-terminating-exception' 11755 Show the current setting of stack unwinding in the functions 11756 called by GDB. 11757 11758 11759 Sometimes, a function you wish to call is actually a "weak alias" 11760 for another function. In such case, GDB might not pick up the type 11761 information, including the types of the function arguments, which 11762 causes GDB to call the inferior function incorrectly. As a result, the 11763 called function will function erroneously and may even crash. A 11764 solution to that is to use the name of the aliased function instead. 11765 11766 11767 File: gdb.info, Node: Patching, Prev: Calling, Up: Altering 11768 11769 17.6 Patching Programs 11770 ====================== 11771 11772 By default, GDB opens the file containing your program's executable 11773 code (or the corefile) read-only. This prevents accidental alterations 11774 to machine code; but it also prevents you from intentionally patching 11775 your program's binary. 11776 11777 If you'd like to be able to patch the binary, you can specify that 11778 explicitly with the `set write' command. For example, you might want 11779 to turn on internal debugging flags, or even to make emergency repairs. 11780 11781 `set write on' 11782 `set write off' 11783 If you specify `set write on', GDB opens executable and core files 11784 for both reading and writing; if you specify `set write off' (the 11785 default), GDB opens them read-only. 11786 11787 If you have already loaded a file, you must load it again (using 11788 the `exec-file' or `core-file' command) after changing `set 11789 write', for your new setting to take effect. 11790 11791 `show write' 11792 Display whether executable files and core files are opened for 11793 writing as well as reading. 11794 11795 11796 File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top 11797 11798 18 GDB Files 11799 ************ 11800 11801 GDB needs to know the file name of the program to be debugged, both in 11802 order to read its symbol table and in order to start your program. To 11803 debug a core dump of a previous run, you must also tell GDB the name of 11804 the core dump file. 11805 11806 * Menu: 11807 11808 * Files:: Commands to specify files 11809 * Separate Debug Files:: Debugging information in separate files 11810 * Symbol Errors:: Errors reading symbol files 11811 * Data Files:: GDB data files 11812 11813 11814 File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files 11815 11816 18.1 Commands to Specify Files 11817 ============================== 11818 11819 You may want to specify executable and core dump file names. The usual 11820 way to do this is at start-up time, using the arguments to GDB's 11821 start-up commands (*note Getting In and Out of GDB: Invocation.). 11822 11823 Occasionally it is necessary to change to a different file during a 11824 GDB session. Or you may run GDB and forget to specify a file you want 11825 to use. Or you are debugging a remote target via `gdbserver' (*note 11826 file: Server.). In these situations the GDB commands to specify new 11827 files are useful. 11828 11829 `file FILENAME' 11830 Use FILENAME as the program to be debugged. It is read for its 11831 symbols and for the contents of pure memory. It is also the 11832 program executed when you use the `run' command. If you do not 11833 specify a directory and the file is not found in the GDB working 11834 directory, GDB uses the environment variable `PATH' as a list of 11835 directories to search, just as the shell does when looking for a 11836 program to run. You can change the value of this variable, for 11837 both GDB and your program, using the `path' command. 11838 11839 You can load unlinked object `.o' files into GDB using the `file' 11840 command. You will not be able to "run" an object file, but you 11841 can disassemble functions and inspect variables. Also, if the 11842 underlying BFD functionality supports it, you could use `gdb 11843 -write' to patch object files using this technique. Note that GDB 11844 can neither interpret nor modify relocations in this case, so 11845 branches and some initialized variables will appear to go to the 11846 wrong place. But this feature is still handy from time to time. 11847 11848 `file' 11849 `file' with no argument makes GDB discard any information it has 11850 on both executable file and the symbol table. 11851 11852 `exec-file [ FILENAME ]' 11853 Specify that the program to be run (but not the symbol table) is 11854 found in FILENAME. GDB searches the environment variable `PATH' 11855 if necessary to locate your program. Omitting FILENAME means to 11856 discard information on the executable file. 11857 11858 `symbol-file [ FILENAME ]' 11859 Read symbol table information from file FILENAME. `PATH' is 11860 searched when necessary. Use the `file' command to get both symbol 11861 table and program to run from the same file. 11862 11863 `symbol-file' with no argument clears out GDB information on your 11864 program's symbol table. 11865 11866 The `symbol-file' command causes GDB to forget the contents of 11867 some breakpoints and auto-display expressions. This is because 11868 they may contain pointers to the internal data recording symbols 11869 and data types, which are part of the old symbol table data being 11870 discarded inside GDB. 11871 11872 `symbol-file' does not repeat if you press <RET> again after 11873 executing it once. 11874 11875 When GDB is configured for a particular environment, it 11876 understands debugging information in whatever format is the 11877 standard generated for that environment; you may use either a GNU 11878 compiler, or other compilers that adhere to the local conventions. 11879 Best results are usually obtained from GNU compilers; for example, 11880 using `GCC' you can generate debugging information for optimized 11881 code. 11882 11883 For most kinds of object files, with the exception of old SVR3 11884 systems using COFF, the `symbol-file' command does not normally 11885 read the symbol table in full right away. Instead, it scans the 11886 symbol table quickly to find which source files and which symbols 11887 are present. The details are read later, one source file at a 11888 time, as they are needed. 11889 11890 The purpose of this two-stage reading strategy is to make GDB 11891 start up faster. For the most part, it is invisible except for 11892 occasional pauses while the symbol table details for a particular 11893 source file are being read. (The `set verbose' command can turn 11894 these pauses into messages if desired. *Note Optional Warnings 11895 and Messages: Messages/Warnings.) 11896 11897 We have not implemented the two-stage strategy for COFF yet. When 11898 the symbol table is stored in COFF format, `symbol-file' reads the 11899 symbol table data in full right away. Note that "stabs-in-COFF" 11900 still does the two-stage strategy, since the debug info is actually 11901 in stabs format. 11902 11903 `symbol-file [ -readnow ] FILENAME' 11904 `file [ -readnow ] FILENAME' 11905 You can override the GDB two-stage strategy for reading symbol 11906 tables by using the `-readnow' option with any of the commands that 11907 load symbol table information, if you want to be sure GDB has the 11908 entire symbol table available. 11909 11910 `core-file [FILENAME]' 11911 `core' 11912 Specify the whereabouts of a core dump file to be used as the 11913 "contents of memory". Traditionally, core files contain only some 11914 parts of the address space of the process that generated them; GDB 11915 can access the executable file itself for other parts. 11916 11917 `core-file' with no argument specifies that no core file is to be 11918 used. 11919 11920 Note that the core file is ignored when your program is actually 11921 running under GDB. So, if you have been running your program and 11922 you wish to debug a core file instead, you must kill the 11923 subprocess in which the program is running. To do this, use the 11924 `kill' command (*note Killing the Child Process: Kill Process.). 11925 11926 `add-symbol-file FILENAME ADDRESS' 11927 `add-symbol-file FILENAME ADDRESS [ -readnow ]' 11928 `add-symbol-file FILENAME -sSECTION ADDRESS ...' 11929 The `add-symbol-file' command reads additional symbol table 11930 information from the file FILENAME. You would use this command 11931 when FILENAME has been dynamically loaded (by some other means) 11932 into the program that is running. ADDRESS should be the memory 11933 address at which the file has been loaded; GDB cannot figure this 11934 out for itself. You can additionally specify an arbitrary number 11935 of `-sSECTION ADDRESS' pairs, to give an explicit section name and 11936 base address for that section. You can specify any ADDRESS as an 11937 expression. 11938 11939 The symbol table of the file FILENAME is added to the symbol table 11940 originally read with the `symbol-file' command. You can use the 11941 `add-symbol-file' command any number of times; the new symbol data 11942 thus read keeps adding to the old. To discard all old symbol data 11943 instead, use the `symbol-file' command without any arguments. 11944 11945 Although FILENAME is typically a shared library file, an 11946 executable file, or some other object file which has been fully 11947 relocated for loading into a process, you can also load symbolic 11948 information from relocatable `.o' files, as long as: 11949 11950 * the file's symbolic information refers only to linker symbols 11951 defined in that file, not to symbols defined by other object 11952 files, 11953 11954 * every section the file's symbolic information refers to has 11955 actually been loaded into the inferior, as it appears in the 11956 file, and 11957 11958 * you can determine the address at which every section was 11959 loaded, and provide these to the `add-symbol-file' command. 11960 11961 Some embedded operating systems, like Sun Chorus and VxWorks, can 11962 load relocatable files into an already running program; such 11963 systems typically make the requirements above easy to meet. 11964 However, it's important to recognize that many native systems use 11965 complex link procedures (`.linkonce' section factoring and C++ 11966 constructor table assembly, for example) that make the 11967 requirements difficult to meet. In general, one cannot assume 11968 that using `add-symbol-file' to read a relocatable object file's 11969 symbolic information will have the same effect as linking the 11970 relocatable object file into the program in the normal way. 11971 11972 `add-symbol-file' does not repeat if you press <RET> after using 11973 it. 11974 11975 `add-symbol-file-from-memory ADDRESS' 11976 Load symbols from the given ADDRESS in a dynamically loaded object 11977 file whose image is mapped directly into the inferior's memory. 11978 For example, the Linux kernel maps a `syscall DSO' into each 11979 process's address space; this DSO provides kernel-specific code for 11980 some system calls. The argument can be any expression whose 11981 evaluation yields the address of the file's shared object file 11982 header. For this command to work, you must have used 11983 `symbol-file' or `exec-file' commands in advance. 11984 11985 `add-shared-symbol-files LIBRARY-FILE' 11986 `assf LIBRARY-FILE' 11987 The `add-shared-symbol-files' command can currently be used only 11988 in the Cygwin build of GDB on MS-Windows OS, where it is an alias 11989 for the `dll-symbols' command (*note Cygwin Native::). GDB 11990 automatically looks for shared libraries, however if GDB does not 11991 find yours, you can invoke `add-shared-symbol-files'. It takes 11992 one argument: the shared library's file name. `assf' is a 11993 shorthand alias for `add-shared-symbol-files'. 11994 11995 `section SECTION ADDR' 11996 The `section' command changes the base address of the named 11997 SECTION of the exec file to ADDR. This can be used if the exec 11998 file does not contain section addresses, (such as in the `a.out' 11999 format), or when the addresses specified in the file itself are 12000 wrong. Each section must be changed separately. The `info files' 12001 command, described below, lists all the sections and their 12002 addresses. 12003 12004 `info files' 12005 `info target' 12006 `info files' and `info target' are synonymous; both print the 12007 current target (*note Specifying a Debugging Target: Targets.), 12008 including the names of the executable and core dump files 12009 currently in use by GDB, and the files from which symbols were 12010 loaded. The command `help target' lists all possible targets 12011 rather than current ones. 12012 12013 `maint info sections' 12014 Another command that can give you extra information about program 12015 sections is `maint info sections'. In addition to the section 12016 information displayed by `info files', this command displays the 12017 flags and file offset of each section in the executable and core 12018 dump files. In addition, `maint info sections' provides the 12019 following command options (which may be arbitrarily combined): 12020 12021 `ALLOBJ' 12022 Display sections for all loaded object files, including 12023 shared libraries. 12024 12025 `SECTIONS' 12026 Display info only for named SECTIONS. 12027 12028 `SECTION-FLAGS' 12029 Display info only for sections for which SECTION-FLAGS are 12030 true. The section flags that GDB currently knows about are: 12031 `ALLOC' 12032 Section will have space allocated in the process when 12033 loaded. Set for all sections except those containing 12034 debug information. 12035 12036 `LOAD' 12037 Section will be loaded from the file into the child 12038 process memory. Set for pre-initialized code and data, 12039 clear for `.bss' sections. 12040 12041 `RELOC' 12042 Section needs to be relocated before loading. 12043 12044 `READONLY' 12045 Section cannot be modified by the child process. 12046 12047 `CODE' 12048 Section contains executable code only. 12049 12050 `DATA' 12051 Section contains data only (no executable code). 12052 12053 `ROM' 12054 Section will reside in ROM. 12055 12056 `CONSTRUCTOR' 12057 Section contains data for constructor/destructor lists. 12058 12059 `HAS_CONTENTS' 12060 Section is not empty. 12061 12062 `NEVER_LOAD' 12063 An instruction to the linker to not output the section. 12064 12065 `COFF_SHARED_LIBRARY' 12066 A notification to the linker that the section contains 12067 COFF shared library information. 12068 12069 `IS_COMMON' 12070 Section contains common symbols. 12071 12072 `set trust-readonly-sections on' 12073 Tell GDB that readonly sections in your object file really are 12074 read-only (i.e. that their contents will not change). In that 12075 case, GDB can fetch values from these sections out of the object 12076 file, rather than from the target program. For some targets 12077 (notably embedded ones), this can be a significant enhancement to 12078 debugging performance. 12079 12080 The default is off. 12081 12082 `set trust-readonly-sections off' 12083 Tell GDB not to trust readonly sections. This means that the 12084 contents of the section might change while the program is running, 12085 and must therefore be fetched from the target when needed. 12086 12087 `show trust-readonly-sections' 12088 Show the current setting of trusting readonly sections. 12089 12090 All file-specifying commands allow both absolute and relative file 12091 names as arguments. GDB always converts the file name to an absolute 12092 file name and remembers it that way. 12093 12094 GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and 12095 IBM RS/6000 AIX shared libraries. 12096 12097 On MS-Windows GDB must be linked with the Expat library to support 12098 shared libraries. *Note Expat::. 12099 12100 GDB automatically loads symbol definitions from shared libraries 12101 when you use the `run' command, or when you examine a core file. 12102 (Before you issue the `run' command, GDB does not understand references 12103 to a function in a shared library, however--unless you are debugging a 12104 core file). 12105 12106 On HP-UX, if the program loads a library explicitly, GDB 12107 automatically loads the symbols at the time of the `shl_load' call. 12108 12109 There are times, however, when you may wish to not automatically load 12110 symbol definitions from shared libraries, such as when they are 12111 particularly large or there are many of them. 12112 12113 To control the automatic loading of shared library symbols, use the 12114 commands: 12115 12116 `set auto-solib-add MODE' 12117 If MODE is `on', symbols from all shared object libraries will be 12118 loaded automatically when the inferior begins execution, you 12119 attach to an independently started inferior, or when the dynamic 12120 linker informs GDB that a new library has been loaded. If MODE is 12121 `off', symbols must be loaded manually, using the `sharedlibrary' 12122 command. The default value is `on'. 12123 12124 If your program uses lots of shared libraries with debug info that 12125 takes large amounts of memory, you can decrease the GDB memory 12126 footprint by preventing it from automatically loading the symbols 12127 from shared libraries. To that end, type `set auto-solib-add off' 12128 before running the inferior, then load each library whose debug 12129 symbols you do need with `sharedlibrary REGEXP', where REGEXP is a 12130 regular expression that matches the libraries whose symbols you 12131 want to be loaded. 12132 12133 `show auto-solib-add' 12134 Display the current autoloading mode. 12135 12136 To explicitly load shared library symbols, use the `sharedlibrary' 12137 command: 12138 12139 `info share REGEX' 12140 `info sharedlibrary REGEX' 12141 Print the names of the shared libraries which are currently loaded 12142 that match REGEX. If REGEX is omitted then print all shared 12143 libraries that are loaded. 12144 12145 `sharedlibrary REGEX' 12146 `share REGEX' 12147 Load shared object library symbols for files matching a Unix 12148 regular expression. As with files loaded automatically, it only 12149 loads shared libraries required by your program for a core file or 12150 after typing `run'. If REGEX is omitted all shared libraries 12151 required by your program are loaded. 12152 12153 `nosharedlibrary' 12154 Unload all shared object library symbols. This discards all 12155 symbols that have been loaded from all shared libraries. Symbols 12156 from shared libraries that were loaded by explicit user requests 12157 are not discarded. 12158 12159 Sometimes you may wish that GDB stops and gives you control when any 12160 of shared library events happen. Use the `set stop-on-solib-events' 12161 command for this: 12162 12163 `set stop-on-solib-events' 12164 This command controls whether GDB should give you control when the 12165 dynamic linker notifies it about some shared library event. The 12166 most common event of interest is loading or unloading of a new 12167 shared library. 12168 12169 `show stop-on-solib-events' 12170 Show whether GDB stops and gives you control when shared library 12171 events happen. 12172 12173 Shared libraries are also supported in many cross or remote debugging 12174 configurations. GDB needs to have access to the target's libraries; 12175 this can be accomplished either by providing copies of the libraries on 12176 the host system, or by asking GDB to automatically retrieve the 12177 libraries from the target. If copies of the target libraries are 12178 provided, they need to be the same as the target libraries, although the 12179 copies on the target can be stripped as long as the copies on the host 12180 are not. 12181 12182 For remote debugging, you need to tell GDB where the target 12183 libraries are, so that it can load the correct copies--otherwise, it 12184 may try to load the host's libraries. GDB has two variables to specify 12185 the search directories for target libraries. 12186 12187 `set sysroot PATH' 12188 Use PATH as the system root for the program being debugged. Any 12189 absolute shared library paths will be prefixed with PATH; many 12190 runtime loaders store the absolute paths to the shared library in 12191 the target program's memory. If you use `set sysroot' to find 12192 shared libraries, they need to be laid out in the same way that 12193 they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy 12194 under PATH. 12195 12196 If PATH starts with the sequence `remote:', GDB will retrieve the 12197 target libraries from the remote system. This is only supported 12198 when using a remote target that supports the `remote get' command 12199 (*note Sending files to a remote system: File Transfer.). The 12200 part of PATH following the initial `remote:' (if present) is used 12201 as system root prefix on the remote file system. (1) 12202 12203 The `set solib-absolute-prefix' command is an alias for `set 12204 sysroot'. 12205 12206 You can set the default system root by using the configure-time 12207 `--with-sysroot' option. If the system root is inside GDB's 12208 configured binary prefix (set with `--prefix' or `--exec-prefix'), 12209 then the default system root will be updated automatically if the 12210 installed GDB is moved to a new location. 12211 12212 `show sysroot' 12213 Display the current shared library prefix. 12214 12215 `set solib-search-path PATH' 12216 If this variable is set, PATH is a colon-separated list of 12217 directories to search for shared libraries. `solib-search-path' 12218 is used after `sysroot' fails to locate the library, or if the 12219 path to the library is relative instead of absolute. If you want 12220 to use `solib-search-path' instead of `sysroot', be sure to set 12221 `sysroot' to a nonexistent directory to prevent GDB from finding 12222 your host's libraries. `sysroot' is preferred; setting it to a 12223 nonexistent directory may interfere with automatic loading of 12224 shared library symbols. 12225 12226 `show solib-search-path' 12227 Display the current shared library search path. 12228 12229 ---------- Footnotes ---------- 12230 12231 (1) If you want to specify a local system root using a directory 12232 that happens to be named `remote:', you need to use some equivalent 12233 variant of the name like `./remote:'. 12234 12235 12236 File: gdb.info, Node: Separate Debug Files, Next: Symbol Errors, Prev: Files, Up: GDB Files 12237 12238 18.2 Debugging Information in Separate Files 12239 ============================================ 12240 12241 GDB allows you to put a program's debugging information in a file 12242 separate from the executable itself, in a way that allows GDB to find 12243 and load the debugging information automatically. Since debugging 12244 information can be very large--sometimes larger than the executable 12245 code itself--some systems distribute debugging information for their 12246 executables in separate files, which users can install only when they 12247 need to debug a problem. 12248 12249 GDB supports two ways of specifying the separate debug info file: 12250 12251 * The executable contains a "debug link" that specifies the name of 12252 the separate debug info file. The separate debug file's name is 12253 usually `EXECUTABLE.debug', where EXECUTABLE is the name of the 12254 corresponding executable file without leading directories (e.g., 12255 `ls.debug' for `/usr/bin/ls'). In addition, the debug link 12256 specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for 12257 the debug file, which GDB uses to validate that the executable and 12258 the debug file came from the same build. 12259 12260 * The executable contains a "build ID", a unique bit string that is 12261 also present in the corresponding debug info file. (This is 12262 supported only on some operating systems, notably those which use 12263 the ELF format for binary files and the GNU Binutils.) For more 12264 details about this feature, see the description of the `--build-id' 12265 command-line option in *Note Command Line Options: 12266 (ld.info)Options. The debug info file's name is not specified 12267 explicitly by the build ID, but can be computed from the build ID, 12268 see below. 12269 12270 Depending on the way the debug info file is specified, GDB uses two 12271 different methods of looking for the debug file: 12272 12273 * For the "debug link" method, GDB looks up the named file in the 12274 directory of the executable file, then in a subdirectory of that 12275 directory named `.debug', and finally under the global debug 12276 directory, in a subdirectory whose name is identical to the leading 12277 directories of the executable's absolute file name. 12278 12279 * For the "build ID" method, GDB looks in the `.build-id' 12280 subdirectory of the global debug directory for a file named 12281 `NN/NNNNNNNN.debug', where NN are the first 2 hex characters of 12282 the build ID bit string, and NNNNNNNN are the rest of the bit 12283 string. (Real build ID strings are 32 or more hex characters, not 12284 10.) 12285 12286 So, for example, suppose you ask GDB to debug `/usr/bin/ls', which 12287 has a debug link that specifies the file `ls.debug', and a build ID 12288 whose value in hex is `abcdef1234'. If the global debug directory is 12289 `/usr/lib/debug', then GDB will look for the following debug 12290 information files, in the indicated order: 12291 12292 - `/usr/lib/debug/.build-id/ab/cdef1234.debug' 12293 12294 - `/usr/bin/ls.debug' 12295 12296 - `/usr/bin/.debug/ls.debug' 12297 12298 - `/usr/lib/debug/usr/bin/ls.debug'. 12299 12300 You can set the global debugging info directory's name, and view the 12301 name GDB is currently using. 12302 12303 `set debug-file-directory DIRECTORIES' 12304 Set the directories which GDB searches for separate debugging 12305 information files to DIRECTORY. Multiple directory components can 12306 be set concatenating them by a directory separator. 12307 12308 `show debug-file-directory' 12309 Show the directories GDB searches for separate debugging 12310 information files. 12311 12312 12313 A debug link is a special section of the executable file named 12314 `.gnu_debuglink'. The section must contain: 12315 12316 * A filename, with any leading directory components removed, 12317 followed by a zero byte, 12318 12319 * zero to three bytes of padding, as needed to reach the next 12320 four-byte boundary within the section, and 12321 12322 * a four-byte CRC checksum, stored in the same endianness used for 12323 the executable file itself. The checksum is computed on the 12324 debugging information file's full contents by the function given 12325 below, passing zero as the CRC argument. 12326 12327 Any executable file format can carry a debug link, as long as it can 12328 contain a section named `.gnu_debuglink' with the contents described 12329 above. 12330 12331 The build ID is a special section in the executable file (and in 12332 other ELF binary files that GDB may consider). This section is often 12333 named `.note.gnu.build-id', but that name is not mandatory. It 12334 contains unique identification for the built files--the ID remains the 12335 same across multiple builds of the same build tree. The default 12336 algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the 12337 content for the build ID string. The same section with an identical 12338 value is present in the original built binary with symbols, in its 12339 stripped variant, and in the separate debugging information file. 12340 12341 The debugging information file itself should be an ordinary 12342 executable, containing a full set of linker symbols, sections, and 12343 debugging information. The sections of the debugging information file 12344 should have the same names, addresses, and sizes as the original file, 12345 but they need not contain any data--much like a `.bss' section in an 12346 ordinary executable. 12347 12348 The GNU binary utilities (Binutils) package includes the `objcopy' 12349 utility that can produce the separated executable / debugging 12350 information file pairs using the following commands: 12351 12352 objcopy --only-keep-debug foo foo.debug 12353 strip -g foo 12354 12355 These commands remove the debugging information from the executable 12356 file `foo' and place it in the file `foo.debug'. You can use the 12357 first, second or both methods to link the two files: 12358 12359 * The debug link method needs the following additional command to 12360 also leave behind a debug link in `foo': 12361 12362 objcopy --add-gnu-debuglink=foo.debug foo 12363 12364 Ulrich Drepper's `elfutils' package, starting with version 0.53, 12365 contains a version of the `strip' command such that the command 12366 `strip foo -f foo.debug' has the same functionality as the two 12367 `objcopy' commands and the `ln -s' command above, together. 12368 12369 * Build ID gets embedded into the main executable using `ld 12370 --build-id' or the GCC counterpart `gcc -Wl,--build-id'. Build ID 12371 support plus compatibility fixes for debug files separation are 12372 present in GNU binary utilities (Binutils) package since version 12373 2.18. 12374 12375 The CRC used in `.gnu_debuglink' is the CRC-32 defined in IEEE 802.3 12376 using the polynomial: 12377 12378 x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 12379 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1 12380 12381 The function is computed byte at a time, taking the least 12382 significant bit of each byte first. The initial pattern `0xffffffff' 12383 is used, to ensure leading zeros affect the CRC and the final result is 12384 inverted to ensure trailing zeros also affect the CRC. 12385 12386 _Note:_ This is the same CRC polynomial as used in handling the 12387 "Remote Serial Protocol" `qCRC' packet (*note GDB Remote Serial 12388 Protocol: Remote Protocol.). However in the case of the Remote Serial 12389 Protocol, the CRC is computed _most_ significant bit first, and the 12390 result is not inverted, so trailing zeros have no effect on the CRC 12391 value. 12392 12393 To complete the description, we show below the code of the function 12394 which produces the CRC used in `.gnu_debuglink'. Inverting the 12395 initially supplied `crc' argument means that an initial call to this 12396 function passing in zero will start computing the CRC using 12397 `0xffffffff'. 12398 12399 unsigned long 12400 gnu_debuglink_crc32 (unsigned long crc, 12401 unsigned char *buf, size_t len) 12402 { 12403 static const unsigned long crc32_table[256] = 12404 { 12405 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 12406 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 12407 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 12408 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 12409 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 12410 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 12411 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 12412 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 12413 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 12414 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 12415 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 12416 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 12417 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 12418 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 12419 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 12420 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 12421 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 12422 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 12423 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 12424 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 12425 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 12426 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 12427 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 12428 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 12429 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 12430 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 12431 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 12432 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 12433 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 12434 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 12435 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 12436 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 12437 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 12438 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 12439 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 12440 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 12441 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 12442 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 12443 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 12444 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 12445 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 12446 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 12447 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 12448 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 12449 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 12450 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 12451 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 12452 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 12453 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 12454 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 12455 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 12456 0x2d02ef8d 12457 }; 12458 unsigned char *end; 12459 12460 crc = ~crc & 0xffffffff; 12461 for (end = buf + len; buf < end; ++buf) 12462 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); 12463 return ~crc & 0xffffffff; 12464 } 12465 12466 This computation does not apply to the "build ID" method. 12467 12468 12469 File: gdb.info, Node: Symbol Errors, Next: Data Files, Prev: Separate Debug Files, Up: GDB Files 12470 12471 18.3 Errors Reading Symbol Files 12472 ================================ 12473 12474 While reading a symbol file, GDB occasionally encounters problems, such 12475 as symbol types it does not recognize, or known bugs in compiler 12476 output. By default, GDB does not notify you of such problems, since 12477 they are relatively common and primarily of interest to people 12478 debugging compilers. If you are interested in seeing information about 12479 ill-constructed symbol tables, you can either ask GDB to print only one 12480 message about each such type of problem, no matter how many times the 12481 problem occurs; or you can ask GDB to print more messages, to see how 12482 many times the problems occur, with the `set complaints' command (*note 12483 Optional Warnings and Messages: Messages/Warnings.). 12484 12485 The messages currently printed, and their meanings, include: 12486 12487 `inner block not inside outer block in SYMBOL' 12488 The symbol information shows where symbol scopes begin and end 12489 (such as at the start of a function or a block of statements). 12490 This error indicates that an inner scope block is not fully 12491 contained in its outer scope blocks. 12492 12493 GDB circumvents the problem by treating the inner block as if it 12494 had the same scope as the outer block. In the error message, 12495 SYMBOL may be shown as "`(don't know)'" if the outer block is not a 12496 function. 12497 12498 `block at ADDRESS out of order' 12499 The symbol information for symbol scope blocks should occur in 12500 order of increasing addresses. This error indicates that it does 12501 not do so. 12502 12503 GDB does not circumvent this problem, and has trouble locating 12504 symbols in the source file whose symbols it is reading. (You can 12505 often determine what source file is affected by specifying `set 12506 verbose on'. *Note Optional Warnings and Messages: 12507 Messages/Warnings.) 12508 12509 `bad block start address patched' 12510 The symbol information for a symbol scope block has a start address 12511 smaller than the address of the preceding source line. This is 12512 known to occur in the SunOS 4.1.1 (and earlier) C compiler. 12513 12514 GDB circumvents the problem by treating the symbol scope block as 12515 starting on the previous source line. 12516 12517 `bad string table offset in symbol N' 12518 Symbol number N contains a pointer into the string table which is 12519 larger than the size of the string table. 12520 12521 GDB circumvents the problem by considering the symbol to have the 12522 name `foo', which may cause other problems if many symbols end up 12523 with this name. 12524 12525 `unknown symbol type `0xNN'' 12526 The symbol information contains new data types that GDB does not 12527 yet know how to read. `0xNN' is the symbol type of the 12528 uncomprehended information, in hexadecimal. 12529 12530 GDB circumvents the error by ignoring this symbol information. 12531 This usually allows you to debug your program, though certain 12532 symbols are not accessible. If you encounter such a problem and 12533 feel like debugging it, you can debug `gdb' with itself, breakpoint 12534 on `complain', then go up to the function `read_dbx_symtab' and 12535 examine `*bufp' to see the symbol. 12536 12537 `stub type has NULL name' 12538 GDB could not find the full definition for a struct or class. 12539 12540 `const/volatile indicator missing (ok if using g++ v1.x), got...' 12541 The symbol information for a C++ member function is missing some 12542 information that recent versions of the compiler should have 12543 output for it. 12544 12545 `info mismatch between compiler and debugger' 12546 GDB could not parse a type specification output by the compiler. 12547 12548 12549 12550 File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files 12551 12552 18.4 GDB Data Files 12553 =================== 12554 12555 GDB will sometimes read an auxiliary data file. These files are kept 12556 in a directory known as the "data directory". 12557 12558 You can set the data directory's name, and view the name GDB is 12559 currently using. 12560 12561 `set data-directory DIRECTORY' 12562 Set the directory which GDB searches for auxiliary data files to 12563 DIRECTORY. 12564 12565 `show data-directory' 12566 Show the directory GDB searches for auxiliary data files. 12567 12568 You can set the default data directory by using the configure-time 12569 `--with-gdb-datadir' option. If the data directory is inside GDB's 12570 configured binary prefix (set with `--prefix' or `--exec-prefix'), then 12571 the default data directory will be updated automatically if the 12572 installed GDB is moved to a new location. 12573 12574 12575 File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top 12576 12577 19 Specifying a Debugging Target 12578 ******************************** 12579 12580 A "target" is the execution environment occupied by your program. 12581 12582 Often, GDB runs in the same host environment as your program; in 12583 that case, the debugging target is specified as a side effect when you 12584 use the `file' or `core' commands. When you need more flexibility--for 12585 example, running GDB on a physically separate host, or controlling a 12586 standalone system over a serial port or a realtime system over a TCP/IP 12587 connection--you can use the `target' command to specify one of the 12588 target types configured for GDB (*note Commands for Managing Targets: 12589 Target Commands.). 12590 12591 It is possible to build GDB for several different "target 12592 architectures". When GDB is built like that, you can choose one of the 12593 available architectures with the `set architecture' command. 12594 12595 `set architecture ARCH' 12596 This command sets the current target architecture to ARCH. The 12597 value of ARCH can be `"auto"', in addition to one of the supported 12598 architectures. 12599 12600 `show architecture' 12601 Show the current target architecture. 12602 12603 `set processor' 12604 `processor' 12605 These are alias commands for, respectively, `set architecture' and 12606 `show architecture'. 12607 12608 * Menu: 12609 12610 * Active Targets:: Active targets 12611 * Target Commands:: Commands for managing targets 12612 * Byte Order:: Choosing target byte order 12613 12614 12615 File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets 12616 12617 19.1 Active Targets 12618 =================== 12619 12620 There are three classes of targets: processes, core files, and 12621 executable files. GDB can work concurrently on up to three active 12622 targets, one in each class. This allows you to (for example) start a 12623 process and inspect its activity without abandoning your work on a core 12624 file. 12625 12626 For example, if you execute `gdb a.out', then the executable file 12627 `a.out' is the only active target. If you designate a core file as 12628 well--presumably from a prior run that crashed and coredumped--then GDB 12629 has two active targets and uses them in tandem, looking first in the 12630 corefile target, then in the executable file, to satisfy requests for 12631 memory addresses. (Typically, these two classes of target are 12632 complementary, since core files contain only a program's read-write 12633 memory--variables and so on--plus machine status, while executable 12634 files contain only the program text and initialized data.) 12635 12636 When you type `run', your executable file becomes an active process 12637 target as well. When a process target is active, all GDB commands 12638 requesting memory addresses refer to that target; addresses in an 12639 active core file or executable file target are obscured while the 12640 process target is active. 12641 12642 Use the `core-file' and `exec-file' commands to select a new core 12643 file or executable target (*note Commands to Specify Files: Files.). 12644 To specify as a target a process that is already running, use the 12645 `attach' command (*note Debugging an Already-running Process: Attach.). 12646 12647 12648 File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets 12649 12650 19.2 Commands for Managing Targets 12651 ================================== 12652 12653 `target TYPE PARAMETERS' 12654 Connects the GDB host environment to a target machine or process. 12655 A target is typically a protocol for talking to debugging 12656 facilities. You use the argument TYPE to specify the type or 12657 protocol of the target machine. 12658 12659 Further PARAMETERS are interpreted by the target protocol, but 12660 typically include things like device names or host names to connect 12661 with, process numbers, and baud rates. 12662 12663 The `target' command does not repeat if you press <RET> again 12664 after executing the command. 12665 12666 `help target' 12667 Displays the names of all targets available. To display targets 12668 currently selected, use either `info target' or `info files' 12669 (*note Commands to Specify Files: Files.). 12670 12671 `help target NAME' 12672 Describe a particular target, including any parameters necessary to 12673 select it. 12674 12675 `set gnutarget ARGS' 12676 GDB uses its own library BFD to read your files. GDB knows 12677 whether it is reading an "executable", a "core", or a ".o" file; 12678 however, you can specify the file format with the `set gnutarget' 12679 command. Unlike most `target' commands, with `gnutarget' the 12680 `target' refers to a program, not a machine. 12681 12682 _Warning:_ To specify a file format with `set gnutarget', you 12683 must know the actual BFD name. 12684 12685 *Note Commands to Specify Files: Files. 12686 12687 `show gnutarget' 12688 Use the `show gnutarget' command to display what file format 12689 `gnutarget' is set to read. If you have not set `gnutarget', GDB 12690 will determine the file format for each file automatically, and 12691 `show gnutarget' displays `The current BDF target is "auto"'. 12692 12693 Here are some common targets (available, or not, depending on the GDB 12694 configuration): 12695 12696 `target exec PROGRAM' 12697 An executable file. `target exec PROGRAM' is the same as 12698 `exec-file PROGRAM'. 12699 12700 `target core FILENAME' 12701 A core dump file. `target core FILENAME' is the same as 12702 `core-file FILENAME'. 12703 12704 `target remote MEDIUM' 12705 A remote system connected to GDB via a serial line or network 12706 connection. This command tells GDB to use its own remote protocol 12707 over MEDIUM for debugging. *Note Remote Debugging::. 12708 12709 For example, if you have a board connected to `/dev/ttya' on the 12710 machine running GDB, you could say: 12711 12712 target remote /dev/ttya 12713 12714 `target remote' supports the `load' command. This is only useful 12715 if you have some other way of getting the stub to the target 12716 system, and you can put it somewhere in memory where it won't get 12717 clobbered by the download. 12718 12719 `target sim' 12720 Builtin CPU simulator. GDB includes simulators for most 12721 architectures. In general, 12722 target sim 12723 load 12724 run 12725 works; however, you cannot assume that a specific memory map, 12726 device drivers, or even basic I/O is available, although some 12727 simulators do provide these. For info about any 12728 processor-specific simulator details, see the appropriate section 12729 in *Note Embedded Processors: Embedded Processors. 12730 12731 12732 Some configurations may include these targets as well: 12733 12734 `target nrom DEV' 12735 NetROM ROM emulator. This target only supports downloading. 12736 12737 12738 Different targets are available on different configurations of GDB; 12739 your configuration may have more or fewer targets. 12740 12741 Many remote targets require you to download the executable's code 12742 once you've successfully established a connection. You may wish to 12743 control various aspects of this process. 12744 12745 `set hash' 12746 This command controls whether a hash mark `#' is displayed while 12747 downloading a file to the remote monitor. If on, a hash mark is 12748 displayed after each S-record is successfully downloaded to the 12749 monitor. 12750 12751 `show hash' 12752 Show the current status of displaying the hash mark. 12753 12754 `set debug monitor' 12755 Enable or disable display of communications messages between GDB 12756 and the remote monitor. 12757 12758 `show debug monitor' 12759 Show the current status of displaying communications between GDB 12760 and the remote monitor. 12761 12762 `load FILENAME' 12763 Depending on what remote debugging facilities are configured into 12764 GDB, the `load' command may be available. Where it exists, it is 12765 meant to make FILENAME (an executable) available for debugging on 12766 the remote system--by downloading, or dynamic linking, for example. 12767 `load' also records the FILENAME symbol table in GDB, like the 12768 `add-symbol-file' command. 12769 12770 If your GDB does not have a `load' command, attempting to execute 12771 it gets the error message "`You can't do that when your target is 12772 ...'" 12773 12774 The file is loaded at whatever address is specified in the 12775 executable. For some object file formats, you can specify the 12776 load address when you link the program; for other formats, like 12777 a.out, the object file format specifies a fixed address. 12778 12779 Depending on the remote side capabilities, GDB may be able to load 12780 programs into flash memory. 12781 12782 `load' does not repeat if you press <RET> again after using it. 12783 12784 12785 File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets 12786 12787 19.3 Choosing Target Byte Order 12788 =============================== 12789 12790 Some types of processors, such as the MIPS, PowerPC, and Renesas SH, 12791 offer the ability to run either big-endian or little-endian byte 12792 orders. Usually the executable or symbol will include a bit to 12793 designate the endian-ness, and you will not need to worry about which 12794 to use. However, you may still find it useful to adjust GDB's idea of 12795 processor endian-ness manually. 12796 12797 `set endian big' 12798 Instruct GDB to assume the target is big-endian. 12799 12800 `set endian little' 12801 Instruct GDB to assume the target is little-endian. 12802 12803 `set endian auto' 12804 Instruct GDB to use the byte order associated with the executable. 12805 12806 `show endian' 12807 Display GDB's current idea of the target byte order. 12808 12809 12810 Note that these commands merely adjust interpretation of symbolic 12811 data on the host, and that they have absolutely no effect on the target 12812 system. 12813 12814 12815 File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top 12816 12817 20 Debugging Remote Programs 12818 **************************** 12819 12820 If you are trying to debug a program running on a machine that cannot 12821 run GDB in the usual way, it is often useful to use remote debugging. 12822 For example, you might use remote debugging on an operating system 12823 kernel, or on a small system which does not have a general purpose 12824 operating system powerful enough to run a full-featured debugger. 12825 12826 Some configurations of GDB have special serial or TCP/IP interfaces 12827 to make this work with particular debugging targets. In addition, GDB 12828 comes with a generic serial protocol (specific to GDB, but not specific 12829 to any particular target system) which you can use if you write the 12830 remote stubs--the code that runs on the remote system to communicate 12831 with GDB. 12832 12833 Other remote targets may be available in your configuration of GDB; 12834 use `help target' to list them. 12835 12836 * Menu: 12837 12838 * Connecting:: Connecting to a remote target 12839 * File Transfer:: Sending files to a remote system 12840 * Server:: Using the gdbserver program 12841 * Remote Configuration:: Remote configuration 12842 * Remote Stub:: Implementing a remote stub 12843 12844 12845 File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging 12846 12847 20.1 Connecting to a Remote Target 12848 ================================== 12849 12850 On the GDB host machine, you will need an unstripped copy of your 12851 program, since GDB needs symbol and debugging information. Start up 12852 GDB as usual, using the name of the local copy of your program as the 12853 first argument. 12854 12855 GDB can communicate with the target over a serial line, or over an 12856 IP network using TCP or UDP. In each case, GDB uses the same protocol 12857 for debugging your program; only the medium carrying the debugging 12858 packets varies. The `target remote' command establishes a connection 12859 to the target. Its arguments indicate which medium to use: 12860 12861 `target remote SERIAL-DEVICE' 12862 Use SERIAL-DEVICE to communicate with the target. For example, to 12863 use a serial line connected to the device named `/dev/ttyb': 12864 12865 target remote /dev/ttyb 12866 12867 If you're using a serial line, you may want to give GDB the 12868 `--baud' option, or use the `set remotebaud' command (*note set 12869 remotebaud: Remote Configuration.) before the `target' command. 12870 12871 `target remote `HOST:PORT'' 12872 `target remote `tcp:HOST:PORT'' 12873 Debug using a TCP connection to PORT on HOST. The HOST may be 12874 either a host name or a numeric IP address; PORT must be a decimal 12875 number. The HOST could be the target machine itself, if it is 12876 directly connected to the net, or it might be a terminal server 12877 which in turn has a serial line to the target. 12878 12879 For example, to connect to port 2828 on a terminal server named 12880 `manyfarms': 12881 12882 target remote manyfarms:2828 12883 12884 If your remote target is actually running on the same machine as 12885 your debugger session (e.g. a simulator for your target running on 12886 the same host), you can omit the hostname. For example, to 12887 connect to port 1234 on your local machine: 12888 12889 target remote :1234 12890 Note that the colon is still required here. 12891 12892 `target remote `udp:HOST:PORT'' 12893 Debug using UDP packets to PORT on HOST. For example, to connect 12894 to UDP port 2828 on a terminal server named `manyfarms': 12895 12896 target remote udp:manyfarms:2828 12897 12898 When using a UDP connection for remote debugging, you should keep 12899 in mind that the `U' stands for "Unreliable". UDP can silently 12900 drop packets on busy or unreliable networks, which will cause 12901 havoc with your debugging session. 12902 12903 `target remote | COMMAND' 12904 Run COMMAND in the background and communicate with it using a 12905 pipe. The COMMAND is a shell command, to be parsed and expanded 12906 by the system's command shell, `/bin/sh'; it should expect remote 12907 protocol packets on its standard input, and send replies on its 12908 standard output. You could use this to run a stand-alone simulator 12909 that speaks the remote debugging protocol, to make net connections 12910 using programs like `ssh', or for other similar tricks. 12911 12912 If COMMAND closes its standard output (perhaps by exiting), GDB 12913 will try to send it a `SIGTERM' signal. (If the program has 12914 already exited, this will have no effect.) 12915 12916 12917 Once the connection has been established, you can use all the usual 12918 commands to examine and change data. The remote program is already 12919 running; you can use `step' and `continue', and you do not need to use 12920 `run'. 12921 12922 Whenever GDB is waiting for the remote program, if you type the 12923 interrupt character (often `Ctrl-c'), GDB attempts to stop the program. 12924 This may or may not succeed, depending in part on the hardware and the 12925 serial drivers the remote system uses. If you type the interrupt 12926 character once again, GDB displays this prompt: 12927 12928 Interrupted while waiting for the program. 12929 Give up (and stop debugging it)? (y or n) 12930 12931 If you type `y', GDB abandons the remote debugging session. (If you 12932 decide you want to try again later, you can use `target remote' again 12933 to connect once more.) If you type `n', GDB goes back to waiting. 12934 12935 `detach' 12936 When you have finished debugging the remote program, you can use 12937 the `detach' command to release it from GDB control. Detaching 12938 from the target normally resumes its execution, but the results 12939 will depend on your particular remote stub. After the `detach' 12940 command, GDB is free to connect to another target. 12941 12942 `disconnect' 12943 The `disconnect' command behaves like `detach', except that the 12944 target is generally not resumed. It will wait for GDB (this 12945 instance or another one) to connect and continue debugging. After 12946 the `disconnect' command, GDB is again free to connect to another 12947 target. 12948 12949 `monitor CMD' 12950 This command allows you to send arbitrary commands directly to the 12951 remote monitor. Since GDB doesn't care about the commands it 12952 sends like this, this command is the way to extend GDB--you can 12953 add new commands that only the external monitor will understand 12954 and implement. 12955 12956 12957 File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Remote Debugging 12958 12959 20.2 Sending files to a remote system 12960 ===================================== 12961 12962 Some remote targets offer the ability to transfer files over the same 12963 connection used to communicate with GDB. This is convenient for 12964 targets accessible through other means, e.g. GNU/Linux systems running 12965 `gdbserver' over a network interface. For other targets, e.g. embedded 12966 devices with only a single serial port, this may be the only way to 12967 upload or download files. 12968 12969 Not all remote targets support these commands. 12970 12971 `remote put HOSTFILE TARGETFILE' 12972 Copy file HOSTFILE from the host system (the machine running GDB) 12973 to TARGETFILE on the target system. 12974 12975 `remote get TARGETFILE HOSTFILE' 12976 Copy file TARGETFILE from the target system to HOSTFILE on the 12977 host system. 12978 12979 `remote delete TARGETFILE' 12980 Delete TARGETFILE from the target system. 12981 12982 12983 12984 File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer, Up: Remote Debugging 12985 12986 20.3 Using the `gdbserver' Program 12987 ================================== 12988 12989 `gdbserver' is a control program for Unix-like systems, which allows 12990 you to connect your program with a remote GDB via `target remote'--but 12991 without linking in the usual debugging stub. 12992 12993 `gdbserver' is not a complete replacement for the debugging stubs, 12994 because it requires essentially the same operating-system facilities 12995 that GDB itself does. In fact, a system that can run `gdbserver' to 12996 connect to a remote GDB could also run GDB locally! `gdbserver' is 12997 sometimes useful nevertheless, because it is a much smaller program 12998 than GDB itself. It is also easier to port than all of GDB, so you may 12999 be able to get started more quickly on a new system by using 13000 `gdbserver'. Finally, if you develop code for real-time systems, you 13001 may find that the tradeoffs involved in real-time operation make it 13002 more convenient to do as much development work as possible on another 13003 system, for example by cross-compiling. You can use `gdbserver' to 13004 make a similar choice for debugging. 13005 13006 GDB and `gdbserver' communicate via either a serial line or a TCP 13007 connection, using the standard GDB remote serial protocol. 13008 13009 _Warning:_ `gdbserver' does not have any built-in security. Do 13010 not run `gdbserver' connected to any public network; a GDB 13011 connection to `gdbserver' provides access to the target system 13012 with the same privileges as the user running `gdbserver'. 13013 13014 20.3.1 Running `gdbserver' 13015 -------------------------- 13016 13017 Run `gdbserver' on the target system. You need a copy of the program 13018 you want to debug, including any libraries it requires. `gdbserver' 13019 does not need your program's symbol table, so you can strip the program 13020 if necessary to save space. GDB on the host system does all the symbol 13021 handling. 13022 13023 To use the server, you must tell it how to communicate with GDB; the 13024 name of your program; and the arguments for your program. The usual 13025 syntax is: 13026 13027 target> gdbserver COMM PROGRAM [ ARGS ... ] 13028 13029 COMM is either a device name (to use a serial line) or a TCP 13030 hostname and portnumber. For example, to debug Emacs with the argument 13031 `foo.txt' and communicate with GDB over the serial port `/dev/com1': 13032 13033 target> gdbserver /dev/com1 emacs foo.txt 13034 13035 `gdbserver' waits passively for the host GDB to communicate with it. 13036 13037 To use a TCP connection instead of a serial line: 13038 13039 target> gdbserver host:2345 emacs foo.txt 13040 13041 The only difference from the previous example is the first argument, 13042 specifying that you are communicating with the host GDB via TCP. The 13043 `host:2345' argument means that `gdbserver' is to expect a TCP 13044 connection from machine `host' to local TCP port 2345. (Currently, the 13045 `host' part is ignored.) You can choose any number you want for the 13046 port number as long as it does not conflict with any TCP ports already 13047 in use on the target system (for example, `23' is reserved for 13048 `telnet').(1) You must use the same port number with the host GDB 13049 `target remote' command. 13050 13051 20.3.1.1 Attaching to a Running Program 13052 ....................................... 13053 13054 On some targets, `gdbserver' can also attach to running programs. This 13055 is accomplished via the `--attach' argument. The syntax is: 13056 13057 target> gdbserver --attach COMM PID 13058 13059 PID is the process ID of a currently running process. It isn't 13060 necessary to point `gdbserver' at a binary for the running process. 13061 13062 You can debug processes by name instead of process ID if your target 13063 has the `pidof' utility: 13064 13065 target> gdbserver --attach COMM `pidof PROGRAM` 13066 13067 In case more than one copy of PROGRAM is running, or PROGRAM has 13068 multiple threads, most versions of `pidof' support the `-s' option to 13069 only return the first process ID. 13070 13071 20.3.1.2 Multi-Process Mode for `gdbserver' 13072 ........................................... 13073 13074 When you connect to `gdbserver' using `target remote', `gdbserver' 13075 debugs the specified program only once. When the program exits, or you 13076 detach from it, GDB closes the connection and `gdbserver' exits. 13077 13078 If you connect using `target extended-remote', `gdbserver' enters 13079 multi-process mode. When the debugged program exits, or you detach 13080 from it, GDB stays connected to `gdbserver' even though no program is 13081 running. The `run' and `attach' commands instruct `gdbserver' to run 13082 or attach to a new program. The `run' command uses `set remote 13083 exec-file' (*note set remote exec-file::) to select the program to run. 13084 Command line arguments are supported, except for wildcard expansion 13085 and I/O redirection (*note Arguments::). 13086 13087 To start `gdbserver' without supplying an initial command to run or 13088 process ID to attach, use the `--multi' command line option. Then you 13089 can connect using `target extended-remote' and start the program you 13090 want to debug. 13091 13092 `gdbserver' does not automatically exit in multi-process mode. You 13093 can terminate it by using `monitor exit' (*note Monitor Commands for 13094 gdbserver::). 13095 13096 20.3.1.3 Other Command-Line Arguments for `gdbserver' 13097 ..................................................... 13098 13099 The `--debug' option tells `gdbserver' to display extra status 13100 information about the debugging process. The `--remote-debug' option 13101 tells `gdbserver' to display remote protocol debug output. These 13102 options are intended for `gdbserver' development and for bug reports to 13103 the developers. 13104 13105 The `--wrapper' option specifies a wrapper to launch programs for 13106 debugging. The option should be followed by the name of the wrapper, 13107 then any command-line arguments to pass to the wrapper, then `--' 13108 indicating the end of the wrapper arguments. 13109 13110 `gdbserver' runs the specified wrapper program with a combined 13111 command line including the wrapper arguments, then the name of the 13112 program to debug, then any arguments to the program. The wrapper runs 13113 until it executes your program, and then GDB gains control. 13114 13115 You can use any program that eventually calls `execve' with its 13116 arguments as a wrapper. Several standard Unix utilities do this, e.g. 13117 `env' and `nohup'. Any Unix shell script ending with `exec "$@"' will 13118 also work. 13119 13120 For example, you can use `env' to pass an environment variable to 13121 the debugged program, without setting the variable in `gdbserver''s 13122 environment: 13123 13124 $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog 13125 13126 20.3.2 Connecting to `gdbserver' 13127 -------------------------------- 13128 13129 Run GDB on the host system. 13130 13131 First make sure you have the necessary symbol files. Load symbols 13132 for your application using the `file' command before you connect. Use 13133 `set sysroot' to locate target libraries (unless your GDB was compiled 13134 with the correct sysroot using `--with-sysroot'). 13135 13136 The symbol file and target libraries must exactly match the 13137 executable and libraries on the target, with one exception: the files 13138 on the host system should not be stripped, even if the files on the 13139 target system are. Mismatched or missing files will lead to confusing 13140 results during debugging. On GNU/Linux targets, mismatched or missing 13141 files may also prevent `gdbserver' from debugging multi-threaded 13142 programs. 13143 13144 Connect to your target (*note Connecting to a Remote Target: 13145 Connecting.). For TCP connections, you must start up `gdbserver' prior 13146 to using the `target remote' command. Otherwise you may get an error 13147 whose text depends on the host system, but which usually looks 13148 something like `Connection refused'. Don't use the `load' command in 13149 GDB when using `gdbserver', since the program is already on the target. 13150 13151 20.3.3 Monitor Commands for `gdbserver' 13152 --------------------------------------- 13153 13154 During a GDB session using `gdbserver', you can use the `monitor' 13155 command to send special requests to `gdbserver'. Here are the 13156 available commands. 13157 13158 `monitor help' 13159 List the available monitor commands. 13160 13161 `monitor set debug 0' 13162 `monitor set debug 1' 13163 Disable or enable general debugging messages. 13164 13165 `monitor set remote-debug 0' 13166 `monitor set remote-debug 1' 13167 Disable or enable specific debugging messages associated with the 13168 remote protocol (*note Remote Protocol::). 13169 13170 `monitor set libthread-db-search-path [PATH]' 13171 When this command is issued, PATH is a colon-separated list of 13172 directories to search for `libthread_db' (*note set 13173 libthread-db-search-path: Threads.). If you omit PATH, 13174 `libthread-db-search-path' will be reset to an empty list. 13175 13176 `monitor exit' 13177 Tell gdbserver to exit immediately. This command should be 13178 followed by `disconnect' to close the debugging session. 13179 `gdbserver' will detach from any attached processes and kill any 13180 processes it created. Use `monitor exit' to terminate `gdbserver' 13181 at the end of a multi-process mode debug session. 13182 13183 13184 ---------- Footnotes ---------- 13185 13186 (1) If you choose a port number that conflicts with another service, 13187 `gdbserver' prints an error message and exits. 13188 13189 13190 File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging 13191 13192 20.4 Remote Configuration 13193 ========================= 13194 13195 This section documents the configuration options available when 13196 debugging remote programs. For the options related to the File I/O 13197 extensions of the remote protocol, see *Note system-call-allowed: 13198 system. 13199 13200 `set remoteaddresssize BITS' 13201 Set the maximum size of address in a memory packet to the specified 13202 number of bits. GDB will mask off the address bits above that 13203 number, when it passes addresses to the remote target. The 13204 default value is the number of bits in the target's address. 13205 13206 `show remoteaddresssize' 13207 Show the current value of remote address size in bits. 13208 13209 `set remotebaud N' 13210 Set the baud rate for the remote serial I/O to N baud. The value 13211 is used to set the speed of the serial port used for debugging 13212 remote targets. 13213 13214 `show remotebaud' 13215 Show the current speed of the remote connection. 13216 13217 `set remotebreak' 13218 If set to on, GDB sends a `BREAK' signal to the remote when you 13219 type `Ctrl-c' to interrupt the program running on the remote. If 13220 set to off, GDB sends the `Ctrl-C' character instead. The default 13221 is off, since most remote systems expect to see `Ctrl-C' as the 13222 interrupt signal. 13223 13224 `show remotebreak' 13225 Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote 13226 program. 13227 13228 `set remoteflow on' 13229 `set remoteflow off' 13230 Enable or disable hardware flow control (`RTS'/`CTS') on the 13231 serial port used to communicate to the remote target. 13232 13233 `show remoteflow' 13234 Show the current setting of hardware flow control. 13235 13236 `set remotelogbase BASE' 13237 Set the base (a.k.a. radix) of logging serial protocol 13238 communications to BASE. Supported values of BASE are: `ascii', 13239 `octal', and `hex'. The default is `ascii'. 13240 13241 `show remotelogbase' 13242 Show the current setting of the radix for logging remote serial 13243 protocol. 13244 13245 `set remotelogfile FILE' 13246 Record remote serial communications on the named FILE. The 13247 default is not to record at all. 13248 13249 `show remotelogfile.' 13250 Show the current setting of the file name on which to record the 13251 serial communications. 13252 13253 `set remotetimeout NUM' 13254 Set the timeout limit to wait for the remote target to respond to 13255 NUM seconds. The default is 2 seconds. 13256 13257 `show remotetimeout' 13258 Show the current number of seconds to wait for the remote target 13259 responses. 13260 13261 `set remote hardware-watchpoint-limit LIMIT' 13262 `set remote hardware-breakpoint-limit LIMIT' 13263 Restrict GDB to using LIMIT remote hardware breakpoint or 13264 watchpoints. A limit of -1, the default, is treated as unlimited. 13265 13266 `set remote exec-file FILENAME' 13267 `show remote exec-file' 13268 Select the file used for `run' with `target extended-remote'. 13269 This should be set to a filename valid on the target system. If 13270 it is not set, the target will use a default filename (e.g. the 13271 last program run). 13272 13273 `set remote interrupt-sequence' 13274 Allow the user to select one of `Ctrl-C', a `BREAK' or `BREAK-g' 13275 as the sequence to the remote target in order to interrupt the 13276 execution. `Ctrl-C' is a default. Some system prefers `BREAK' 13277 which is high level of serial line for some certain time. Linux 13278 kernel prefers `BREAK-g', a.k.a Magic SysRq g. It is `BREAK' 13279 signal followed by character `g'. 13280 13281 `show interrupt-sequence' 13282 Show which of `Ctrl-C', `BREAK' or `BREAK-g' is sent by GDB to 13283 interrupt the remote program. `BREAK-g' is BREAK signal followed 13284 by `g' and also known as Magic SysRq g. 13285 13286 `set remote interrupt-on-connect' 13287 Specify whether interrupt-sequence is sent to remote target when 13288 GDB connects to it. This is mostly needed when you debug Linux 13289 kernel. Linux kernel expects `BREAK' followed by `g' which is 13290 known as Magic SysRq g in order to connect GDB. 13291 13292 `show interrupt-on-connect' 13293 Show whether interrupt-sequence is sent to remote target when GDB 13294 connects to it. 13295 13296 `set tcp auto-retry on' 13297 Enable auto-retry for remote TCP connections. This is useful if 13298 the remote debugging agent is launched in parallel with GDB; there 13299 is a race condition because the agent may not become ready to 13300 accept the connection before GDB attempts to connect. When 13301 auto-retry is enabled, if the initial attempt to connect fails, 13302 GDB reattempts to establish the connection using the timeout 13303 specified by `set tcp connect-timeout'. 13304 13305 `set tcp auto-retry off' 13306 Do not auto-retry failed TCP connections. 13307 13308 `show tcp auto-retry' 13309 Show the current auto-retry setting. 13310 13311 `set tcp connect-timeout SECONDS' 13312 Set the timeout for establishing a TCP connection to the remote 13313 target to SECONDS. The timeout affects both polling to retry 13314 failed connections (enabled by `set tcp auto-retry on') and 13315 waiting for connections that are merely slow to complete, and 13316 represents an approximate cumulative value. 13317 13318 `show tcp connect-timeout' 13319 Show the current connection timeout setting. 13320 13321 The GDB remote protocol autodetects the packets supported by your 13322 debugging stub. If you need to override the autodetection, you can use 13323 these commands to enable or disable individual packets. Each packet 13324 can be set to `on' (the remote target supports this packet), `off' (the 13325 remote target does not support this packet), or `auto' (detect remote 13326 target support for this packet). They all default to `auto'. For more 13327 information about each packet, see *Note Remote Protocol::. 13328 13329 During normal use, you should not have to use any of these commands. 13330 If you do, that may be a bug in your remote debugging stub, or a bug in 13331 GDB. You may want to report the problem to the GDB developers. 13332 13333 For each packet NAME, the command to enable or disable the packet is 13334 `set remote NAME-packet'. The available settings are: 13335 13336 Command Name Remote Packet Related Features 13337 `fetch-register' `p' `info registers' 13338 `set-register' `P' `set' 13339 `binary-download' `X' `load', `set' 13340 `read-aux-vector' `qXfer:auxv:read' `info auxv' 13341 `symbol-lookup' `qSymbol' Detecting 13342 multiple threads 13343 `attach' `vAttach' `attach' 13344 `verbose-resume' `vCont' Stepping or 13345 resuming multiple 13346 threads 13347 `run' `vRun' `run' 13348 `software-breakpoint'`Z0' `break' 13349 `hardware-breakpoint'`Z1' `hbreak' 13350 `write-watchpoint' `Z2' `watch' 13351 `read-watchpoint' `Z3' `rwatch' 13352 `access-watchpoint' `Z4' `awatch' 13353 `target-features' `qXfer:features:read' `set architecture' 13354 `library-info' `qXfer:libraries:read' `info 13355 sharedlibrary' 13356 `memory-map' `qXfer:memory-map:read' `info mem' 13357 `read-spu-object' `qXfer:spu:read' `info spu' 13358 `write-spu-object' `qXfer:spu:write' `info spu' 13359 `read-siginfo-object'`qXfer:siginfo:read' `print $_siginfo' 13360 `write-siginfo-object'`qXfer:siginfo:write' `set $_siginfo' 13361 `threads' `qXfer:threads:read' `info threads' 13362 `get-thread-local- `qGetTLSAddr' Displaying 13363 storage-address' `__thread' 13364 variables 13365 `search-memory' `qSearch:memory' `find' 13366 `supported-packets' `qSupported' Remote 13367 communications 13368 parameters 13369 `pass-signals' `QPassSignals' `handle SIGNAL' 13370 `hostio-close-packet'`vFile:close' `remote get', 13371 `remote put' 13372 `hostio-open-packet' `vFile:open' `remote get', 13373 `remote put' 13374 `hostio-pread-packet'`vFile:pread' `remote get', 13375 `remote put' 13376 `hostio-pwrite-packet'`vFile:pwrite' `remote get', 13377 `remote put' 13378 `hostio-unlink-packet'`vFile:unlink' `remote delete' 13379 `noack-packet' `QStartNoAckMode' Packet 13380 acknowledgment 13381 `osdata' `qXfer:osdata:read' `info os' 13382 `query-attached' `qAttached' Querying remote 13383 process attach 13384 state. 13385 13386 13387 File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging 13388 13389 20.5 Implementing a Remote Stub 13390 =============================== 13391 13392 The stub files provided with GDB implement the target side of the 13393 communication protocol, and the GDB side is implemented in the GDB 13394 source file `remote.c'. Normally, you can simply allow these 13395 subroutines to communicate, and ignore the details. (If you're 13396 implementing your own stub file, you can still ignore the details: start 13397 with one of the existing stub files. `sparc-stub.c' is the best 13398 organized, and therefore the easiest to read.) 13399 13400 To debug a program running on another machine (the debugging 13401 "target" machine), you must first arrange for all the usual 13402 prerequisites for the program to run by itself. For example, for a C 13403 program, you need: 13404 13405 1. A startup routine to set up the C runtime environment; these 13406 usually have a name like `crt0'. The startup routine may be 13407 supplied by your hardware supplier, or you may have to write your 13408 own. 13409 13410 2. A C subroutine library to support your program's subroutine calls, 13411 notably managing input and output. 13412 13413 3. A way of getting your program to the other machine--for example, a 13414 download program. These are often supplied by the hardware 13415 manufacturer, but you may have to write your own from hardware 13416 documentation. 13417 13418 The next step is to arrange for your program to use a serial port to 13419 communicate with the machine where GDB is running (the "host" machine). 13420 In general terms, the scheme looks like this: 13421 13422 _On the host,_ 13423 GDB already understands how to use this protocol; when everything 13424 else is set up, you can simply use the `target remote' command 13425 (*note Specifying a Debugging Target: Targets.). 13426 13427 _On the target,_ 13428 you must link with your program a few special-purpose subroutines 13429 that implement the GDB remote serial protocol. The file 13430 containing these subroutines is called a "debugging stub". 13431 13432 On certain remote targets, you can use an auxiliary program 13433 `gdbserver' instead of linking a stub into your program. *Note 13434 Using the `gdbserver' Program: Server, for details. 13435 13436 The debugging stub is specific to the architecture of the remote 13437 machine; for example, use `sparc-stub.c' to debug programs on SPARC 13438 boards. 13439 13440 These working remote stubs are distributed with GDB: 13441 13442 `i386-stub.c' 13443 For Intel 386 and compatible architectures. 13444 13445 `m68k-stub.c' 13446 For Motorola 680x0 architectures. 13447 13448 `sh-stub.c' 13449 For Renesas SH architectures. 13450 13451 `sparc-stub.c' 13452 For SPARC architectures. 13453 13454 `sparcl-stub.c' 13455 For Fujitsu SPARCLITE architectures. 13456 13457 13458 The `README' file in the GDB distribution may list other recently 13459 added stubs. 13460 13461 * Menu: 13462 13463 * Stub Contents:: What the stub can do for you 13464 * Bootstrapping:: What you must do for the stub 13465 * Debug Session:: Putting it all together 13466 13467 13468 File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub 13469 13470 20.5.1 What the Stub Can Do for You 13471 ----------------------------------- 13472 13473 The debugging stub for your architecture supplies these three 13474 subroutines: 13475 13476 `set_debug_traps' 13477 This routine arranges for `handle_exception' to run when your 13478 program stops. You must call this subroutine explicitly near the 13479 beginning of your program. 13480 13481 `handle_exception' 13482 This is the central workhorse, but your program never calls it 13483 explicitly--the setup code arranges for `handle_exception' to run 13484 when a trap is triggered. 13485 13486 `handle_exception' takes control when your program stops during 13487 execution (for example, on a breakpoint), and mediates 13488 communications with GDB on the host machine. This is where the 13489 communications protocol is implemented; `handle_exception' acts as 13490 the GDB representative on the target machine. It begins by 13491 sending summary information on the state of your program, then 13492 continues to execute, retrieving and transmitting any information 13493 GDB needs, until you execute a GDB command that makes your program 13494 resume; at that point, `handle_exception' returns control to your 13495 own code on the target machine. 13496 13497 `breakpoint' 13498 Use this auxiliary subroutine to make your program contain a 13499 breakpoint. Depending on the particular situation, this may be 13500 the only way for GDB to get control. For instance, if your target 13501 machine has some sort of interrupt button, you won't need to call 13502 this; pressing the interrupt button transfers control to 13503 `handle_exception'--in effect, to GDB. On some machines, simply 13504 receiving characters on the serial port may also trigger a trap; 13505 again, in that situation, you don't need to call `breakpoint' from 13506 your own program--simply running `target remote' from the host GDB 13507 session gets control. 13508 13509 Call `breakpoint' if none of these is true, or if you simply want 13510 to make certain your program stops at a predetermined point for the 13511 start of your debugging session. 13512 13513 13514 File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub 13515 13516 20.5.2 What You Must Do for the Stub 13517 ------------------------------------ 13518 13519 The debugging stubs that come with GDB are set up for a particular chip 13520 architecture, but they have no information about the rest of your 13521 debugging target machine. 13522 13523 First of all you need to tell the stub how to communicate with the 13524 serial port. 13525 13526 `int getDebugChar()' 13527 Write this subroutine to read a single character from the serial 13528 port. It may be identical to `getchar' for your target system; a 13529 different name is used to allow you to distinguish the two if you 13530 wish. 13531 13532 `void putDebugChar(int)' 13533 Write this subroutine to write a single character to the serial 13534 port. It may be identical to `putchar' for your target system; a 13535 different name is used to allow you to distinguish the two if you 13536 wish. 13537 13538 If you want GDB to be able to stop your program while it is running, 13539 you need to use an interrupt-driven serial driver, and arrange for it 13540 to stop when it receives a `^C' (`\003', the control-C character). 13541 That is the character which GDB uses to tell the remote system to stop. 13542 13543 Getting the debugging target to return the proper status to GDB 13544 probably requires changes to the standard stub; one quick and dirty way 13545 is to just execute a breakpoint instruction (the "dirty" part is that 13546 GDB reports a `SIGTRAP' instead of a `SIGINT'). 13547 13548 Other routines you need to supply are: 13549 13550 `void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' 13551 Write this function to install EXCEPTION_ADDRESS in the exception 13552 handling tables. You need to do this because the stub does not 13553 have any way of knowing what the exception handling tables on your 13554 target system are like (for example, the processor's table might 13555 be in ROM, containing entries which point to a table in RAM). 13556 EXCEPTION_NUMBER is the exception number which should be changed; 13557 its meaning is architecture-dependent (for example, different 13558 numbers might represent divide by zero, misaligned access, etc). 13559 When this exception occurs, control should be transferred directly 13560 to EXCEPTION_ADDRESS, and the processor state (stack, registers, 13561 and so on) should be just as it is when a processor exception 13562 occurs. So if you want to use a jump instruction to reach 13563 EXCEPTION_ADDRESS, it should be a simple jump, not a jump to 13564 subroutine. 13565 13566 For the 386, EXCEPTION_ADDRESS should be installed as an interrupt 13567 gate so that interrupts are masked while the handler runs. The 13568 gate should be at privilege level 0 (the most privileged level). 13569 The SPARC and 68k stubs are able to mask interrupts themselves 13570 without help from `exceptionHandler'. 13571 13572 `void flush_i_cache()' 13573 On SPARC and SPARCLITE only, write this subroutine to flush the 13574 instruction cache, if any, on your target machine. If there is no 13575 instruction cache, this subroutine may be a no-op. 13576 13577 On target machines that have instruction caches, GDB requires this 13578 function to make certain that the state of your program is stable. 13579 13580 You must also make sure this library routine is available: 13581 13582 `void *memset(void *, int, int)' 13583 This is the standard library function `memset' that sets an area of 13584 memory to a known value. If you have one of the free versions of 13585 `libc.a', `memset' can be found there; otherwise, you must either 13586 obtain it from your hardware manufacturer, or write your own. 13587 13588 If you do not use the GNU C compiler, you may need other standard 13589 library subroutines as well; this varies from one stub to another, but 13590 in general the stubs are likely to use any of the common library 13591 subroutines which `GCC' generates as inline code. 13592 13593 13594 File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub 13595 13596 20.5.3 Putting it All Together 13597 ------------------------------ 13598 13599 In summary, when your program is ready to debug, you must follow these 13600 steps. 13601 13602 1. Make sure you have defined the supporting low-level routines 13603 (*note What You Must Do for the Stub: Bootstrapping.): 13604 `getDebugChar', `putDebugChar', 13605 `flush_i_cache', `memset', `exceptionHandler'. 13606 13607 2. Insert these lines near the top of your program: 13608 13609 set_debug_traps(); 13610 breakpoint(); 13611 13612 3. For the 680x0 stub only, you need to provide a variable called 13613 `exceptionHook'. Normally you just use: 13614 13615 void (*exceptionHook)() = 0; 13616 13617 but if before calling `set_debug_traps', you set it to point to a 13618 function in your program, that function is called when `GDB' 13619 continues after stopping on a trap (for example, bus error). The 13620 function indicated by `exceptionHook' is called with one 13621 parameter: an `int' which is the exception number. 13622 13623 4. Compile and link together: your program, the GDB debugging stub for 13624 your target architecture, and the supporting subroutines. 13625 13626 5. Make sure you have a serial connection between your target machine 13627 and the GDB host, and identify the serial port on the host. 13628 13629 6. Download your program to your target machine (or get it there by 13630 whatever means the manufacturer provides), and start it. 13631 13632 7. Start GDB on the host, and connect to the target (*note Connecting 13633 to a Remote Target: Connecting.). 13634 13635 13636 13637 File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top 13638 13639 21 Configuration-Specific Information 13640 ************************************* 13641 13642 While nearly all GDB commands are available for all native and cross 13643 versions of the debugger, there are some exceptions. This chapter 13644 describes things that are only available in certain configurations. 13645 13646 There are three major categories of configurations: native 13647 configurations, where the host and target are the same, embedded 13648 operating system configurations, which are usually the same for several 13649 different processor architectures, and bare embedded processors, which 13650 are quite different from each other. 13651 13652 * Menu: 13653 13654 * Native:: 13655 * Embedded OS:: 13656 * Embedded Processors:: 13657 * Architectures:: 13658 13659 13660 File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations 13661 13662 21.1 Native 13663 =========== 13664 13665 This section describes details specific to particular native 13666 configurations. 13667 13668 * Menu: 13669 13670 * HP-UX:: HP-UX 13671 * BSD libkvm Interface:: Debugging BSD kernel memory images 13672 * SVR4 Process Information:: SVR4 process information 13673 * DJGPP Native:: Features specific to the DJGPP port 13674 * Cygwin Native:: Features specific to the Cygwin port 13675 * Hurd Native:: Features specific to GNU Hurd 13676 * Neutrino:: Features specific to QNX Neutrino 13677 * Darwin:: Features specific to Darwin 13678 13679 13680 File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native 13681 13682 21.1.1 HP-UX 13683 ------------ 13684 13685 On HP-UX systems, if you refer to a function or variable name that 13686 begins with a dollar sign, GDB searches for a user or system name 13687 first, before it searches for a convenience variable. 13688 13689 13690 File: gdb.info, Node: BSD libkvm Interface, Next: SVR4 Process Information, Prev: HP-UX, Up: Native 13691 13692 21.1.2 BSD libkvm Interface 13693 --------------------------- 13694 13695 BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory 13696 interface that provides a uniform interface for accessing kernel virtual 13697 memory images, including live systems and crash dumps. GDB uses this 13698 interface to allow you to debug live kernels and kernel crash dumps on 13699 many native BSD configurations. This is implemented as a special `kvm' 13700 debugging target. For debugging a live system, load the currently 13701 running kernel into GDB and connect to the `kvm' target: 13702 13703 (gdb) target kvm 13704 13705 For debugging crash dumps, provide the file name of the crash dump 13706 as an argument: 13707 13708 (gdb) target kvm /var/crash/bsd.0 13709 13710 Once connected to the `kvm' target, the following commands are 13711 available: 13712 13713 `kvm pcb' 13714 Set current context from the "Process Control Block" (PCB) address. 13715 13716 `kvm proc' 13717 Set current context from proc address. This command isn't 13718 available on modern FreeBSD systems. 13719 13720 13721 File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native 13722 13723 21.1.3 SVR4 Process Information 13724 ------------------------------- 13725 13726 Many versions of SVR4 and compatible systems provide a facility called 13727 `/proc' that can be used to examine the image of a running process 13728 using file-system subroutines. If GDB is configured for an operating 13729 system with this facility, the command `info proc' is available to 13730 report information about the process running your program, or about any 13731 process running on your system. `info proc' works only on SVR4 systems 13732 that include the `procfs' code. This includes, as of this writing, 13733 GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not 13734 HP-UX, for example. 13735 13736 `info proc' 13737 `info proc PROCESS-ID' 13738 Summarize available information about any running process. If a 13739 process ID is specified by PROCESS-ID, display information about 13740 that process; otherwise display information about the program being 13741 debugged. The summary includes the debugged process ID, the 13742 command line used to invoke it, its current working directory, and 13743 its executable file's absolute file name. 13744 13745 On some systems, PROCESS-ID can be of the form `[PID]/TID' which 13746 specifies a certain thread ID within a process. If the optional 13747 PID part is missing, it means a thread from the process being 13748 debugged (the leading `/' still needs to be present, or else GDB 13749 will interpret the number as a process ID rather than a thread ID). 13750 13751 `info proc mappings' 13752 Report the memory address space ranges accessible in the program, 13753 with information on whether the process has read, write, or 13754 execute access rights to each range. On GNU/Linux systems, each 13755 memory range includes the object file which is mapped to that 13756 range, instead of the memory access rights to that range. 13757 13758 `info proc stat' 13759 `info proc status' 13760 These subcommands are specific to GNU/Linux systems. They show 13761 the process-related information, including the user ID and group 13762 ID; how many threads are there in the process; its virtual memory 13763 usage; the signals that are pending, blocked, and ignored; its 13764 TTY; its consumption of system and user time; its stack size; its 13765 `nice' value; etc. For more information, see the `proc' man page 13766 (type `man 5 proc' from your shell prompt). 13767 13768 `info proc all' 13769 Show all the information about the process described under all of 13770 the above `info proc' subcommands. 13771 13772 `set procfs-trace' 13773 This command enables and disables tracing of `procfs' API calls. 13774 13775 `show procfs-trace' 13776 Show the current state of `procfs' API call tracing. 13777 13778 `set procfs-file FILE' 13779 Tell GDB to write `procfs' API trace to the named FILE. GDB 13780 appends the trace info to the previous contents of the file. The 13781 default is to display the trace on the standard output. 13782 13783 `show procfs-file' 13784 Show the file to which `procfs' API trace is written. 13785 13786 `proc-trace-entry' 13787 `proc-trace-exit' 13788 `proc-untrace-entry' 13789 `proc-untrace-exit' 13790 These commands enable and disable tracing of entries into and exits 13791 from the `syscall' interface. 13792 13793 `info pidlist' 13794 For QNX Neutrino only, this command displays the list of all the 13795 processes and all the threads within each process. 13796 13797 `info meminfo' 13798 For QNX Neutrino only, this command displays the list of all 13799 mapinfos. 13800 13801 13802 File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native 13803 13804 21.1.4 Features for Debugging DJGPP Programs 13805 -------------------------------------------- 13806 13807 DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows. 13808 DJGPP programs are 32-bit protected-mode programs that use the "DPMI" 13809 (DOS Protected-Mode Interface) API to run on top of real-mode DOS 13810 systems and their emulations. 13811 13812 GDB supports native debugging of DJGPP programs, and defines a few 13813 commands specific to the DJGPP port. This subsection describes those 13814 commands. 13815 13816 `info dos' 13817 This is a prefix of DJGPP-specific commands which print 13818 information about the target system and important OS structures. 13819 13820 `info dos sysinfo' 13821 This command displays assorted information about the underlying 13822 platform: the CPU type and features, the OS version and flavor, the 13823 DPMI version, and the available conventional and DPMI memory. 13824 13825 `info dos gdt' 13826 `info dos ldt' 13827 `info dos idt' 13828 These 3 commands display entries from, respectively, Global, Local, 13829 and Interrupt Descriptor Tables (GDT, LDT, and IDT). The 13830 descriptor tables are data structures which store a descriptor for 13831 each segment that is currently in use. The segment's selector is 13832 an index into a descriptor table; the table entry for that index 13833 holds the descriptor's base address and limit, and its attributes 13834 and access rights. 13835 13836 A typical DJGPP program uses 3 segments: a code segment, a data 13837 segment (used for both data and the stack), and a DOS segment 13838 (which allows access to DOS/BIOS data structures and absolute 13839 addresses in conventional memory). However, the DPMI host will 13840 usually define additional segments in order to support the DPMI 13841 environment. 13842 13843 These commands allow to display entries from the descriptor tables. 13844 Without an argument, all entries from the specified table are 13845 displayed. An argument, which should be an integer expression, 13846 means display a single entry whose index is given by the argument. 13847 For example, here's a convenient way to display information about 13848 the debugged program's data segment: 13849 13850 `(gdb) info dos ldt $ds' 13851 `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)' 13852 13853 13854 This comes in handy when you want to see whether a pointer is 13855 outside the data segment's limit (i.e. "garbled"). 13856 13857 `info dos pde' 13858 `info dos pte' 13859 These two commands display entries from, respectively, the Page 13860 Directory and the Page Tables. Page Directories and Page Tables 13861 are data structures which control how virtual memory addresses are 13862 mapped into physical addresses. A Page Table includes an entry 13863 for every page of memory that is mapped into the program's address 13864 space; there may be several Page Tables, each one holding up to 13865 4096 entries. A Page Directory has up to 4096 entries, one each 13866 for every Page Table that is currently in use. 13867 13868 Without an argument, `info dos pde' displays the entire Page 13869 Directory, and `info dos pte' displays all the entries in all of 13870 the Page Tables. An argument, an integer expression, given to the 13871 `info dos pde' command means display only that entry from the Page 13872 Directory table. An argument given to the `info dos pte' command 13873 means display entries from a single Page Table, the one pointed to 13874 by the specified entry in the Page Directory. 13875 13876 These commands are useful when your program uses "DMA" (Direct 13877 Memory Access), which needs physical addresses to program the DMA 13878 controller. 13879 13880 These commands are supported only with some DPMI servers. 13881 13882 `info dos address-pte ADDR' 13883 This command displays the Page Table entry for a specified linear 13884 address. The argument ADDR is a linear address which should 13885 already have the appropriate segment's base address added to it, 13886 because this command accepts addresses which may belong to _any_ 13887 segment. For example, here's how to display the Page Table entry 13888 for the page where a variable `i' is stored: 13889 13890 `(gdb) info dos address-pte __djgpp_base_address + (char *)&i' 13891 `Page Table entry for address 0x11a00d30:' 13892 `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30' 13893 13894 13895 This says that `i' is stored at offset `0xd30' from the page whose 13896 physical base address is `0x02698000', and shows all the 13897 attributes of that page. 13898 13899 Note that you must cast the addresses of variables to a `char *', 13900 since otherwise the value of `__djgpp_base_address', the base 13901 address of all variables and functions in a DJGPP program, will be 13902 added using the rules of C pointer arithmetics: if `i' is declared 13903 an `int', GDB will add 4 times the value of `__djgpp_base_address' 13904 to the address of `i'. 13905 13906 Here's another example, it displays the Page Table entry for the 13907 transfer buffer: 13908 13909 `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)' 13910 `Page Table entry for address 0x29110:' 13911 `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110' 13912 13913 13914 (The `+ 3' offset is because the transfer buffer's address is the 13915 3rd member of the `_go32_info_block' structure.) The output 13916 clearly shows that this DPMI server maps the addresses in 13917 conventional memory 1:1, i.e. the physical (`0x00029000' + 13918 `0x110') and linear (`0x29110') addresses are identical. 13919 13920 This command is supported only with some DPMI servers. 13921 13922 In addition to native debugging, the DJGPP port supports remote 13923 debugging via a serial data link. The following commands are specific 13924 to remote serial debugging in the DJGPP port of GDB. 13925 13926 `set com1base ADDR' 13927 This command sets the base I/O port address of the `COM1' serial 13928 port. 13929 13930 `set com1irq IRQ' 13931 This command sets the "Interrupt Request" (`IRQ') line to use for 13932 the `COM1' serial port. 13933 13934 There are similar commands `set com2base', `set com3irq', etc. for 13935 setting the port address and the `IRQ' lines for the other 3 COM 13936 ports. 13937 13938 The related commands `show com1base', `show com1irq' etc. display 13939 the current settings of the base address and the `IRQ' lines used 13940 by the COM ports. 13941 13942 `info serial' 13943 This command prints the status of the 4 DOS serial ports. For each 13944 port, it prints whether it's active or not, its I/O base address 13945 and IRQ number, whether it uses a 16550-style FIFO, its baudrate, 13946 and the counts of various errors encountered so far. 13947 13948 13949 File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native 13950 13951 21.1.5 Features for Debugging MS Windows PE Executables 13952 ------------------------------------------------------- 13953 13954 GDB supports native debugging of MS Windows programs, including DLLs 13955 with and without symbolic debugging information. 13956 13957 MS-Windows programs that call `SetConsoleMode' to switch off the 13958 special meaning of the `Ctrl-C' keystroke cannot be interrupted by 13959 typing `C-c'. For this reason, GDB on MS-Windows supports `C-<BREAK>' 13960 as an alternative interrupt key sequence, which can be used to 13961 interrupt the debuggee even if it ignores `C-c'. 13962 13963 There are various additional Cygwin-specific commands, described in 13964 this section. Working with DLLs that have no debugging symbols is 13965 described in *Note Non-debug DLL Symbols::. 13966 13967 `info w32' 13968 This is a prefix of MS Windows-specific commands which print 13969 information about the target system and important OS structures. 13970 13971 `info w32 selector' 13972 This command displays information returned by the Win32 API 13973 `GetThreadSelectorEntry' function. It takes an optional argument 13974 that is evaluated to a long value to give the information about 13975 this given selector. Without argument, this command displays 13976 information about the six segment registers. 13977 13978 `info dll' 13979 This is a Cygwin-specific alias of `info shared'. 13980 13981 `dll-symbols' 13982 This command loads symbols from a dll similarly to add-sym command 13983 but without the need to specify a base address. 13984 13985 `set cygwin-exceptions MODE' 13986 If MODE is `on', GDB will break on exceptions that happen inside 13987 the Cygwin DLL. If MODE is `off', GDB will delay recognition of 13988 exceptions, and may ignore some exceptions which seem to be caused 13989 by internal Cygwin DLL "bookkeeping". This option is meant 13990 primarily for debugging the Cygwin DLL itself; the default value 13991 is `off' to avoid annoying GDB users with false `SIGSEGV' signals. 13992 13993 `show cygwin-exceptions' 13994 Displays whether GDB will break on exceptions that happen inside 13995 the Cygwin DLL itself. 13996 13997 `set new-console MODE' 13998 If MODE is `on' the debuggee will be started in a new console on 13999 next start. If MODE is `off'i, the debuggee will be started in 14000 the same console as the debugger. 14001 14002 `show new-console' 14003 Displays whether a new console is used when the debuggee is 14004 started. 14005 14006 `set new-group MODE' 14007 This boolean value controls whether the debuggee should start a 14008 new group or stay in the same group as the debugger. This affects 14009 the way the Windows OS handles `Ctrl-C'. 14010 14011 `show new-group' 14012 Displays current value of new-group boolean. 14013 14014 `set debugevents' 14015 This boolean value adds debug output concerning kernel events 14016 related to the debuggee seen by the debugger. This includes 14017 events that signal thread and process creation and exit, DLL 14018 loading and unloading, console interrupts, and debugging messages 14019 produced by the Windows `OutputDebugString' API call. 14020 14021 `set debugexec' 14022 This boolean value adds debug output concerning execute events 14023 (such as resume thread) seen by the debugger. 14024 14025 `set debugexceptions' 14026 This boolean value adds debug output concerning exceptions in the 14027 debuggee seen by the debugger. 14028 14029 `set debugmemory' 14030 This boolean value adds debug output concerning debuggee memory 14031 reads and writes by the debugger. 14032 14033 `set shell' 14034 This boolean values specifies whether the debuggee is called via a 14035 shell or directly (default value is on). 14036 14037 `show shell' 14038 Displays if the debuggee will be started with a shell. 14039 14040 14041 * Menu: 14042 14043 * Non-debug DLL Symbols:: Support for DLLs without debugging symbols 14044 14045 14046 File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native 14047 14048 21.1.5.1 Support for DLLs without Debugging Symbols 14049 ................................................... 14050 14051 Very often on windows, some of the DLLs that your program relies on do 14052 not include symbolic debugging information (for example, 14053 `kernel32.dll'). When GDB doesn't recognize any debugging symbols in a 14054 DLL, it relies on the minimal amount of symbolic information contained 14055 in the DLL's export table. This section describes working with such 14056 symbols, known internally to GDB as "minimal symbols". 14057 14058 Note that before the debugged program has started execution, no DLLs 14059 will have been loaded. The easiest way around this problem is simply to 14060 start the program -- either by setting a breakpoint or letting the 14061 program run once to completion. It is also possible to force GDB to 14062 load a particular DLL before starting the executable -- see the shared 14063 library information in *Note Files::, or the `dll-symbols' command in 14064 *Note Cygwin Native::. Currently, explicitly loading symbols from a 14065 DLL with no debugging information will cause the symbol names to be 14066 duplicated in GDB's lookup table, which may adversely affect symbol 14067 lookup performance. 14068 14069 21.1.5.2 DLL Name Prefixes 14070 .......................... 14071 14072 In keeping with the naming conventions used by the Microsoft debugging 14073 tools, DLL export symbols are made available with a prefix based on the 14074 DLL name, for instance `KERNEL32!CreateFileA'. The plain name is also 14075 entered into the symbol table, so `CreateFileA' is often sufficient. 14076 In some cases there will be name clashes within a program (particularly 14077 if the executable itself includes full debugging symbols) necessitating 14078 the use of the fully qualified name when referring to the contents of 14079 the DLL. Use single-quotes around the name to avoid the exclamation 14080 mark ("!") being interpreted as a language operator. 14081 14082 Note that the internal name of the DLL may be all upper-case, even 14083 though the file name of the DLL is lower-case, or vice-versa. Since 14084 symbols within GDB are _case-sensitive_ this may cause some confusion. 14085 If in doubt, try the `info functions' and `info variables' commands or 14086 even `maint print msymbols' (*note Symbols::). Here's an example: 14087 14088 (gdb) info function CreateFileA 14089 All functions matching regular expression "CreateFileA": 14090 14091 Non-debugging symbols: 14092 0x77e885f4 CreateFileA 14093 0x77e885f4 KERNEL32!CreateFileA 14094 14095 (gdb) info function ! 14096 All functions matching regular expression "!": 14097 14098 Non-debugging symbols: 14099 0x6100114c cygwin1!__assert 14100 0x61004034 cygwin1!_dll_crt0@0 14101 0x61004240 cygwin1!dll_crt0(per_process *) 14102 [etc...] 14103 14104 21.1.5.3 Working with Minimal Symbols 14105 ..................................... 14106 14107 Symbols extracted from a DLL's export table do not contain very much 14108 type information. All that GDB can do is guess whether a symbol refers 14109 to a function or variable depending on the linker section that contains 14110 the symbol. Also note that the actual contents of the memory contained 14111 in a DLL are not available unless the program is running. This means 14112 that you cannot examine the contents of a variable or disassemble a 14113 function within a DLL without a running program. 14114 14115 Variables are generally treated as pointers and dereferenced 14116 automatically. For this reason, it is often necessary to prefix a 14117 variable name with the address-of operator ("&") and provide explicit 14118 type information in the command. Here's an example of the type of 14119 problem: 14120 14121 (gdb) print 'cygwin1!__argv' 14122 $1 = 268572168 14123 14124 (gdb) x 'cygwin1!__argv' 14125 0x10021610: "\230y\"" 14126 14127 And two possible solutions: 14128 14129 (gdb) print ((char **)'cygwin1!__argv')[0] 14130 $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" 14131 14132 (gdb) x/2x &'cygwin1!__argv' 14133 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 14134 (gdb) x/x 0x10021608 14135 0x10021608: 0x0022fd98 14136 (gdb) x/s 0x0022fd98 14137 0x22fd98: "/cygdrive/c/mydirectory/myprogram" 14138 14139 Setting a break point within a DLL is possible even before the 14140 program starts execution. However, under these circumstances, GDB can't 14141 examine the initial instructions of the function in order to skip the 14142 function's frame set-up code. You can work around this by using "*&" to 14143 set the breakpoint at a raw memory address: 14144 14145 (gdb) break *&'python22!PyOS_Readline' 14146 Breakpoint 1 at 0x1e04eff0 14147 14148 The author of these extensions is not entirely convinced that 14149 setting a break point within a shared DLL like `kernel32.dll' is 14150 completely safe. 14151 14152 14153 File: gdb.info, Node: Hurd Native, Next: Neutrino, Prev: Cygwin Native, Up: Native 14154 14155 21.1.6 Commands Specific to GNU Hurd Systems 14156 -------------------------------------------- 14157 14158 This subsection describes GDB commands specific to the GNU Hurd native 14159 debugging. 14160 14161 `set signals' 14162 `set sigs' 14163 This command toggles the state of inferior signal interception by 14164 GDB. Mach exceptions, such as breakpoint traps, are not affected 14165 by this command. `sigs' is a shorthand alias for `signals'. 14166 14167 `show signals' 14168 `show sigs' 14169 Show the current state of intercepting inferior's signals. 14170 14171 `set signal-thread' 14172 `set sigthread' 14173 This command tells GDB which thread is the `libc' signal thread. 14174 That thread is run when a signal is delivered to a running 14175 process. `set sigthread' is the shorthand alias of `set 14176 signal-thread'. 14177 14178 `show signal-thread' 14179 `show sigthread' 14180 These two commands show which thread will run when the inferior is 14181 delivered a signal. 14182 14183 `set stopped' 14184 This commands tells GDB that the inferior process is stopped, as 14185 with the `SIGSTOP' signal. The stopped process can be continued 14186 by delivering a signal to it. 14187 14188 `show stopped' 14189 This command shows whether GDB thinks the debuggee is stopped. 14190 14191 `set exceptions' 14192 Use this command to turn off trapping of exceptions in the 14193 inferior. When exception trapping is off, neither breakpoints nor 14194 single-stepping will work. To restore the default, set exception 14195 trapping on. 14196 14197 `show exceptions' 14198 Show the current state of trapping exceptions in the inferior. 14199 14200 `set task pause' 14201 This command toggles task suspension when GDB has control. 14202 Setting it to on takes effect immediately, and the task is 14203 suspended whenever GDB gets control. Setting it to off will take 14204 effect the next time the inferior is continued. If this option is 14205 set to off, you can use `set thread default pause on' or `set 14206 thread pause on' (see below) to pause individual threads. 14207 14208 `show task pause' 14209 Show the current state of task suspension. 14210 14211 `set task detach-suspend-count' 14212 This command sets the suspend count the task will be left with when 14213 GDB detaches from it. 14214 14215 `show task detach-suspend-count' 14216 Show the suspend count the task will be left with when detaching. 14217 14218 `set task exception-port' 14219 `set task excp' 14220 This command sets the task exception port to which GDB will 14221 forward exceptions. The argument should be the value of the "send 14222 rights" of the task. `set task excp' is a shorthand alias. 14223 14224 `set noninvasive' 14225 This command switches GDB to a mode that is the least invasive as 14226 far as interfering with the inferior is concerned. This is the 14227 same as using `set task pause', `set exceptions', and `set 14228 signals' to values opposite to the defaults. 14229 14230 `info send-rights' 14231 `info receive-rights' 14232 `info port-rights' 14233 `info port-sets' 14234 `info dead-names' 14235 `info ports' 14236 `info psets' 14237 These commands display information about, respectively, send 14238 rights, receive rights, port rights, port sets, and dead names of 14239 a task. There are also shorthand aliases: `info ports' for `info 14240 port-rights' and `info psets' for `info port-sets'. 14241 14242 `set thread pause' 14243 This command toggles current thread suspension when GDB has 14244 control. Setting it to on takes effect immediately, and the 14245 current thread is suspended whenever GDB gets control. Setting it 14246 to off will take effect the next time the inferior is continued. 14247 Normally, this command has no effect, since when GDB has control, 14248 the whole task is suspended. However, if you used `set task pause 14249 off' (see above), this command comes in handy to suspend only the 14250 current thread. 14251 14252 `show thread pause' 14253 This command shows the state of current thread suspension. 14254 14255 `set thread run' 14256 This command sets whether the current thread is allowed to run. 14257 14258 `show thread run' 14259 Show whether the current thread is allowed to run. 14260 14261 `set thread detach-suspend-count' 14262 This command sets the suspend count GDB will leave on a thread 14263 when detaching. This number is relative to the suspend count 14264 found by GDB when it notices the thread; use `set thread 14265 takeover-suspend-count' to force it to an absolute value. 14266 14267 `show thread detach-suspend-count' 14268 Show the suspend count GDB will leave on the thread when detaching. 14269 14270 `set thread exception-port' 14271 `set thread excp' 14272 Set the thread exception port to which to forward exceptions. This 14273 overrides the port set by `set task exception-port' (see above). 14274 `set thread excp' is the shorthand alias. 14275 14276 `set thread takeover-suspend-count' 14277 Normally, GDB's thread suspend counts are relative to the value 14278 GDB finds when it notices each thread. This command changes the 14279 suspend counts to be absolute instead. 14280 14281 `set thread default' 14282 `show thread default' 14283 Each of the above `set thread' commands has a `set thread default' 14284 counterpart (e.g., `set thread default pause', `set thread default 14285 exception-port', etc.). The `thread default' variety of commands 14286 sets the default thread properties for all threads; you can then 14287 change the properties of individual threads with the non-default 14288 commands. 14289 14290 14291 File: gdb.info, Node: Neutrino, Next: Darwin, Prev: Hurd Native, Up: Native 14292 14293 21.1.7 QNX Neutrino 14294 ------------------- 14295 14296 GDB provides the following commands specific to the QNX Neutrino target: 14297 14298 `set debug nto-debug' 14299 When set to on, enables debugging messages specific to the QNX 14300 Neutrino support. 14301 14302 `show debug nto-debug' 14303 Show the current state of QNX Neutrino messages. 14304 14305 14306 File: gdb.info, Node: Darwin, Prev: Neutrino, Up: Native 14307 14308 21.1.8 Darwin 14309 ------------- 14310 14311 GDB provides the following commands specific to the Darwin target: 14312 14313 `set debug darwin NUM' 14314 When set to a non zero value, enables debugging messages specific 14315 to the Darwin support. Higher values produce more verbose output. 14316 14317 `show debug darwin' 14318 Show the current state of Darwin messages. 14319 14320 `set debug mach-o NUM' 14321 When set to a non zero value, enables debugging messages while GDB 14322 is reading Darwin object files. ("Mach-O" is the file format used 14323 on Darwin for object and executable files.) Higher values produce 14324 more verbose output. This is a command to diagnose problems 14325 internal to GDB and should not be needed in normal usage. 14326 14327 `show debug mach-o' 14328 Show the current state of Mach-O file messages. 14329 14330 `set mach-exceptions on' 14331 `set mach-exceptions off' 14332 On Darwin, faults are first reported as a Mach exception and are 14333 then mapped to a Posix signal. Use this command to turn on 14334 trapping of Mach exceptions in the inferior. This might be 14335 sometimes useful to better understand the cause of a fault. The 14336 default is off. 14337 14338 `show mach-exceptions' 14339 Show the current state of exceptions trapping. 14340 14341 14342 File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations 14343 14344 21.2 Embedded Operating Systems 14345 =============================== 14346 14347 This section describes configurations involving the debugging of 14348 embedded operating systems that are available for several different 14349 architectures. 14350 14351 * Menu: 14352 14353 * VxWorks:: Using GDB with VxWorks 14354 14355 GDB includes the ability to debug programs running on various 14356 real-time operating systems. 14357 14358 14359 File: gdb.info, Node: VxWorks, Up: Embedded OS 14360 14361 21.2.1 Using GDB with VxWorks 14362 ----------------------------- 14363 14364 `target vxworks MACHINENAME' 14365 A VxWorks system, attached via TCP/IP. The argument MACHINENAME 14366 is the target system's machine name or IP address. 14367 14368 14369 On VxWorks, `load' links FILENAME dynamically on the current target 14370 system as well as adding its symbols in GDB. 14371 14372 GDB enables developers to spawn and debug tasks running on networked 14373 VxWorks targets from a Unix host. Already-running tasks spawned from 14374 the VxWorks shell can also be debugged. GDB uses code that runs on 14375 both the Unix host and on the VxWorks target. The program `gdb' is 14376 installed and executed on the Unix host. (It may be installed with the 14377 name `vxgdb', to distinguish it from a GDB for debugging programs on 14378 the host itself.) 14379 14380 `VxWorks-timeout ARGS' 14381 All VxWorks-based targets now support the option `vxworks-timeout'. 14382 This option is set by the user, and ARGS represents the number of 14383 seconds GDB waits for responses to rpc's. You might use this if 14384 your VxWorks target is a slow software simulator or is on the far 14385 side of a thin network line. 14386 14387 The following information on connecting to VxWorks was current when 14388 this manual was produced; newer releases of VxWorks may use revised 14389 procedures. 14390 14391 To use GDB with VxWorks, you must rebuild your VxWorks kernel to 14392 include the remote debugging interface routines in the VxWorks library 14393 `rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration 14394 file `configAll.h' and rebuild your VxWorks kernel. The resulting 14395 kernel contains `rdb.a', and spawns the source debugging task 14396 `tRdbTask' when VxWorks is booted. For more information on configuring 14397 and remaking VxWorks, see the manufacturer's manual. 14398 14399 Once you have included `rdb.a' in your VxWorks system image and set 14400 your Unix execution search path to find GDB, you are ready to run GDB. 14401 From your Unix host, run `gdb' (or `vxgdb', depending on your 14402 installation). 14403 14404 GDB comes up showing the prompt: 14405 14406 (vxgdb) 14407 14408 * Menu: 14409 14410 * VxWorks Connection:: Connecting to VxWorks 14411 * VxWorks Download:: VxWorks download 14412 * VxWorks Attach:: Running tasks 14413 14414 14415 File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks 14416 14417 21.2.1.1 Connecting to VxWorks 14418 .............................. 14419 14420 The GDB command `target' lets you connect to a VxWorks target on the 14421 network. To connect to a target whose host name is "`tt'", type: 14422 14423 (vxgdb) target vxworks tt 14424 14425 GDB displays messages like these: 14426 14427 Attaching remote machine across net... 14428 Connected to tt. 14429 14430 GDB then attempts to read the symbol tables of any object modules 14431 loaded into the VxWorks target since it was last booted. GDB locates 14432 these files by searching the directories listed in the command search 14433 path (*note Your Program's Environment: Environment.); if it fails to 14434 find an object file, it displays a message such as: 14435 14436 prog.o: No such file or directory. 14437 14438 When this happens, add the appropriate directory to the search path 14439 with the GDB command `path', and execute the `target' command again. 14440 14441 14442 File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks 14443 14444 21.2.1.2 VxWorks Download 14445 ......................... 14446 14447 If you have connected to the VxWorks target and you want to debug an 14448 object that has not yet been loaded, you can use the GDB `load' command 14449 to download a file from Unix to VxWorks incrementally. The object file 14450 given as an argument to the `load' command is actually opened twice: 14451 first by the VxWorks target in order to download the code, then by GDB 14452 in order to read the symbol table. This can lead to problems if the 14453 current working directories on the two systems differ. If both systems 14454 have NFS mounted the same filesystems, you can avoid these problems by 14455 using absolute paths. Otherwise, it is simplest to set the working 14456 directory on both systems to the directory in which the object file 14457 resides, and then to reference the file by its name, without any path. 14458 For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in 14459 VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this 14460 program, type this on VxWorks: 14461 14462 -> cd "VXPATH/vw/demo/rdb" 14463 14464 Then, in GDB, type: 14465 14466 (vxgdb) cd HOSTPATH/vw/demo/rdb 14467 (vxgdb) load prog.o 14468 14469 GDB displays a response similar to this: 14470 14471 Reading symbol data from wherever/vw/demo/rdb/prog.o... done. 14472 14473 You can also use the `load' command to reload an object module after 14474 editing and recompiling the corresponding source file. Note that this 14475 makes GDB delete all currently-defined breakpoints, auto-displays, and 14476 convenience variables, and to clear the value history. (This is 14477 necessary in order to preserve the integrity of debugger's data 14478 structures that reference the target system's symbol table.) 14479 14480 14481 File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks 14482 14483 21.2.1.3 Running Tasks 14484 ...................... 14485 14486 You can also attach to an existing task using the `attach' command as 14487 follows: 14488 14489 (vxgdb) attach TASK 14490 14491 where TASK is the VxWorks hexadecimal task ID. The task can be running 14492 or suspended when you attach to it. Running tasks are suspended at the 14493 time of attachment. 14494 14495 14496 File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations 14497 14498 21.3 Embedded Processors 14499 ======================== 14500 14501 This section goes into details specific to particular embedded 14502 configurations. 14503 14504 Whenever a specific embedded processor has a simulator, GDB allows 14505 to send an arbitrary command to the simulator. 14506 14507 `sim COMMAND' 14508 Send an arbitrary COMMAND string to the simulator. Consult the 14509 documentation for the specific simulator in use for information 14510 about acceptable commands. 14511 14512 * Menu: 14513 14514 * ARM:: ARM RDI 14515 * M32R/D:: Renesas M32R/D 14516 * M68K:: Motorola M68K 14517 * MicroBlaze:: Xilinx MicroBlaze 14518 * MIPS Embedded:: MIPS Embedded 14519 * OpenRISC 1000:: OpenRisc 1000 14520 * PA:: HP PA Embedded 14521 * PowerPC Embedded:: PowerPC Embedded 14522 * Sparclet:: Tsqware Sparclet 14523 * Sparclite:: Fujitsu Sparclite 14524 * Z8000:: Zilog Z8000 14525 * AVR:: Atmel AVR 14526 * CRIS:: CRIS 14527 * Super-H:: Renesas Super-H 14528 14529 14530 File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors 14531 14532 21.3.1 ARM 14533 ---------- 14534 14535 `target rdi DEV' 14536 ARM Angel monitor, via RDI library interface to ADP protocol. You 14537 may use this target to communicate with both boards running the 14538 Angel monitor, or with the EmbeddedICE JTAG debug device. 14539 14540 `target rdp DEV' 14541 ARM Demon monitor. 14542 14543 14544 GDB provides the following ARM-specific commands: 14545 14546 `set arm disassembler' 14547 This commands selects from a list of disassembly styles. The 14548 `"std"' style is the standard style. 14549 14550 `show arm disassembler' 14551 Show the current disassembly style. 14552 14553 `set arm apcs32' 14554 This command toggles ARM operation mode between 32-bit and 26-bit. 14555 14556 `show arm apcs32' 14557 Display the current usage of the ARM 32-bit mode. 14558 14559 `set arm fpu FPUTYPE' 14560 This command sets the ARM floating-point unit (FPU) type. The 14561 argument FPUTYPE can be one of these: 14562 14563 `auto' 14564 Determine the FPU type by querying the OS ABI. 14565 14566 `softfpa' 14567 Software FPU, with mixed-endian doubles on little-endian ARM 14568 processors. 14569 14570 `fpa' 14571 GCC-compiled FPA co-processor. 14572 14573 `softvfp' 14574 Software FPU with pure-endian doubles. 14575 14576 `vfp' 14577 VFP co-processor. 14578 14579 `show arm fpu' 14580 Show the current type of the FPU. 14581 14582 `set arm abi' 14583 This command forces GDB to use the specified ABI. 14584 14585 `show arm abi' 14586 Show the currently used ABI. 14587 14588 `set arm fallback-mode (arm|thumb|auto)' 14589 GDB uses the symbol table, when available, to determine whether 14590 instructions are ARM or Thumb. This command controls GDB's 14591 default behavior when the symbol table is not available. The 14592 default is `auto', which causes GDB to use the current execution 14593 mode (from the `T' bit in the `CPSR' register). 14594 14595 `show arm fallback-mode' 14596 Show the current fallback instruction mode. 14597 14598 `set arm force-mode (arm|thumb|auto)' 14599 This command overrides use of the symbol table to determine whether 14600 instructions are ARM or Thumb. The default is `auto', which 14601 causes GDB to use the symbol table and then the setting of `set 14602 arm fallback-mode'. 14603 14604 `show arm force-mode' 14605 Show the current forced instruction mode. 14606 14607 `set debug arm' 14608 Toggle whether to display ARM-specific debugging messages from the 14609 ARM target support subsystem. 14610 14611 `show debug arm' 14612 Show whether ARM-specific debugging messages are enabled. 14613 14614 The following commands are available when an ARM target is debugged 14615 using the RDI interface: 14616 14617 `rdilogfile [FILE]' 14618 Set the filename for the ADP (Angel Debugger Protocol) packet log. 14619 With an argument, sets the log file to the specified FILE. With 14620 no argument, show the current log file name. The default log file 14621 is `rdi.log'. 14622 14623 `rdilogenable [ARG]' 14624 Control logging of ADP packets. With an argument of 1 or `"yes"' 14625 enables logging, with an argument 0 or `"no"' disables it. With 14626 no arguments displays the current setting. When logging is 14627 enabled, ADP packets exchanged between GDB and the RDI target 14628 device are logged to a file. 14629 14630 `set rdiromatzero' 14631 Tell GDB whether the target has ROM at address 0. If on, vector 14632 catching is disabled, so that zero address can be used. If off 14633 (the default), vector catching is enabled. For this command to 14634 take effect, it needs to be invoked prior to the `target rdi' 14635 command. 14636 14637 `show rdiromatzero' 14638 Show the current setting of ROM at zero address. 14639 14640 `set rdiheartbeat' 14641 Enable or disable RDI heartbeat packets. It is not recommended to 14642 turn on this option, since it confuses ARM and EPI JTAG interface, 14643 as well as the Angel monitor. 14644 14645 `show rdiheartbeat' 14646 Show the setting of RDI heartbeat packets. 14647 14648 14649 File: gdb.info, Node: M32R/D, Next: M68K, Prev: ARM, Up: Embedded Processors 14650 14651 21.3.2 Renesas M32R/D and M32R/SDI 14652 ---------------------------------- 14653 14654 `target m32r DEV' 14655 Renesas M32R/D ROM monitor. 14656 14657 `target m32rsdi DEV' 14658 Renesas M32R SDI server, connected via parallel port to the board. 14659 14660 The following GDB commands are specific to the M32R monitor: 14661 14662 `set download-path PATH' 14663 Set the default path for finding downloadable SREC files. 14664 14665 `show download-path' 14666 Show the default path for downloadable SREC files. 14667 14668 `set board-address ADDR' 14669 Set the IP address for the M32R-EVA target board. 14670 14671 `show board-address' 14672 Show the current IP address of the target board. 14673 14674 `set server-address ADDR' 14675 Set the IP address for the download server, which is the GDB's 14676 host machine. 14677 14678 `show server-address' 14679 Display the IP address of the download server. 14680 14681 `upload [FILE]' 14682 Upload the specified SREC FILE via the monitor's Ethernet upload 14683 capability. If no FILE argument is given, the current executable 14684 file is uploaded. 14685 14686 `tload [FILE]' 14687 Test the `upload' command. 14688 14689 The following commands are available for M32R/SDI: 14690 14691 `sdireset' 14692 This command resets the SDI connection. 14693 14694 `sdistatus' 14695 This command shows the SDI connection status. 14696 14697 `debug_chaos' 14698 Instructs the remote that M32R/Chaos debugging is to be used. 14699 14700 `use_debug_dma' 14701 Instructs the remote to use the DEBUG_DMA method of accessing 14702 memory. 14703 14704 `use_mon_code' 14705 Instructs the remote to use the MON_CODE method of accessing 14706 memory. 14707 14708 `use_ib_break' 14709 Instructs the remote to set breakpoints by IB break. 14710 14711 `use_dbt_break' 14712 Instructs the remote to set breakpoints by DBT. 14713 14714 14715 File: gdb.info, Node: M68K, Next: MicroBlaze, Prev: M32R/D, Up: Embedded Processors 14716 14717 21.3.3 M68k 14718 ----------- 14719 14720 The Motorola m68k configuration includes ColdFire support, and a target 14721 command for the following ROM monitor. 14722 14723 `target dbug DEV' 14724 dBUG ROM monitor for Motorola ColdFire. 14725 14726 14727 14728 File: gdb.info, Node: MicroBlaze, Next: MIPS Embedded, Prev: M68K, Up: Embedded Processors 14729 14730 21.3.4 MicroBlaze 14731 ----------------- 14732 14733 The MicroBlaze is a soft-core processor supported on various Xilinx 14734 FPGAs, such as Spartan or Virtex series. Boards with these processors 14735 usually have JTAG ports which connect to a host system running the 14736 Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK). 14737 This host system is used to download the configuration bitstream to the 14738 target FPGA. The Xilinx Microprocessor Debugger (XMD) program 14739 communicates with the target board using the JTAG interface and 14740 presents a `gdbserver' interface to the board. By default `xmd' uses 14741 port `1234'. (While it is possible to change this default port, it 14742 requires the use of undocumented `xmd' commands. Contact Xilinx 14743 support if you need to do this.) 14744 14745 Use these GDB commands to connect to the MicroBlaze target processor. 14746 14747 `target remote :1234' 14748 Use this command to connect to the target if you are running GDB 14749 on the same system as `xmd'. 14750 14751 `target remote XMD-HOST:1234' 14752 Use this command to connect to the target if it is connected to 14753 `xmd' running on a different system named XMD-HOST. 14754 14755 `load' 14756 Use this command to download a program to the MicroBlaze target. 14757 14758 `set debug microblaze N' 14759 Enable MicroBlaze-specific debugging messages if non-zero. 14760 14761 `show debug microblaze N' 14762 Show MicroBlaze-specific debugging level. 14763 14764 14765 File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze, Up: Embedded Processors 14766 14767 21.3.5 MIPS Embedded 14768 -------------------- 14769 14770 GDB can use the MIPS remote debugging protocol to talk to a MIPS board 14771 attached to a serial line. This is available when you configure GDB 14772 with `--target=mips-idt-ecoff'. 14773 14774 Use these GDB commands to specify the connection to your target 14775 board: 14776 14777 `target mips PORT' 14778 To run a program on the board, start up `gdb' with the name of 14779 your program as the argument. To connect to the board, use the 14780 command `target mips PORT', where PORT is the name of the serial 14781 port connected to the board. If the program has not already been 14782 downloaded to the board, you may use the `load' command to 14783 download it. You can then use all the usual GDB commands. 14784 14785 For example, this sequence connects to the target board through a 14786 serial port, and loads and runs a program called PROG through the 14787 debugger: 14788 14789 host$ gdb PROG 14790 GDB is free software and ... 14791 (gdb) target mips /dev/ttyb 14792 (gdb) load PROG 14793 (gdb) run 14794 14795 `target mips HOSTNAME:PORTNUMBER' 14796 On some GDB host configurations, you can specify a TCP connection 14797 (for instance, to a serial line managed by a terminal 14798 concentrator) instead of a serial port, using the syntax 14799 `HOSTNAME:PORTNUMBER'. 14800 14801 `target pmon PORT' 14802 PMON ROM monitor. 14803 14804 `target ddb PORT' 14805 NEC's DDB variant of PMON for Vr4300. 14806 14807 `target lsi PORT' 14808 LSI variant of PMON. 14809 14810 `target r3900 DEV' 14811 Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. 14812 14813 `target array DEV' 14814 Array Tech LSI33K RAID controller board. 14815 14816 14817 GDB also supports these special commands for MIPS targets: 14818 14819 `set mipsfpu double' 14820 `set mipsfpu single' 14821 `set mipsfpu none' 14822 `set mipsfpu auto' 14823 `show mipsfpu' 14824 If your target board does not support the MIPS floating point 14825 coprocessor, you should use the command `set mipsfpu none' (if you 14826 need this, you may wish to put the command in your GDB init file). 14827 This tells GDB how to find the return value of functions which 14828 return floating point values. It also allows GDB to avoid saving 14829 the floating point registers when calling functions on the board. 14830 If you are using a floating point coprocessor with only single 14831 precision floating point support, as on the R4650 processor, use 14832 the command `set mipsfpu single'. The default double precision 14833 floating point coprocessor may be selected using `set mipsfpu 14834 double'. 14835 14836 In previous versions the only choices were double precision or no 14837 floating point, so `set mipsfpu on' will select double precision 14838 and `set mipsfpu off' will select no floating point. 14839 14840 As usual, you can inquire about the `mipsfpu' variable with `show 14841 mipsfpu'. 14842 14843 `set timeout SECONDS' 14844 `set retransmit-timeout SECONDS' 14845 `show timeout' 14846 `show retransmit-timeout' 14847 You can control the timeout used while waiting for a packet, in 14848 the MIPS remote protocol, with the `set timeout SECONDS' command. 14849 The default is 5 seconds. Similarly, you can control the timeout 14850 used while waiting for an acknowledgment of a packet with the `set 14851 retransmit-timeout SECONDS' command. The default is 3 seconds. 14852 You can inspect both values with `show timeout' and `show 14853 retransmit-timeout'. (These commands are _only_ available when 14854 GDB is configured for `--target=mips-idt-ecoff'.) 14855 14856 The timeout set by `set timeout' does not apply when GDB is 14857 waiting for your program to stop. In that case, GDB waits forever 14858 because it has no way of knowing how long the program is going to 14859 run before stopping. 14860 14861 `set syn-garbage-limit NUM' 14862 Limit the maximum number of characters GDB should ignore when it 14863 tries to synchronize with the remote target. The default is 10 14864 characters. Setting the limit to -1 means there's no limit. 14865 14866 `show syn-garbage-limit' 14867 Show the current limit on the number of characters to ignore when 14868 trying to synchronize with the remote system. 14869 14870 `set monitor-prompt PROMPT' 14871 Tell GDB to expect the specified PROMPT string from the remote 14872 monitor. The default depends on the target: 14873 pmon target 14874 `PMON' 14875 14876 ddb target 14877 `NEC010' 14878 14879 lsi target 14880 `PMON>' 14881 14882 `show monitor-prompt' 14883 Show the current strings GDB expects as the prompt from the remote 14884 monitor. 14885 14886 `set monitor-warnings' 14887 Enable or disable monitor warnings about hardware breakpoints. 14888 This has effect only for the `lsi' target. When on, GDB will 14889 display warning messages whose codes are returned by the `lsi' 14890 PMON monitor for breakpoint commands. 14891 14892 `show monitor-warnings' 14893 Show the current setting of printing monitor warnings. 14894 14895 `pmon COMMAND' 14896 This command allows sending an arbitrary COMMAND string to the 14897 monitor. The monitor must be in debug mode for this to work. 14898 14899 14900 File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors 14901 14902 21.3.6 OpenRISC 1000 14903 -------------------- 14904 14905 See OR1k Architecture document (`www.opencores.org') for more 14906 information about platform and commands. 14907 14908 `target jtag jtag://HOST:PORT' 14909 Connects to remote JTAG server. JTAG remote server can be either 14910 an or1ksim or JTAG server, connected via parallel port to the 14911 board. 14912 14913 Example: `target jtag jtag://localhost:9999' 14914 14915 `or1ksim COMMAND' 14916 If connected to `or1ksim' OpenRISC 1000 Architectural Simulator, 14917 proprietary commands can be executed. 14918 14919 `info or1k spr' 14920 Displays spr groups. 14921 14922 `info or1k spr GROUP' 14923 `info or1k spr GROUPNO' 14924 Displays register names in selected group. 14925 14926 `info or1k spr GROUP REGISTER' 14927 `info or1k spr REGISTER' 14928 `info or1k spr GROUPNO REGISTERNO' 14929 `info or1k spr REGISTERNO' 14930 Shows information about specified spr register. 14931 14932 `spr GROUP REGISTER VALUE' 14933 `spr REGISTER VALUE' 14934 `spr GROUPNO REGISTERNO VALUE' 14935 `spr REGISTERNO VALUE' 14936 Writes VALUE to specified spr register. 14937 14938 Some implementations of OpenRISC 1000 Architecture also have 14939 hardware trace. It is very similar to GDB trace, except it does not 14940 interfere with normal program execution and is thus much faster. 14941 Hardware breakpoints/watchpoint triggers can be set using: 14942 `$LEA/$LDATA' 14943 Load effective address/data 14944 14945 `$SEA/$SDATA' 14946 Store effective address/data 14947 14948 `$AEA/$ADATA' 14949 Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) 14950 14951 `$FETCH' 14952 Fetch data 14953 14954 When triggered, it can capture low level data, like: `PC', `LSEA', 14955 `LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'. 14956 14957 `htrace' commands: 14958 `hwatch CONDITIONAL' 14959 Set hardware watchpoint on combination of Load/Store Effective 14960 Address(es) or Data. For example: 14961 14962 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && 14963 ($SDATA >= 50)' 14964 14965 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && 14966 ($SDATA >= 50)' 14967 14968 `htrace info' 14969 Display information about current HW trace configuration. 14970 14971 `htrace trigger CONDITIONAL' 14972 Set starting criteria for HW trace. 14973 14974 `htrace qualifier CONDITIONAL' 14975 Set acquisition qualifier for HW trace. 14976 14977 `htrace stop CONDITIONAL' 14978 Set HW trace stopping criteria. 14979 14980 `htrace record [DATA]*' 14981 Selects the data to be recorded, when qualifier is met and HW 14982 trace was triggered. 14983 14984 `htrace enable' 14985 `htrace disable' 14986 Enables/disables the HW trace. 14987 14988 `htrace rewind [FILENAME]' 14989 Clears currently recorded trace data. 14990 14991 If filename is specified, new trace file is made and any newly 14992 collected data will be written there. 14993 14994 `htrace print [START [LEN]]' 14995 Prints trace buffer, using current record configuration. 14996 14997 `htrace mode continuous' 14998 Set continuous trace mode. 14999 15000 `htrace mode suspend' 15001 Set suspend trace mode. 15002 15003 15004 15005 File: gdb.info, Node: PowerPC Embedded, Next: Sparclet, Prev: PA, Up: Embedded Processors 15006 15007 21.3.7 PowerPC Embedded 15008 ----------------------- 15009 15010 GDB provides the following PowerPC-specific commands: 15011 15012 `set powerpc soft-float' 15013 `show powerpc soft-float' 15014 Force GDB to use (or not use) a software floating point calling 15015 convention. By default, GDB selects the calling convention based 15016 on the selected architecture and the provided executable file. 15017 15018 `set powerpc vector-abi' 15019 `show powerpc vector-abi' 15020 Force GDB to use the specified calling convention for vector 15021 arguments and return values. The valid options are `auto'; 15022 `generic', to avoid vector registers even if they are present; 15023 `altivec', to use AltiVec registers; and `spe' to use SPE 15024 registers. By default, GDB selects the calling convention based 15025 on the selected architecture and the provided executable file. 15026 15027 `target dink32 DEV' 15028 DINK32 ROM monitor. 15029 15030 `target ppcbug DEV' 15031 15032 `target ppcbug1 DEV' 15033 PPCBUG ROM monitor for PowerPC. 15034 15035 `target sds DEV' 15036 SDS monitor, running on a PowerPC board (such as Motorola's ADS). 15037 15038 The following commands specific to the SDS protocol are supported by 15039 GDB: 15040 15041 `set sdstimeout NSEC' 15042 Set the timeout for SDS protocol reads to be NSEC seconds. The 15043 default is 2 seconds. 15044 15045 `show sdstimeout' 15046 Show the current value of the SDS timeout. 15047 15048 `sds COMMAND' 15049 Send the specified COMMAND string to the SDS monitor. 15050 15051 15052 File: gdb.info, Node: PA, Next: PowerPC Embedded, Prev: OpenRISC 1000, Up: Embedded Processors 15053 15054 21.3.8 HP PA Embedded 15055 --------------------- 15056 15057 `target op50n DEV' 15058 OP50N monitor, running on an OKI HPPA board. 15059 15060 `target w89k DEV' 15061 W89K monitor, running on a Winbond HPPA board. 15062 15063 15064 15065 File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PowerPC Embedded, Up: Embedded Processors 15066 15067 21.3.9 Tsqware Sparclet 15068 ----------------------- 15069 15070 GDB enables developers to debug tasks running on Sparclet targets from 15071 a Unix host. GDB uses code that runs on both the Unix host and on the 15072 Sparclet target. The program `gdb' is installed and executed on the 15073 Unix host. 15074 15075 `remotetimeout ARGS' 15076 GDB supports the option `remotetimeout'. This option is set by 15077 the user, and ARGS represents the number of seconds GDB waits for 15078 responses. 15079 15080 When compiling for debugging, include the options `-g' to get debug 15081 information and `-Ttext' to relocate the program to where you wish to 15082 load it on the target. You may also want to add the options `-n' or 15083 `-N' in order to reduce the size of the sections. Example: 15084 15085 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N 15086 15087 You can use `objdump' to verify that the addresses are what you 15088 intended: 15089 15090 sparclet-aout-objdump --headers --syms prog 15091 15092 Once you have set your Unix execution search path to find GDB, you 15093 are ready to run GDB. From your Unix host, run `gdb' (or 15094 `sparclet-aout-gdb', depending on your installation). 15095 15096 GDB comes up showing the prompt: 15097 15098 (gdbslet) 15099 15100 * Menu: 15101 15102 * Sparclet File:: Setting the file to debug 15103 * Sparclet Connection:: Connecting to Sparclet 15104 * Sparclet Download:: Sparclet download 15105 * Sparclet Execution:: Running and debugging 15106 15107 15108 File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet 15109 15110 21.3.9.1 Setting File to Debug 15111 .............................. 15112 15113 The GDB command `file' lets you choose with program to debug. 15114 15115 (gdbslet) file prog 15116 15117 GDB then attempts to read the symbol table of `prog'. GDB locates 15118 the file by searching the directories listed in the command search path. 15119 If the file was compiled with debug information (option `-g'), source 15120 files will be searched as well. GDB locates the source files by 15121 searching the directories listed in the directory search path (*note 15122 Your Program's Environment: Environment.). If it fails to find a file, 15123 it displays a message such as: 15124 15125 prog: No such file or directory. 15126 15127 When this happens, add the appropriate directories to the search 15128 paths with the GDB commands `path' and `dir', and execute the `target' 15129 command again. 15130 15131 15132 File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet 15133 15134 21.3.9.2 Connecting to Sparclet 15135 ............................... 15136 15137 The GDB command `target' lets you connect to a Sparclet target. To 15138 connect to a target on serial port "`ttya'", type: 15139 15140 (gdbslet) target sparclet /dev/ttya 15141 Remote target sparclet connected to /dev/ttya 15142 main () at ../prog.c:3 15143 15144 GDB displays messages like these: 15145 15146 Connected to ttya. 15147 15148 15149 File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet 15150 15151 21.3.9.3 Sparclet Download 15152 .......................... 15153 15154 Once connected to the Sparclet target, you can use the GDB `load' 15155 command to download the file from the host to the target. The file 15156 name and load offset should be given as arguments to the `load' command. 15157 Since the file format is aout, the program must be loaded to the 15158 starting address. You can use `objdump' to find out what this value 15159 is. The load offset is an offset which is added to the VMA (virtual 15160 memory address) of each of the file's sections. For instance, if the 15161 program `prog' was linked to text address 0x1201000, with data at 15162 0x12010160 and bss at 0x12010170, in GDB, type: 15163 15164 (gdbslet) load prog 0x12010000 15165 Loading section .text, size 0xdb0 vma 0x12010000 15166 15167 If the code is loaded at a different address then what the program 15168 was linked to, you may need to use the `section' and `add-symbol-file' 15169 commands to tell GDB where to map the symbol table. 15170 15171 15172 File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet 15173 15174 21.3.9.4 Running and Debugging 15175 .............................. 15176 15177 You can now begin debugging the task using GDB's execution control 15178 commands, `b', `step', `run', etc. See the GDB manual for the list of 15179 commands. 15180 15181 (gdbslet) b main 15182 Breakpoint 1 at 0x12010000: file prog.c, line 3. 15183 (gdbslet) run 15184 Starting program: prog 15185 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 15186 3 char *symarg = 0; 15187 (gdbslet) step 15188 4 char *execarg = "hello!"; 15189 (gdbslet) 15190 15191 15192 File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded Processors 15193 15194 21.3.10 Fujitsu Sparclite 15195 ------------------------- 15196 15197 `target sparclite DEV' 15198 Fujitsu sparclite boards, used only for the purpose of loading. 15199 You must use an additional command to debug the program. For 15200 example: target remote DEV using GDB standard remote protocol. 15201 15202 15203 15204 File: gdb.info, Node: Z8000, Next: AVR, Prev: Sparclite, Up: Embedded Processors 15205 15206 21.3.11 Zilog Z8000 15207 ------------------- 15208 15209 When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 15210 simulator. 15211 15212 For the Z8000 family, `target sim' simulates either the Z8002 (the 15213 unsegmented variant of the Z8000 architecture) or the Z8001 (the 15214 segmented variant). The simulator recognizes which architecture is 15215 appropriate by inspecting the object code. 15216 15217 `target sim ARGS' 15218 Debug programs on a simulated CPU. If the simulator supports setup 15219 options, specify them via ARGS. 15220 15221 After specifying this target, you can debug programs for the simulated 15222 CPU in the same style as programs for your host computer; use the 15223 `file' command to load a new program image, the `run' command to run 15224 your program, and so on. 15225 15226 As well as making available all the usual machine registers (*note 15227 Registers: Registers.), the Z8000 simulator provides three additional 15228 items of information as specially named registers: 15229 15230 `cycles' 15231 Counts clock-ticks in the simulator. 15232 15233 `insts' 15234 Counts instructions run in the simulator. 15235 15236 `time' 15237 Execution time in 60ths of a second. 15238 15239 15240 You can refer to these values in GDB expressions with the usual 15241 conventions; for example, `b fputc if $cycles>5000' sets a conditional 15242 breakpoint that suspends only after at least 5000 simulated clock ticks. 15243 15244 15245 File: gdb.info, Node: AVR, Next: CRIS, Prev: Z8000, Up: Embedded Processors 15246 15247 21.3.12 Atmel AVR 15248 ----------------- 15249 15250 When configured for debugging the Atmel AVR, GDB supports the following 15251 AVR-specific commands: 15252 15253 `info io_registers' 15254 This command displays information about the AVR I/O registers. For 15255 each register, GDB prints its number and value. 15256 15257 15258 File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors 15259 15260 21.3.13 CRIS 15261 ------------ 15262 15263 When configured for debugging CRIS, GDB provides the following 15264 CRIS-specific commands: 15265 15266 `set cris-version VER' 15267 Set the current CRIS version to VER, either `10' or `32'. The 15268 CRIS version affects register names and sizes. This command is 15269 useful in case autodetection of the CRIS version fails. 15270 15271 `show cris-version' 15272 Show the current CRIS version. 15273 15274 `set cris-dwarf2-cfi' 15275 Set the usage of DWARF-2 CFI for CRIS debugging. The default is 15276 `on'. Change to `off' when using `gcc-cris' whose version is below 15277 `R59'. 15278 15279 `show cris-dwarf2-cfi' 15280 Show the current state of using DWARF-2 CFI. 15281 15282 `set cris-mode MODE' 15283 Set the current CRIS mode to MODE. It should only be changed when 15284 debugging in guru mode, in which case it should be set to `guru' 15285 (the default is `normal'). 15286 15287 `show cris-mode' 15288 Show the current CRIS mode. 15289 15290 15291 File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors 15292 15293 21.3.14 Renesas Super-H 15294 ----------------------- 15295 15296 For the Renesas Super-H processor, GDB provides these commands: 15297 15298 `regs' 15299 Show the values of all Super-H registers. 15300 15301 `set sh calling-convention CONVENTION' 15302 Set the calling-convention used when calling functions from GDB. 15303 Allowed values are `gcc', which is the default setting, and 15304 `renesas'. With the `gcc' setting, functions are called using the 15305 GCC calling convention. If the DWARF-2 information of the called 15306 function specifies that the function follows the Renesas calling 15307 convention, the function is called using the Renesas calling 15308 convention. If the calling convention is set to `renesas', the 15309 Renesas calling convention is always used, regardless of the 15310 DWARF-2 information. This can be used to override the default of 15311 `gcc' if debug information is missing, or the compiler does not 15312 emit the DWARF-2 calling convention entry for a function. 15313 15314 `show sh calling-convention' 15315 Show the current calling convention setting. 15316 15317 15318 15319 File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations 15320 15321 21.4 Architectures 15322 ================== 15323 15324 This section describes characteristics of architectures that affect all 15325 uses of GDB with the architecture, both native and cross. 15326 15327 * Menu: 15328 15329 * i386:: 15330 * A29K:: 15331 * Alpha:: 15332 * MIPS:: 15333 * HPPA:: HP PA architecture 15334 * SPU:: Cell Broadband Engine SPU architecture 15335 * PowerPC:: 15336 15337 15338 File: gdb.info, Node: i386, Next: A29K, Up: Architectures 15339 15340 21.4.1 x86 Architecture-specific Issues 15341 --------------------------------------- 15342 15343 `set struct-convention MODE' 15344 Set the convention used by the inferior to return `struct's and 15345 `union's from functions to MODE. Possible values of MODE are 15346 `"pcc"', `"reg"', and `"default"' (the default). `"default"' or 15347 `"pcc"' means that `struct's are returned on the stack, while 15348 `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4, 15349 or 8 bytes will be returned in a register. 15350 15351 `show struct-convention' 15352 Show the current setting of the convention to return `struct's 15353 from functions. 15354 15355 15356 File: gdb.info, Node: A29K, Next: Alpha, Prev: i386, Up: Architectures 15357 15358 21.4.2 A29K 15359 ----------- 15360 15361 `set rstack_high_address ADDRESS' 15362 On AMD 29000 family processors, registers are saved in a separate 15363 "register stack". There is no way for GDB to determine the extent 15364 of this stack. Normally, GDB just assumes that the stack is 15365 "large enough". This may result in GDB referencing memory 15366 locations that do not exist. If necessary, you can get around 15367 this problem by specifying the ending address of the register 15368 stack with the `set rstack_high_address' command. The argument 15369 should be an address, which you probably want to precede with `0x' 15370 to specify in hexadecimal. 15371 15372 `show rstack_high_address' 15373 Display the current limit of the register stack, on AMD 29000 15374 family processors. 15375 15376 15377 15378 File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures 15379 15380 21.4.3 Alpha 15381 ------------ 15382 15383 See the following section. 15384 15385 15386 File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures 15387 15388 21.4.4 MIPS 15389 ----------- 15390 15391 Alpha- and MIPS-based computers use an unusual stack frame, which 15392 sometimes requires GDB to search backward in the object code to find 15393 the beginning of a function. 15394 15395 To improve response time (especially for embedded applications, where 15396 GDB may be restricted to a slow serial line for this search) you may 15397 want to limit the size of this search, using one of these commands: 15398 15399 `set heuristic-fence-post LIMIT' 15400 Restrict GDB to examining at most LIMIT bytes in its search for 15401 the beginning of a function. A value of 0 (the default) means 15402 there is no limit. However, except for 0, the larger the limit 15403 the more bytes `heuristic-fence-post' must search and therefore 15404 the longer it takes to run. You should only need to use this 15405 command when debugging a stripped executable. 15406 15407 `show heuristic-fence-post' 15408 Display the current limit. 15409 15410 These commands are available _only_ when GDB is configured for 15411 debugging programs on Alpha or MIPS processors. 15412 15413 Several MIPS-specific commands are available when debugging MIPS 15414 programs: 15415 15416 `set mips abi ARG' 15417 Tell GDB which MIPS ABI is used by the inferior. Possible values 15418 of ARG are: 15419 15420 `auto' 15421 The default ABI associated with the current binary (this is 15422 the default). 15423 15424 `o32' 15425 15426 `o64' 15427 15428 `n32' 15429 15430 `n64' 15431 15432 `eabi32' 15433 15434 `eabi64' 15435 15436 `auto' 15437 15438 `show mips abi' 15439 Show the MIPS ABI used by GDB to debug the inferior. 15440 15441 `set mipsfpu' 15442 `show mipsfpu' 15443 *Note set mipsfpu: MIPS Embedded. 15444 15445 `set mips mask-address ARG' 15446 This command determines whether the most-significant 32 bits of 15447 64-bit MIPS addresses are masked off. The argument ARG can be 15448 `on', `off', or `auto'. The latter is the default setting, which 15449 lets GDB determine the correct value. 15450 15451 `show mips mask-address' 15452 Show whether the upper 32 bits of MIPS addresses are masked off or 15453 not. 15454 15455 `set remote-mips64-transfers-32bit-regs' 15456 This command controls compatibility with 64-bit MIPS targets that 15457 transfer data in 32-bit quantities. If you have an old MIPS 64 15458 target that transfers 32 bits for some registers, like SR and FSR, 15459 and 64 bits for other registers, set this option to `on'. 15460 15461 `show remote-mips64-transfers-32bit-regs' 15462 Show the current setting of compatibility with older MIPS 64 15463 targets. 15464 15465 `set debug mips' 15466 This command turns on and off debugging messages for the 15467 MIPS-specific target code in GDB. 15468 15469 `show debug mips' 15470 Show the current setting of MIPS debugging messages. 15471 15472 15473 File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures 15474 15475 21.4.5 HPPA 15476 ----------- 15477 15478 When GDB is debugging the HP PA architecture, it provides the following 15479 special commands: 15480 15481 `set debug hppa' 15482 This command determines whether HPPA architecture-specific 15483 debugging messages are to be displayed. 15484 15485 `show debug hppa' 15486 Show whether HPPA debugging messages are displayed. 15487 15488 `maint print unwind ADDRESS' 15489 This command displays the contents of the unwind table entry at the 15490 given ADDRESS. 15491 15492 15493 15494 File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures 15495 15496 21.4.6 Cell Broadband Engine SPU architecture 15497 --------------------------------------------- 15498 15499 When GDB is debugging the Cell Broadband Engine SPU architecture, it 15500 provides the following special commands: 15501 15502 `info spu event' 15503 Display SPU event facility status. Shows current event mask and 15504 pending event status. 15505 15506 `info spu signal' 15507 Display SPU signal notification facility status. Shows pending 15508 signal-control word and signal notification mode of both signal 15509 notification channels. 15510 15511 `info spu mailbox' 15512 Display SPU mailbox facility status. Shows all pending entries, 15513 in order of processing, in each of the SPU Write Outbound, SPU 15514 Write Outbound Interrupt, and SPU Read Inbound mailboxes. 15515 15516 `info spu dma' 15517 Display MFC DMA status. Shows all pending commands in the MFC DMA 15518 queue. For each entry, opcode, tag, class IDs, effective and 15519 local store addresses and transfer size are shown. 15520 15521 `info spu proxydma' 15522 Display MFC Proxy-DMA status. Shows all pending commands in the 15523 MFC Proxy-DMA queue. For each entry, opcode, tag, class IDs, 15524 effective and local store addresses and transfer size are shown. 15525 15526 15527 When GDB is debugging a combined PowerPC/SPU application on the Cell 15528 Broadband Engine, it provides in addition the following special 15529 commands: 15530 15531 `set spu stop-on-load ARG' 15532 Set whether to stop for new SPE threads. When set to `on', GDB 15533 will give control to the user when a new SPE thread enters its 15534 `main' function. The default is `off'. 15535 15536 `show spu stop-on-load' 15537 Show whether to stop for new SPE threads. 15538 15539 `set spu auto-flush-cache ARG' 15540 Set whether to automatically flush the software-managed cache. 15541 When set to `on', GDB will automatically cause the SPE 15542 software-managed cache to be flushed whenever SPE execution stops. 15543 This provides a consistent view of PowerPC memory that is 15544 accessed via the cache. If an application does not use the 15545 software-managed cache, this option has no effect. 15546 15547 `show spu auto-flush-cache' 15548 Show whether to automatically flush the software-managed cache. 15549 15550 15551 15552 File: gdb.info, Node: PowerPC, Prev: SPU, Up: Architectures 15553 15554 21.4.7 PowerPC 15555 -------------- 15556 15557 When GDB is debugging the PowerPC architecture, it provides a set of 15558 pseudo-registers to enable inspection of 128-bit wide Decimal Floating 15559 Point numbers stored in the floating point registers. These values must 15560 be stored in two consecutive registers, always starting at an even 15561 register like `f0' or `f2'. 15562 15563 The pseudo-registers go from `$dl0' through `$dl15', and are formed 15564 by joining the even/odd register pairs `f0' and `f1' for `$dl0', `f2' 15565 and `f3' for `$dl1' and so on. 15566 15567 For POWER7 processors, GDB provides a set of pseudo-registers, the 15568 64-bit wide Extended Floating Point Registers (`f32' through `f63'). 15569 15570 15571 File: gdb.info, Node: Controlling GDB, Next: Extending GDB, Prev: Configurations, Up: Top 15572 15573 22 Controlling GDB 15574 ****************** 15575 15576 You can alter the way GDB interacts with you by using the `set' 15577 command. For commands controlling how GDB displays data, see *Note 15578 Print Settings: Print Settings. Other settings are described here. 15579 15580 * Menu: 15581 15582 * Prompt:: Prompt 15583 * Editing:: Command editing 15584 * Command History:: Command history 15585 * Screen Size:: Screen size 15586 * Numbers:: Numbers 15587 * ABI:: Configuring the current ABI 15588 * Messages/Warnings:: Optional warnings and messages 15589 * Debugging Output:: Optional messages about internal happenings 15590 * Other Misc Settings:: Other Miscellaneous Settings 15591 15592 15593 File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB 15594 15595 22.1 Prompt 15596 =========== 15597 15598 GDB indicates its readiness to read a command by printing a string 15599 called the "prompt". This string is normally `(gdb)'. You can change 15600 the prompt string with the `set prompt' command. For instance, when 15601 debugging GDB with GDB, it is useful to change the prompt in one of the 15602 GDB sessions so that you can always tell which one you are talking to. 15603 15604 _Note:_ `set prompt' does not add a space for you after the prompt 15605 you set. This allows you to set a prompt which ends in a space or a 15606 prompt that does not. 15607 15608 `set prompt NEWPROMPT' 15609 Directs GDB to use NEWPROMPT as its prompt string henceforth. 15610 15611 `show prompt' 15612 Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT' 15613 15614 15615 File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB 15616 15617 22.2 Command Editing 15618 ==================== 15619 15620 GDB reads its input commands via the "Readline" interface. This GNU 15621 library provides consistent behavior for programs which provide a 15622 command line interface to the user. Advantages are GNU Emacs-style or 15623 "vi"-style inline editing of commands, `csh'-like history substitution, 15624 and a storage and recall of command history across debugging sessions. 15625 15626 You may control the behavior of command line editing in GDB with the 15627 command `set'. 15628 15629 `set editing' 15630 `set editing on' 15631 Enable command line editing (enabled by default). 15632 15633 `set editing off' 15634 Disable command line editing. 15635 15636 `show editing' 15637 Show whether command line editing is enabled. 15638 15639 *Note Command Line Editing::, for more details about the Readline 15640 interface. Users unfamiliar with GNU Emacs or `vi' are encouraged to 15641 read that chapter. 15642 15643 15644 File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB 15645 15646 22.3 Command History 15647 ==================== 15648 15649 GDB can keep track of the commands you type during your debugging 15650 sessions, so that you can be certain of precisely what happened. Use 15651 these commands to manage the GDB command history facility. 15652 15653 GDB uses the GNU History library, a part of the Readline package, to 15654 provide the history facility. *Note Using History Interactively::, for 15655 the detailed description of the History library. 15656 15657 To issue a command to GDB without affecting certain aspects of the 15658 state which is seen by users, prefix it with `server ' (*note Server 15659 Prefix::). This means that this command will not affect the command 15660 history, nor will it affect GDB's notion of which command to repeat if 15661 <RET> is pressed on a line by itself. 15662 15663 The server prefix does not affect the recording of values into the 15664 value history; to print a value without recording it into the value 15665 history, use the `output' command instead of the `print' command. 15666 15667 Here is the description of GDB commands related to command history. 15668 15669 `set history filename FNAME' 15670 Set the name of the GDB command history file to FNAME. This is 15671 the file where GDB reads an initial command history list, and 15672 where it writes the command history from this session when it 15673 exits. You can access this list through history expansion or 15674 through the history command editing characters listed below. This 15675 file defaults to the value of the environment variable 15676 `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS) 15677 if this variable is not set. 15678 15679 `set history save' 15680 `set history save on' 15681 Record command history in a file, whose name may be specified with 15682 the `set history filename' command. By default, this option is 15683 disabled. 15684 15685 `set history save off' 15686 Stop recording command history in a file. 15687 15688 `set history size SIZE' 15689 Set the number of commands which GDB keeps in its history list. 15690 This defaults to the value of the environment variable `HISTSIZE', 15691 or to 256 if this variable is not set. 15692 15693 History expansion assigns special meaning to the character `!'. 15694 *Note Event Designators::, for more details. 15695 15696 Since `!' is also the logical not operator in C, history expansion 15697 is off by default. If you decide to enable history expansion with the 15698 `set history expansion on' command, you may sometimes need to follow 15699 `!' (when it is used as logical not, in an expression) with a space or 15700 a tab to prevent it from being expanded. The readline history 15701 facilities do not attempt substitution on the strings `!=' and `!(', 15702 even when history expansion is enabled. 15703 15704 The commands to control history expansion are: 15705 15706 `set history expansion on' 15707 `set history expansion' 15708 Enable history expansion. History expansion is off by default. 15709 15710 `set history expansion off' 15711 Disable history expansion. 15712 15713 `show history' 15714 `show history filename' 15715 `show history save' 15716 `show history size' 15717 `show history expansion' 15718 These commands display the state of the GDB history parameters. 15719 `show history' by itself displays all four states. 15720 15721 `show commands' 15722 Display the last ten commands in the command history. 15723 15724 `show commands N' 15725 Print ten commands centered on command number N. 15726 15727 `show commands +' 15728 Print ten commands just after the commands last printed. 15729 15730 15731 File: gdb.info, Node: Screen Size, Next: Numbers, Prev: Command History, Up: Controlling GDB 15732 15733 22.4 Screen Size 15734 ================ 15735 15736 Certain commands to GDB may produce large amounts of information output 15737 to the screen. To help you read all of it, GDB pauses and asks you for 15738 input at the end of each page of output. Type <RET> when you want to 15739 continue the output, or `q' to discard the remaining output. Also, the 15740 screen width setting determines when to wrap lines of output. 15741 Depending on what is being printed, GDB tries to break the line at a 15742 readable place, rather than simply letting it overflow onto the 15743 following line. 15744 15745 Normally GDB knows the size of the screen from the terminal driver 15746 software. For example, on Unix GDB uses the termcap data base together 15747 with the value of the `TERM' environment variable and the `stty rows' 15748 and `stty cols' settings. If this is not correct, you can override it 15749 with the `set height' and `set width' commands: 15750 15751 `set height LPP' 15752 `show height' 15753 `set width CPL' 15754 `show width' 15755 These `set' commands specify a screen height of LPP lines and a 15756 screen width of CPL characters. The associated `show' commands 15757 display the current settings. 15758 15759 If you specify a height of zero lines, GDB does not pause during 15760 output no matter how long the output is. This is useful if output 15761 is to a file or to an editor buffer. 15762 15763 Likewise, you can specify `set width 0' to prevent GDB from 15764 wrapping its output. 15765 15766 `set pagination on' 15767 `set pagination off' 15768 Turn the output pagination on or off; the default is on. Turning 15769 pagination off is the alternative to `set height 0'. 15770 15771 `show pagination' 15772 Show the current pagination mode. 15773 15774 15775 File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB 15776 15777 22.5 Numbers 15778 ============ 15779 15780 You can always enter numbers in octal, decimal, or hexadecimal in GDB 15781 by the usual conventions: octal numbers begin with `0', decimal numbers 15782 end with `.', and hexadecimal numbers begin with `0x'. Numbers that 15783 neither begin with `0' or `0x', nor end with a `.' are, by default, 15784 entered in base 10; likewise, the default display for numbers--when no 15785 particular format is specified--is base 10. You can change the default 15786 base for both input and output with the commands described below. 15787 15788 `set input-radix BASE' 15789 Set the default base for numeric input. Supported choices for 15790 BASE are decimal 8, 10, or 16. BASE must itself be specified 15791 either unambiguously or using the current input radix; for 15792 example, any of 15793 15794 set input-radix 012 15795 set input-radix 10. 15796 set input-radix 0xa 15797 15798 sets the input base to decimal. On the other hand, `set 15799 input-radix 10' leaves the input radix unchanged, no matter what 15800 it was, since `10', being without any leading or trailing signs of 15801 its base, is interpreted in the current radix. Thus, if the 15802 current radix is 16, `10' is interpreted in hex, i.e. as 16 15803 decimal, which doesn't change the radix. 15804 15805 `set output-radix BASE' 15806 Set the default base for numeric display. Supported choices for 15807 BASE are decimal 8, 10, or 16. BASE must itself be specified 15808 either unambiguously or using the current input radix. 15809 15810 `show input-radix' 15811 Display the current default base for numeric input. 15812 15813 `show output-radix' 15814 Display the current default base for numeric display. 15815 15816 `set radix [BASE]' 15817 `show radix' 15818 These commands set and show the default base for both input and 15819 output of numbers. `set radix' sets the radix of input and output 15820 to the same base; without an argument, it resets the radix back to 15821 its default value of 10. 15822 15823 15824 15825 File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Controlling GDB 15826 15827 22.6 Configuring the Current ABI 15828 ================================ 15829 15830 GDB can determine the "ABI" (Application Binary Interface) of your 15831 application automatically. However, sometimes you need to override its 15832 conclusions. Use these commands to manage GDB's view of the current 15833 ABI. 15834 15835 One GDB configuration can debug binaries for multiple operating 15836 system targets, either via remote debugging or native emulation. GDB 15837 will autodetect the "OS ABI" (Operating System ABI) in use, but you can 15838 override its conclusion using the `set osabi' command. One example 15839 where this is useful is in debugging of binaries which use an alternate 15840 C library (e.g. UCLIBC for GNU/Linux) which does not have the same 15841 identifying marks that the standard C library for your platform 15842 provides. 15843 15844 `show osabi' 15845 Show the OS ABI currently in use. 15846 15847 `set osabi' 15848 With no argument, show the list of registered available OS ABI's. 15849 15850 `set osabi ABI' 15851 Set the current OS ABI to ABI. 15852 15853 Generally, the way that an argument of type `float' is passed to a 15854 function depends on whether the function is prototyped. For a 15855 prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed 15856 unchanged, according to the architecture's convention for `float'. For 15857 unprototyped (i.e. K&R style) functions, `float' arguments are first 15858 promoted to type `double' and then passed. 15859 15860 Unfortunately, some forms of debug information do not reliably 15861 indicate whether a function is prototyped. If GDB calls a function 15862 that is not marked as prototyped, it consults `set 15863 coerce-float-to-double'. 15864 15865 `set coerce-float-to-double' 15866 `set coerce-float-to-double on' 15867 Arguments of type `float' will be promoted to `double' when passed 15868 to an unprototyped function. This is the default setting. 15869 15870 `set coerce-float-to-double off' 15871 Arguments of type `float' will be passed directly to unprototyped 15872 functions. 15873 15874 `show coerce-float-to-double' 15875 Show the current setting of promoting `float' to `double'. 15876 15877 GDB needs to know the ABI used for your program's C++ objects. The 15878 correct C++ ABI depends on which C++ compiler was used to build your 15879 application. GDB only fully supports programs with a single C++ ABI; 15880 if your program contains code using multiple C++ ABI's or if GDB can 15881 not identify your program's ABI correctly, you can tell GDB which ABI 15882 to use. Currently supported ABI's include "gnu-v2", for `g++' versions 15883 before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for 15884 the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or 15885 "gnu-v3" ABI's as well. The default setting is "auto". 15886 15887 `show cp-abi' 15888 Show the C++ ABI currently in use. 15889 15890 `set cp-abi' 15891 With no argument, show the list of supported C++ ABI's. 15892 15893 `set cp-abi ABI' 15894 `set cp-abi auto' 15895 Set the current C++ ABI to ABI, or return to automatic detection. 15896 15897 15898 File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI, Up: Controlling GDB 15899 15900 22.7 Optional Warnings and Messages 15901 =================================== 15902 15903 By default, GDB is silent about its inner workings. If you are running 15904 on a slow machine, you may want to use the `set verbose' command. This 15905 makes GDB tell you when it does a lengthy internal operation, so you 15906 will not think it has crashed. 15907 15908 Currently, the messages controlled by `set verbose' are those which 15909 announce that the symbol table for a source file is being read; see 15910 `symbol-file' in *Note Commands to Specify Files: Files. 15911 15912 `set verbose on' 15913 Enables GDB output of certain informational messages. 15914 15915 `set verbose off' 15916 Disables GDB output of certain informational messages. 15917 15918 `show verbose' 15919 Displays whether `set verbose' is on or off. 15920 15921 By default, if GDB encounters bugs in the symbol table of an object 15922 file, it is silent; but if you are debugging a compiler, you may find 15923 this information useful (*note Errors Reading Symbol Files: Symbol 15924 Errors.). 15925 15926 `set complaints LIMIT' 15927 Permits GDB to output LIMIT complaints about each type of unusual 15928 symbols before becoming silent about the problem. Set LIMIT to 15929 zero to suppress all complaints; set it to a large number to 15930 prevent complaints from being suppressed. 15931 15932 `show complaints' 15933 Displays how many symbol complaints GDB is permitted to produce. 15934 15935 15936 By default, GDB is cautious, and asks what sometimes seems to be a 15937 lot of stupid questions to confirm certain commands. For example, if 15938 you try to run a program which is already running: 15939 15940 (gdb) run 15941 The program being debugged has been started already. 15942 Start it from the beginning? (y or n) 15943 15944 If you are willing to unflinchingly face the consequences of your own 15945 commands, you can disable this "feature": 15946 15947 `set confirm off' 15948 Disables confirmation requests. 15949 15950 `set confirm on' 15951 Enables confirmation requests (the default). 15952 15953 `show confirm' 15954 Displays state of confirmation requests. 15955 15956 15957 If you need to debug user-defined commands or sourced files you may 15958 find it useful to enable "command tracing". In this mode each command 15959 will be printed as it is executed, prefixed with one or more `+' 15960 symbols, the quantity denoting the call depth of each command. 15961 15962 `set trace-commands on' 15963 Enable command tracing. 15964 15965 `set trace-commands off' 15966 Disable command tracing. 15967 15968 `show trace-commands' 15969 Display the current state of command tracing. 15970 15971 15972 File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB 15973 15974 22.8 Optional Messages about Internal Happenings 15975 ================================================ 15976 15977 GDB has commands that enable optional debugging messages from various 15978 GDB subsystems; normally these commands are of interest to GDB 15979 maintainers, or when reporting a bug. This section documents those 15980 commands. 15981 15982 `set exec-done-display' 15983 Turns on or off the notification of asynchronous commands' 15984 completion. When on, GDB will print a message when an 15985 asynchronous command finishes its execution. The default is off. 15986 15987 `show exec-done-display' 15988 Displays the current setting of asynchronous command completion 15989 notification. 15990 15991 `set debug arch' 15992 Turns on or off display of gdbarch debugging info. The default is 15993 off 15994 15995 `show debug arch' 15996 Displays the current state of displaying gdbarch debugging info. 15997 15998 `set debug aix-thread' 15999 Display debugging messages about inner workings of the AIX thread 16000 module. 16001 16002 `show debug aix-thread' 16003 Show the current state of AIX thread debugging info display. 16004 16005 `set debug dwarf2-die' 16006 Dump DWARF2 DIEs after they are read in. The value is the number 16007 of nesting levels to print. A value of zero turns off the display. 16008 16009 `show debug dwarf2-die' 16010 Show the current state of DWARF2 DIE debugging. 16011 16012 `set debug displaced' 16013 Turns on or off display of GDB debugging info for the displaced 16014 stepping support. The default is off. 16015 16016 `show debug displaced' 16017 Displays the current state of displaying GDB debugging info 16018 related to displaced stepping. 16019 16020 `set debug event' 16021 Turns on or off display of GDB event debugging info. The default 16022 is off. 16023 16024 `show debug event' 16025 Displays the current state of displaying GDB event debugging info. 16026 16027 `set debug expression' 16028 Turns on or off display of debugging info about GDB expression 16029 parsing. The default is off. 16030 16031 `show debug expression' 16032 Displays the current state of displaying debugging info about GDB 16033 expression parsing. 16034 16035 `set debug frame' 16036 Turns on or off display of GDB frame debugging info. The default 16037 is off. 16038 16039 `show debug frame' 16040 Displays the current state of displaying GDB frame debugging info. 16041 16042 `set debug gnu-nat' 16043 Turns on or off debugging messages from the GNU/Hurd debug support. 16044 16045 `show debug gnu-nat' 16046 Show the current state of GNU/Hurd debugging messages. 16047 16048 `set debug infrun' 16049 Turns on or off display of GDB debugging info for running the 16050 inferior. The default is off. `infrun.c' contains GDB's runtime 16051 state machine used for implementing operations such as 16052 single-stepping the inferior. 16053 16054 `show debug infrun' 16055 Displays the current state of GDB inferior debugging. 16056 16057 `set debug lin-lwp' 16058 Turns on or off debugging messages from the Linux LWP debug 16059 support. 16060 16061 `show debug lin-lwp' 16062 Show the current state of Linux LWP debugging messages. 16063 16064 `set debug lin-lwp-async' 16065 Turns on or off debugging messages from the Linux LWP async debug 16066 support. 16067 16068 `show debug lin-lwp-async' 16069 Show the current state of Linux LWP async debugging messages. 16070 16071 `set debug observer' 16072 Turns on or off display of GDB observer debugging. This includes 16073 info such as the notification of observable events. 16074 16075 `show debug observer' 16076 Displays the current state of observer debugging. 16077 16078 `set debug overload' 16079 Turns on or off display of GDB C++ overload debugging info. This 16080 includes info such as ranking of functions, etc. The default is 16081 off. 16082 16083 `show debug overload' 16084 Displays the current state of displaying GDB C++ overload 16085 debugging info. 16086 16087 `set debug parser' 16088 Turns on or off the display of expression parser debugging output. 16089 Internally, this sets the `yydebug' variable in the expression 16090 parser. *Note Tracing Your Parser: (bison)Tracing, for details. 16091 The default is off. 16092 16093 `show debug parser' 16094 Show the current state of expression parser debugging. 16095 16096 `set debug remote' 16097 Turns on or off display of reports on all packets sent back and 16098 forth across the serial line to the remote machine. The info is 16099 printed on the GDB standard output stream. The default is off. 16100 16101 `show debug remote' 16102 Displays the state of display of remote packets. 16103 16104 `set debug serial' 16105 Turns on or off display of GDB serial debugging info. The default 16106 is off. 16107 16108 `show debug serial' 16109 Displays the current state of displaying GDB serial debugging info. 16110 16111 `set debug solib-frv' 16112 Turns on or off debugging messages for FR-V shared-library code. 16113 16114 `show debug solib-frv' 16115 Display the current state of FR-V shared-library code debugging 16116 messages. 16117 16118 `set debug target' 16119 Turns on or off display of GDB target debugging info. This info 16120 includes what is going on at the target level of GDB, as it 16121 happens. The default is 0. Set it to 1 to track events, and to 2 16122 to also track the value of large memory transfers. Changes to 16123 this flag do not take effect until the next time you connect to a 16124 target or use the `run' command. 16125 16126 `show debug target' 16127 Displays the current state of displaying GDB target debugging info. 16128 16129 `set debug timestamp' 16130 Turns on or off display of timestamps with GDB debugging info. 16131 When enabled, seconds and microseconds are displayed before each 16132 debugging message. 16133 16134 `show debug timestamp' 16135 Displays the current state of displaying timestamps with GDB 16136 debugging info. 16137 16138 `set debugvarobj' 16139 Turns on or off display of GDB variable object debugging info. The 16140 default is off. 16141 16142 `show debugvarobj' 16143 Displays the current state of displaying GDB variable object 16144 debugging info. 16145 16146 `set debug xml' 16147 Turns on or off debugging messages for built-in XML parsers. 16148 16149 `show debug xml' 16150 Displays the current state of XML debugging messages. 16151 16152 16153 File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB 16154 16155 22.9 Other Miscellaneous Settings 16156 ================================= 16157 16158 `set interactive-mode' 16159 If `on', forces GDB to operate interactively. If `off', forces 16160 GDB to operate non-interactively, If `auto' (the default), GDB 16161 guesses which mode to use, based on whether the debugger was 16162 started in a terminal or not. 16163 16164 In the vast majority of cases, the debugger should be able to guess 16165 correctly which mode should be used. But this setting can be 16166 useful in certain specific cases, such as running a MinGW GDB 16167 inside a cygwin window. 16168 16169 `show interactive-mode' 16170 Displays whether the debugger is operating in interactive mode or 16171 not. 16172 16173 16174 File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top 16175 16176 23 Extending GDB 16177 **************** 16178 16179 GDB provides two mechanisms for extension. The first is based on 16180 composition of GDB commands, and the second is based on the Python 16181 scripting language. 16182 16183 To facilitate the use of these extensions, GDB is capable of 16184 evaluating the contents of a file. When doing so, GDB can recognize 16185 which scripting language is being used by looking at the filename 16186 extension. Files with an unrecognized filename extension are always 16187 treated as a GDB Command Files. *Note Command files: Command Files. 16188 16189 You can control how GDB evaluates these files with the following 16190 setting: 16191 16192 `set script-extension off' 16193 All scripts are always evaluated as GDB Command Files. 16194 16195 `set script-extension soft' 16196 The debugger determines the scripting language based on filename 16197 extension. If this scripting language is supported, GDB evaluates 16198 the script using that language. Otherwise, it evaluates the file 16199 as a GDB Command File. 16200 16201 `set script-extension strict' 16202 The debugger determines the scripting language based on filename 16203 extension, and evaluates the script using that language. If the 16204 language is not supported, then the evaluation fails. 16205 16206 `show script-extension' 16207 Display the current value of the `script-extension' option. 16208 16209 16210 * Menu: 16211 16212 * Sequences:: Canned Sequences of Commands 16213 * Python:: Scripting GDB using Python 16214 16215 16216 File: gdb.info, Node: Sequences, Next: Python, Up: Extending GDB 16217 16218 23.1 Canned Sequences of Commands 16219 ================================= 16220 16221 Aside from breakpoint commands (*note Breakpoint Command Lists: Break 16222 Commands.), GDB provides two ways to store sequences of commands for 16223 execution as a unit: user-defined commands and command files. 16224 16225 * Menu: 16226 16227 * Define:: How to define your own commands 16228 * Hooks:: Hooks for user-defined commands 16229 * Command Files:: How to write scripts of commands to be stored in a file 16230 * Output:: Commands for controlled output 16231 16232 16233 File: gdb.info, Node: Define, Next: Hooks, Up: Sequences 16234 16235 23.1.1 User-defined Commands 16236 ---------------------------- 16237 16238 A "user-defined command" is a sequence of GDB commands to which you 16239 assign a new name as a command. This is done with the `define' 16240 command. User commands may accept up to 10 arguments separated by 16241 whitespace. Arguments are accessed within the user command via 16242 `$arg0...$arg9'. A trivial example: 16243 16244 define adder 16245 print $arg0 + $arg1 + $arg2 16246 end 16247 16248 To execute the command use: 16249 16250 adder 1 2 3 16251 16252 This defines the command `adder', which prints the sum of its three 16253 arguments. Note the arguments are text substitutions, so they may 16254 reference variables, use complex expressions, or even perform inferior 16255 functions calls. 16256 16257 In addition, `$argc' may be used to find out how many arguments have 16258 been passed. This expands to a number in the range 0...10. 16259 16260 define adder 16261 if $argc == 2 16262 print $arg0 + $arg1 16263 end 16264 if $argc == 3 16265 print $arg0 + $arg1 + $arg2 16266 end 16267 end 16268 16269 `define COMMANDNAME' 16270 Define a command named COMMANDNAME. If there is already a command 16271 by that name, you are asked to confirm that you want to redefine 16272 it. COMMANDNAME may be a bare command name consisting of letters, 16273 numbers, dashes, and underscores. It may also start with any 16274 predefined prefix command. For example, `define target my-target' 16275 creates a user-defined `target my-target' command. 16276 16277 The definition of the command is made up of other GDB command 16278 lines, which are given following the `define' command. The end of 16279 these commands is marked by a line containing `end'. 16280 16281 `document COMMANDNAME' 16282 Document the user-defined command COMMANDNAME, so that it can be 16283 accessed by `help'. The command COMMANDNAME must already be 16284 defined. This command reads lines of documentation just as 16285 `define' reads the lines of the command definition, ending with 16286 `end'. After the `document' command is finished, `help' on command 16287 COMMANDNAME displays the documentation you have written. 16288 16289 You may use the `document' command again to change the 16290 documentation of a command. Redefining the command with `define' 16291 does not change the documentation. 16292 16293 `dont-repeat' 16294 Used inside a user-defined command, this tells GDB that this 16295 command should not be repeated when the user hits <RET> (*note 16296 repeat last command: Command Syntax.). 16297 16298 `help user-defined' 16299 List all user-defined commands, with the first line of the 16300 documentation (if any) for each. 16301 16302 `show user' 16303 `show user COMMANDNAME' 16304 Display the GDB commands used to define COMMANDNAME (but not its 16305 documentation). If no COMMANDNAME is given, display the 16306 definitions for all user-defined commands. 16307 16308 `show max-user-call-depth' 16309 `set max-user-call-depth' 16310 The value of `max-user-call-depth' controls how many recursion 16311 levels are allowed in user-defined commands before GDB suspects an 16312 infinite recursion and aborts the command. 16313 16314 In addition to the above commands, user-defined commands frequently 16315 use control flow commands, described in *Note Command Files::. 16316 16317 When user-defined commands are executed, the commands of the 16318 definition are not printed. An error in any command stops execution of 16319 the user-defined command. 16320 16321 If used interactively, commands that would ask for confirmation 16322 proceed without asking when used inside a user-defined command. Many 16323 GDB commands that normally print messages to say what they are doing 16324 omit the messages when used in a user-defined command. 16325 16326 16327 File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences 16328 16329 23.1.2 User-defined Command Hooks 16330 --------------------------------- 16331 16332 You may define "hooks", which are a special kind of user-defined 16333 command. Whenever you run the command `foo', if the user-defined 16334 command `hook-foo' exists, it is executed (with no arguments) before 16335 that command. 16336 16337 A hook may also be defined which is run after the command you 16338 executed. Whenever you run the command `foo', if the user-defined 16339 command `hookpost-foo' exists, it is executed (with no arguments) after 16340 that command. Post-execution hooks may exist simultaneously with 16341 pre-execution hooks, for the same command. 16342 16343 It is valid for a hook to call the command which it hooks. If this 16344 occurs, the hook is not re-executed, thereby avoiding infinite 16345 recursion. 16346 16347 In addition, a pseudo-command, `stop' exists. Defining 16348 (`hook-stop') makes the associated commands execute every time 16349 execution stops in your program: before breakpoint commands are run, 16350 displays are printed, or the stack frame is printed. 16351 16352 For example, to ignore `SIGALRM' signals while single-stepping, but 16353 treat them normally during normal execution, you could define: 16354 16355 define hook-stop 16356 handle SIGALRM nopass 16357 end 16358 16359 define hook-run 16360 handle SIGALRM pass 16361 end 16362 16363 define hook-continue 16364 handle SIGALRM pass 16365 end 16366 16367 As a further example, to hook at the beginning and end of the `echo' 16368 command, and to add extra text to the beginning and end of the message, 16369 you could define: 16370 16371 define hook-echo 16372 echo <<<--- 16373 end 16374 16375 define hookpost-echo 16376 echo --->>>\n 16377 end 16378 16379 (gdb) echo Hello World 16380 <<<---Hello World--->>> 16381 (gdb) 16382 16383 You can define a hook for any single-word command in GDB, but not 16384 for command aliases; you should define a hook for the basic command 16385 name, e.g. `backtrace' rather than `bt'. You can hook a multi-word 16386 command by adding `hook-' or `hookpost-' to the last word of the 16387 command, e.g. `define target hook-remote' to add a hook to `target 16388 remote'. 16389 16390 If an error occurs during the execution of your hook, execution of 16391 GDB commands stops and GDB issues a prompt (before the command that you 16392 actually typed had a chance to run). 16393 16394 If you try to define a hook which does not match any known command, 16395 you get a warning from the `define' command. 16396 16397 16398 File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences 16399 16400 23.1.3 Command Files 16401 -------------------- 16402 16403 A command file for GDB is a text file made of lines that are GDB 16404 commands. Comments (lines starting with `#') may also be included. An 16405 empty line in a command file does nothing; it does not mean to repeat 16406 the last command, as it would from the terminal. 16407 16408 You can request the execution of a command file with the `source' 16409 command. Note that the `source' command is also used to evaluate 16410 scripts that are not Command Files. The exact behavior can be 16411 configured using the `script-extension' setting. *Note Extending GDB: 16412 Extending GDB. 16413 16414 `source [`-v'] FILENAME' 16415 Execute the command file FILENAME. 16416 16417 The lines in a command file are generally executed sequentially, 16418 unless the order of execution is changed by one of the _flow-control 16419 commands_ described below. The commands are not printed as they are 16420 executed. An error in any command terminates execution of the command 16421 file and control is returned to the console. 16422 16423 GDB searches for FILENAME in the current directory and then on the 16424 search path (specified with the `directory' command). 16425 16426 If `-v', for verbose mode, is given then GDB displays each command 16427 as it is executed. The option must be given before FILENAME, and is 16428 interpreted as part of the filename anywhere else. 16429 16430 Commands that would ask for confirmation if used interactively 16431 proceed without asking when used in a command file. Many GDB commands 16432 that normally print messages to say what they are doing omit the 16433 messages when called from command files. 16434 16435 GDB also accepts command input from standard input. In this mode, 16436 normal output goes to standard output and error output goes to standard 16437 error. Errors in a command file supplied on standard input do not 16438 terminate execution of the command file--execution continues with the 16439 next command. 16440 16441 gdb < cmds > log 2>&1 16442 16443 (The syntax above will vary depending on the shell used.) This 16444 example will execute commands from the file `cmds'. All output and 16445 errors would be directed to `log'. 16446 16447 Since commands stored on command files tend to be more general than 16448 commands typed interactively, they frequently need to deal with 16449 complicated situations, such as different or unexpected values of 16450 variables and symbols, changes in how the program being debugged is 16451 built, etc. GDB provides a set of flow-control commands to deal with 16452 these complexities. Using these commands, you can write complex 16453 scripts that loop over data structures, execute commands conditionally, 16454 etc. 16455 16456 `if' 16457 `else' 16458 This command allows to include in your script conditionally 16459 executed commands. The `if' command takes a single argument, which 16460 is an expression to evaluate. It is followed by a series of 16461 commands that are executed only if the expression is true (its 16462 value is nonzero). There can then optionally be an `else' line, 16463 followed by a series of commands that are only executed if the 16464 expression was false. The end of the list is marked by a line 16465 containing `end'. 16466 16467 `while' 16468 This command allows to write loops. Its syntax is similar to 16469 `if': the command takes a single argument, which is an expression 16470 to evaluate, and must be followed by the commands to execute, one 16471 per line, terminated by an `end'. These commands are called the 16472 "body" of the loop. The commands in the body of `while' are 16473 executed repeatedly as long as the expression evaluates to true. 16474 16475 `loop_break' 16476 This command exits the `while' loop in whose body it is included. 16477 Execution of the script continues after that `while's `end' line. 16478 16479 `loop_continue' 16480 This command skips the execution of the rest of the body of 16481 commands in the `while' loop in whose body it is included. 16482 Execution branches to the beginning of the `while' loop, where it 16483 evaluates the controlling expression. 16484 16485 `end' 16486 Terminate the block of commands that are the body of `if', `else', 16487 or `while' flow-control commands. 16488 16489 16490 File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences 16491 16492 23.1.4 Commands for Controlled Output 16493 ------------------------------------- 16494 16495 During the execution of a command file or a user-defined command, normal 16496 GDB output is suppressed; the only output that appears is what is 16497 explicitly printed by the commands in the definition. This section 16498 describes three commands useful for generating exactly the output you 16499 want. 16500 16501 `echo TEXT' 16502 Print TEXT. Nonprinting characters can be included in TEXT using 16503 C escape sequences, such as `\n' to print a newline. *No newline 16504 is printed unless you specify one.* In addition to the standard C 16505 escape sequences, a backslash followed by a space stands for a 16506 space. This is useful for displaying a string with spaces at the 16507 beginning or the end, since leading and trailing spaces are 16508 otherwise trimmed from all arguments. To print ` and foo = ', use 16509 the command `echo \ and foo = \ '. 16510 16511 A backslash at the end of TEXT can be used, as in C, to continue 16512 the command onto subsequent lines. For example, 16513 16514 echo This is some text\n\ 16515 which is continued\n\ 16516 onto several lines.\n 16517 16518 produces the same output as 16519 16520 echo This is some text\n 16521 echo which is continued\n 16522 echo onto several lines.\n 16523 16524 `output EXPRESSION' 16525 Print the value of EXPRESSION and nothing but that value: no 16526 newlines, no `$NN = '. The value is not entered in the value 16527 history either. *Note Expressions: Expressions, for more 16528 information on expressions. 16529 16530 `output/FMT EXPRESSION' 16531 Print the value of EXPRESSION in format FMT. You can use the same 16532 formats as for `print'. *Note Output Formats: Output Formats, for 16533 more information. 16534 16535 `printf TEMPLATE, EXPRESSIONS...' 16536 Print the values of one or more EXPRESSIONS under the control of 16537 the string TEMPLATE. To print several values, make EXPRESSIONS be 16538 a comma-separated list of individual expressions, which may be 16539 either numbers or pointers. Their values are printed as specified 16540 by TEMPLATE, exactly as a C program would do by executing the code 16541 below: 16542 16543 printf (TEMPLATE, EXPRESSIONS...); 16544 16545 As in `C' `printf', ordinary characters in TEMPLATE are printed 16546 verbatim, while "conversion specification" introduced by the `%' 16547 character cause subsequent EXPRESSIONS to be evaluated, their 16548 values converted and formatted according to type and style 16549 information encoded in the conversion specifications, and then 16550 printed. 16551 16552 For example, you can print two values in hex like this: 16553 16554 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 16555 16556 `printf' supports all the standard `C' conversion specifications, 16557 including the flags and modifiers between the `%' character and 16558 the conversion letter, with the following exceptions: 16559 16560 * The argument-ordering modifiers, such as `2$', are not 16561 supported. 16562 16563 * The modifier `*' is not supported for specifying precision or 16564 width. 16565 16566 * The `'' flag (for separation of digits into groups according 16567 to `LC_NUMERIC'') is not supported. 16568 16569 * The type modifiers `hh', `j', `t', and `z' are not supported. 16570 16571 * The conversion letter `n' (as in `%n') is not supported. 16572 16573 * The conversion letters `a' and `A' are not supported. 16574 16575 Note that the `ll' type modifier is supported only if the 16576 underlying `C' implementation used to build GDB supports the `long 16577 long int' type, and the `L' type modifier is supported only if 16578 `long double' type is available. 16579 16580 As in `C', `printf' supports simple backslash-escape sequences, 16581 such as `\n', `\t', `\\', `\"', `\a', and `\f', that consist of 16582 backslash followed by a single character. Octal and hexadecimal 16583 escape sequences are not supported. 16584 16585 Additionally, `printf' supports conversion specifications for DFP 16586 ("Decimal Floating Point") types using the following length 16587 modifiers together with a floating point specifier. letters: 16588 16589 * `H' for printing `Decimal32' types. 16590 16591 * `D' for printing `Decimal64' types. 16592 16593 * `DD' for printing `Decimal128' types. 16594 16595 If the underlying `C' implementation used to build GDB has support 16596 for the three length modifiers for DFP types, other modifiers such 16597 as width and precision will also be available for GDB to use. 16598 16599 In case there is no such `C' support, no additional modifiers will 16600 be available and the value will be printed in the standard way. 16601 16602 Here's an example of printing DFP types using the above conversion 16603 letters: 16604 printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl 16605 16606 16607 16608 File: gdb.info, Node: Python, Prev: Sequences, Up: Extending GDB 16609 16610 23.2 Scripting GDB using Python 16611 =============================== 16612 16613 You can script GDB using the Python programming language 16614 (http://www.python.org/). This feature is available only if GDB was 16615 configured using `--with-python'. 16616 16617 * Menu: 16618 16619 * Python Commands:: Accessing Python from GDB. 16620 * Python API:: Accessing GDB from Python. 16621 16622 16623 File: gdb.info, Node: Python Commands, Next: Python API, Up: Python 16624 16625 23.2.1 Python Commands 16626 ---------------------- 16627 16628 GDB provides one command for accessing the Python interpreter, and one 16629 related setting: 16630 16631 `python [CODE]' 16632 The `python' command can be used to evaluate Python code. 16633 16634 If given an argument, the `python' command will evaluate the 16635 argument as a Python command. For example: 16636 16637 (gdb) python print 23 16638 23 16639 16640 If you do not provide an argument to `python', it will act as a 16641 multi-line command, like `define'. In this case, the Python 16642 script is made up of subsequent command lines, given after the 16643 `python' command. This command list is terminated using a line 16644 containing `end'. For example: 16645 16646 (gdb) python 16647 Type python script 16648 End with a line saying just "end". 16649 >print 23 16650 >end 16651 23 16652 16653 `maint set python print-stack' 16654 By default, GDB will print a stack trace when an error occurs in a 16655 Python script. This can be controlled using `maint set python 16656 print-stack': if `on', the default, then Python stack printing is 16657 enabled; if `off', then Python stack printing is disabled. 16658 16659 It is also possible to execute a Python script from the GDB 16660 interpreter: 16661 16662 `source `script-name'' 16663 The script name must end with `.py' and GDB must be configured to 16664 recognize the script language based on filename extension using 16665 the `script-extension' setting. *Note Extending GDB: Extending 16666 GDB. 16667 16668 `python execfile ("script-name")' 16669 This method is based on the `execfile' Python built-in function, 16670 and thus is always available. 16671 16672 16673 File: gdb.info, Node: Python API, Prev: Python Commands, Up: Python 16674 16675 23.2.2 Python API 16676 ----------------- 16677 16678 At startup, GDB overrides Python's `sys.stdout' and `sys.stderr' to 16679 print using GDB's output-paging streams. A Python program which 16680 outputs to one of these streams may have its output interrupted by the 16681 user (*note Screen Size::). In this situation, a Python 16682 `KeyboardInterrupt' exception is thrown. 16683 16684 * Menu: 16685 16686 * Basic Python:: Basic Python Functions. 16687 * Exception Handling:: 16688 * Auto-loading:: Automatically loading Python code. 16689 * Values From Inferior:: 16690 * Types In Python:: Python representation of types. 16691 * Pretty Printing:: Pretty-printing values. 16692 * Selecting Pretty-Printers:: How GDB chooses a pretty-printer. 16693 * Commands In Python:: Implementing new commands in Python. 16694 * Functions In Python:: Writing new convenience functions. 16695 * Objfiles In Python:: Object files. 16696 * Frames In Python:: Acessing inferior stack frames from Python. 16697 * Lazy Strings In Python:: Python representation of lazy strings. 16698 16699 16700 File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API 16701 16702 23.2.2.1 Basic Python 16703 ..................... 16704 16705 GDB introduces a new Python module, named `gdb'. All methods and 16706 classes added by GDB are placed in this module. GDB automatically 16707 `import's the `gdb' module for use in all scripts evaluated by the 16708 `python' command. 16709 16710 -- Function: execute command [from_tty] 16711 Evaluate COMMAND, a string, as a GDB CLI command. If a GDB 16712 exception happens while COMMAND runs, it is translated as 16713 described in *Note Exception Handling: Exception Handling. If no 16714 exceptions occur, this function returns `None'. 16715 16716 FROM_TTY specifies whether GDB ought to consider this command as 16717 having originated from the user invoking it interactively. It 16718 must be a boolean value. If omitted, it defaults to `False'. 16719 16720 -- Function: parameter parameter 16721 Return the value of a GDB parameter. PARAMETER is a string naming 16722 the parameter to look up; PARAMETER may contain spaces if the 16723 parameter has a multi-part name. For example, `print object' is a 16724 valid parameter name. 16725 16726 If the named parameter does not exist, this function throws a 16727 `RuntimeError'. Otherwise, the parameter's value is converted to 16728 a Python value of the appropriate type, and returned. 16729 16730 -- Function: history number 16731 Return a value from GDB's value history (*note Value History::). 16732 NUMBER indicates which history element to return. If NUMBER is 16733 negative, then GDB will take its absolute value and count backward 16734 from the last element (i.e., the most recent element) to find the 16735 value to return. If NUMBER is zero, then GDB will return the most 16736 recent element. If the element specified by NUMBER doesn't exist 16737 in the value history, a `RuntimeError' exception will be raised. 16738 16739 If no exception is raised, the return value is always an instance 16740 of `gdb.Value' (*note Values From Inferior::). 16741 16742 -- Function: parse_and_eval expression 16743 Parse EXPRESSION as an expression in the current language, 16744 evaluate it, and return the result as a `gdb.Value'. EXPRESSION 16745 must be a string. 16746 16747 This function can be useful when implementing a new command (*note 16748 Commands In Python::), as it provides a way to parse the command's 16749 argument as an expression. It is also useful simply to compute 16750 values, for example, it is the only way to get the value of a 16751 convenience variable (*note Convenience Vars::) as a `gdb.Value'. 16752 16753 -- Function: write string 16754 Print a string to GDB's paginated standard output stream. Writing 16755 to `sys.stdout' or `sys.stderr' will automatically call this 16756 function. 16757 16758 -- Function: flush 16759 Flush GDB's paginated standard output stream. Flushing 16760 `sys.stdout' or `sys.stderr' will automatically call this function. 16761 16762 16763 File: gdb.info, Node: Exception Handling, Next: Auto-loading, Prev: Basic Python, Up: Python API 16764 16765 23.2.2.2 Exception Handling 16766 ........................... 16767 16768 When executing the `python' command, Python exceptions uncaught within 16769 the Python code are translated to calls to GDB error-reporting 16770 mechanism. If the command that called `python' does not handle the 16771 error, GDB will terminate it and print an error message containing the 16772 Python exception name, the associated value, and the Python call stack 16773 backtrace at the point where the exception was raised. Example: 16774 16775 (gdb) python print foo 16776 Traceback (most recent call last): 16777 File "<string>", line 1, in <module> 16778 NameError: name 'foo' is not defined 16779 16780 GDB errors that happen in GDB commands invoked by Python code are 16781 converted to Python `RuntimeError' exceptions. User interrupt (via 16782 `C-c' or by typing `q' at a pagination prompt) is translated to a 16783 Python `KeyboardInterrupt' exception. If you catch these exceptions in 16784 your Python code, your exception handler will see `RuntimeError' or 16785 `KeyboardInterrupt' as the exception type, the GDB error message as its 16786 value, and the Python call stack backtrace at the Python statement 16787 closest to where the GDB error occured as the traceback. 16788 16789 16790 File: gdb.info, Node: Auto-loading, Next: Values From Inferior, Prev: Exception Handling, Up: Python API 16791 16792 23.2.2.3 Auto-loading 16793 ..................... 16794 16795 When a new object file is read (for example, due to the `file' command, 16796 or because the inferior has loaded a shared library), GDB will look for 16797 a file named `OBJFILE-gdb.py', where OBJFILE is the object file's real 16798 name, formed by ensuring that the file name is absolute, following all 16799 symlinks, and resolving `.' and `..' components. If this file exists 16800 and is readable, GDB will evaluate it as a Python script. 16801 16802 If this file does not exist, and if the parameter 16803 `debug-file-directory' is set (*note Separate Debug Files::), then GDB 16804 will use for its each separated directory component `component' the 16805 file named ``component'/REAL-NAME', where REAL-NAME is the object 16806 file's real name, as described above. 16807 16808 Finally, if this file does not exist, then GDB will look for a file 16809 named `DATA-DIRECTORY/python/auto-load/REAL-NAME', where DATA-DIRECTORY 16810 is GDB's data directory (available via `show data-directory', *note 16811 Data Files::), and REAL-NAME is the object file's real name, as 16812 described above. 16813 16814 When reading an auto-loaded file, GDB sets the "current objfile". 16815 This is available via the `gdb.current_objfile' function (*note 16816 Objfiles In Python::). This can be useful for registering 16817 objfile-specific pretty-printers. 16818 16819 The auto-loading feature is useful for supplying application-specific 16820 debugging commands and scripts. You can enable or disable this 16821 feature, and view its current state. 16822 16823 `maint set python auto-load [yes|no]' 16824 Enable or disable the Python auto-loading feature. 16825 16826 `show python auto-load' 16827 Show whether Python auto-loading is enabled or disabled. 16828 16829 GDB does not track which files it has already auto-loaded. So, your 16830 `-gdb.py' file should take care to ensure that it may be evaluated 16831 multiple times without error. 16832 16833 16834 File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Auto-loading, Up: Python API 16835 16836 23.2.2.4 Values From Inferior 16837 ............................. 16838 16839 GDB provides values it obtains from the inferior program in an object 16840 of type `gdb.Value'. GDB uses this object for its internal bookkeeping 16841 of the inferior's values, and for fetching values when necessary. 16842 16843 Inferior values that are simple scalars can be used directly in 16844 Python expressions that are valid for the value's data type. Here's an 16845 example for an integer or floating-point value `some_val': 16846 16847 bar = some_val + 2 16848 16849 As result of this, `bar' will also be a `gdb.Value' object whose values 16850 are of the same type as those of `some_val'. 16851 16852 Inferior values that are structures or instances of some class can 16853 be accessed using the Python "dictionary syntax". For example, if 16854 `some_val' is a `gdb.Value' instance holding a structure, you can 16855 access its `foo' element with: 16856 16857 bar = some_val['foo'] 16858 16859 Again, `bar' will also be a `gdb.Value' object. 16860 16861 The following attributes are provided: 16862 16863 -- Instance Variable of Value: address 16864 If this object is addressable, this read-only attribute holds 16865 a `gdb.Value' object representing the address. Otherwise, 16866 this attribute holds `None'. 16867 16868 -- Instance Variable of Value: is_optimized_out 16869 This read-only boolean attribute is true if the compiler 16870 optimized out this value, thus it is not available for 16871 fetching from the inferior. 16872 16873 -- Instance Variable of Value: type 16874 The type of this `gdb.Value'. The value of this attribute is 16875 a `gdb.Type' object. 16876 16877 The following methods are provided: 16878 16879 -- Method on Value: cast type 16880 Return a new instance of `gdb.Value' that is the result of 16881 casting this instance to the type described by TYPE, which 16882 must be a `gdb.Type' object. If the cast cannot be performed 16883 for some reason, this method throws an exception. 16884 16885 -- Method on Value: dereference 16886 For pointer data types, this method returns a new `gdb.Value' 16887 object whose contents is the object pointed to by the 16888 pointer. For example, if `foo' is a C pointer to an `int', 16889 declared in your C program as 16890 16891 int *foo; 16892 16893 then you can use the corresponding `gdb.Value' to access what 16894 `foo' points to like this: 16895 16896 bar = foo.dereference () 16897 16898 The result `bar' will be a `gdb.Value' object holding the 16899 value pointed to by `foo'. 16900 16901 -- Method on Value: string [encoding] [errors] [length] 16902 If this `gdb.Value' represents a string, then this method 16903 converts the contents to a Python string. Otherwise, this 16904 method will throw an exception. 16905 16906 Strings are recognized in a language-specific way; whether a 16907 given `gdb.Value' represents a string is determined by the 16908 current language. 16909 16910 For C-like languages, a value is a string if it is a pointer 16911 to or an array of characters or ints. The string is assumed 16912 to be terminated by a zero of the appropriate width. However 16913 if the optional length argument is given, the string will be 16914 converted to that given length, ignoring any embedded zeros 16915 that the string may contain. 16916 16917 If the optional ENCODING argument is given, it must be a 16918 string naming the encoding of the string in the `gdb.Value', 16919 such as `"ascii"', `"iso-8859-6"' or `"utf-8"'. It accepts 16920 the same encodings as the corresponding argument to Python's 16921 `string.decode' method, and the Python codec machinery will 16922 be used to convert the string. If ENCODING is not given, or 16923 if ENCODING is the empty string, then either the 16924 `target-charset' (*note Character Sets::) will be used, or a 16925 language-specific encoding will be used, if the current 16926 language is able to supply one. 16927 16928 The optional ERRORS argument is the same as the corresponding 16929 argument to Python's `string.decode' method. 16930 16931 If the optional LENGTH argument is given, the string will be 16932 fetched and converted to the given length. 16933 16934 -- Method on Value: lazy_string [encoding] [length] 16935 If this `gdb.Value' represents a string, then this method 16936 converts the contents to a `gdb.LazyString' (*note Lazy 16937 Strings In Python::). Otherwise, this method will throw an 16938 exception. 16939 16940 If the optional ENCODING argument is given, it must be a 16941 string naming the encoding of the `gdb.LazyString'. Some 16942 examples are: `ascii', `iso-8859-6' or `utf-8'. If the 16943 ENCODING argument is an encoding that GDB does recognize, GDB 16944 will raise an error. 16945 16946 When a lazy string is printed, the GDB encoding machinery is 16947 used to convert the string during printing. If the optional 16948 ENCODING argument is not provided, or is an empty string, GDB 16949 will automatically select the encoding most suitable for the 16950 string type. For further information on encoding in GDB 16951 please see *Note Character Sets::. 16952 16953 If the optional LENGTH argument is given, the string will be 16954 fetched and encoded to the length of characters specified. If 16955 the LENGTH argument is not provided, the string will be 16956 fetched and encoded until a null of appropriate width is 16957 found. 16958 16959 16960 File: gdb.info, Node: Types In Python, Next: Pretty Printing, Prev: Values From Inferior, Up: Python API 16961 16962 23.2.2.5 Types In Python 16963 ........................ 16964 16965 GDB represents types from the inferior using the class `gdb.Type'. 16966 16967 The following type-related functions are available in the `gdb' 16968 module: 16969 16970 -- Function: lookup_type name [block] 16971 This function looks up a type by name. NAME is the name of the 16972 type to look up. It must be a string. 16973 16974 Ordinarily, this function will return an instance of `gdb.Type'. 16975 If the named type cannot be found, it will throw an exception. 16976 16977 An instance of `Type' has the following attributes: 16978 16979 -- Instance Variable of Type: code 16980 The type code for this type. The type code will be one of the 16981 `TYPE_CODE_' constants defined below. 16982 16983 -- Instance Variable of Type: sizeof 16984 The size of this type, in target `char' units. Usually, a 16985 target's `char' type will be an 8-bit byte. However, on some 16986 unusual platforms, this type may have a different size. 16987 16988 -- Instance Variable of Type: tag 16989 The tag name for this type. The tag name is the name after 16990 `struct', `union', or `enum' in C and C++; not all languages 16991 have this concept. If this type has no tag name, then `None' 16992 is returned. 16993 16994 The following methods are provided: 16995 16996 -- Method on Type: fields 16997 For structure and union types, this method returns the 16998 fields. Range types have two fields, the minimum and maximum 16999 values. Enum types have one field per enum constant. 17000 Function and method types have one field per parameter. The 17001 base types of C++ classes are also represented as fields. If 17002 the type has no fields, or does not fit into one of these 17003 categories, an empty sequence will be returned. 17004 17005 Each field is an object, with some pre-defined attributes: 17006 `bitpos' 17007 This attribute is not available for `static' fields (as 17008 in C++ or Java). For non-`static' fields, the value is 17009 the bit position of the field. 17010 17011 `name' 17012 The name of the field, or `None' for anonymous fields. 17013 17014 `artificial' 17015 This is `True' if the field is artificial, usually 17016 meaning that it was provided by the compiler and not the 17017 user. This attribute is always provided, and is `False' 17018 if the field is not artificial. 17019 17020 `is_base_class' 17021 This is `True' if the field represents a base class of a 17022 C++ structure. This attribute is always provided, and 17023 is `False' if the field is not a base class of the type 17024 that is the argument of `fields', or if that type was 17025 not a C++ class. 17026 17027 `bitsize' 17028 If the field is packed, or is a bitfield, then this will 17029 have a non-zero value, which is the size of the field in 17030 bits. Otherwise, this will be zero; in this case the 17031 field's size is given by its type. 17032 17033 `type' 17034 The type of the field. This is usually an instance of 17035 `Type', but it can be `None' in some situations. 17036 17037 -- Method on Type: const 17038 Return a new `gdb.Type' object which represents a 17039 `const'-qualified variant of this type. 17040 17041 -- Method on Type: volatile 17042 Return a new `gdb.Type' object which represents a 17043 `volatile'-qualified variant of this type. 17044 17045 -- Method on Type: unqualified 17046 Return a new `gdb.Type' object which represents an unqualified 17047 variant of this type. That is, the result is neither `const' 17048 nor `volatile'. 17049 17050 -- Method on Type: range 17051 Return a Python `Tuple' object that contains two elements: the 17052 low bound of the argument type and the high bound of that 17053 type. If the type does not have a range, GDB will raise a 17054 `RuntimeError' exception. 17055 17056 -- Method on Type: reference 17057 Return a new `gdb.Type' object which represents a reference 17058 to this type. 17059 17060 -- Method on Type: pointer 17061 Return a new `gdb.Type' object which represents a pointer to 17062 this type. 17063 17064 -- Method on Type: strip_typedefs 17065 Return a new `gdb.Type' that represents the real type, after 17066 removing all layers of typedefs. 17067 17068 -- Method on Type: target 17069 Return a new `gdb.Type' object which represents the target 17070 type of this type. 17071 17072 For a pointer type, the target type is the type of the 17073 pointed-to object. For an array type (meaning C-like 17074 arrays), the target type is the type of the elements of the 17075 array. For a function or method type, the target type is the 17076 type of the return value. For a complex type, the target 17077 type is the type of the elements. For a typedef, the target 17078 type is the aliased type. 17079 17080 If the type does not have a target, this method will throw an 17081 exception. 17082 17083 -- Method on Type: template_argument n 17084 If this `gdb.Type' is an instantiation of a template, this 17085 will return a new `gdb.Type' which represents the type of the 17086 Nth template argument. 17087 17088 If this `gdb.Type' is not a template type, this will throw an 17089 exception. Ordinarily, only C++ code will have template 17090 types. 17091 17092 NAME is searched for globally. 17093 17094 Each type has a code, which indicates what category this type falls 17095 into. The available type categories are represented by constants 17096 defined in the `gdb' module: 17097 17098 `TYPE_CODE_PTR' 17099 The type is a pointer. 17100 17101 `TYPE_CODE_ARRAY' 17102 The type is an array. 17103 17104 `TYPE_CODE_STRUCT' 17105 The type is a structure. 17106 17107 `TYPE_CODE_UNION' 17108 The type is a union. 17109 17110 `TYPE_CODE_ENUM' 17111 The type is an enum. 17112 17113 `TYPE_CODE_FLAGS' 17114 A bit flags type, used for things such as status registers. 17115 17116 `TYPE_CODE_FUNC' 17117 The type is a function. 17118 17119 `TYPE_CODE_INT' 17120 The type is an integer type. 17121 17122 `TYPE_CODE_FLT' 17123 A floating point type. 17124 17125 `TYPE_CODE_VOID' 17126 The special type `void'. 17127 17128 `TYPE_CODE_SET' 17129 A Pascal set type. 17130 17131 `TYPE_CODE_RANGE' 17132 A range type, that is, an integer type with bounds. 17133 17134 `TYPE_CODE_STRING' 17135 A string type. Note that this is only used for certain languages 17136 with language-defined string types; C strings are not represented 17137 this way. 17138 17139 `TYPE_CODE_BITSTRING' 17140 A string of bits. 17141 17142 `TYPE_CODE_ERROR' 17143 An unknown or erroneous type. 17144 17145 `TYPE_CODE_METHOD' 17146 A method type, as found in C++ or Java. 17147 17148 `TYPE_CODE_METHODPTR' 17149 A pointer-to-member-function. 17150 17151 `TYPE_CODE_MEMBERPTR' 17152 A pointer-to-member. 17153 17154 `TYPE_CODE_REF' 17155 A reference type. 17156 17157 `TYPE_CODE_CHAR' 17158 A character type. 17159 17160 `TYPE_CODE_BOOL' 17161 A boolean type. 17162 17163 `TYPE_CODE_COMPLEX' 17164 A complex float type. 17165 17166 `TYPE_CODE_TYPEDEF' 17167 A typedef to some other type. 17168 17169 `TYPE_CODE_NAMESPACE' 17170 A C++ namespace. 17171 17172 `TYPE_CODE_DECFLOAT' 17173 A decimal floating point type. 17174 17175 `TYPE_CODE_INTERNAL_FUNCTION' 17176 A function internal to GDB. This is the type used to represent 17177 convenience functions. 17178 17179 17180 File: gdb.info, Node: Pretty Printing, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API 17181 17182 23.2.2.6 Pretty Printing 17183 ........................ 17184 17185 GDB provides a mechanism to allow pretty-printing of values using 17186 Python code. The pretty-printer API allows application-specific code 17187 to greatly simplify the display of complex objects. This mechanism 17188 works for both MI and the CLI. 17189 17190 For example, here is how a C++ `std::string' looks without a 17191 pretty-printer: 17192 17193 (gdb) print s 17194 $1 = { 17195 static npos = 4294967295, 17196 _M_dataplus = { 17197 <std::allocator<char>> = { 17198 <__gnu_cxx::new_allocator<char>> = {<No data fields>}, <No data fields>}, 17199 members of std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_Alloc_hider: 17200 _M_p = 0x804a014 "abcd" 17201 } 17202 } 17203 17204 After a pretty-printer for `std::string' has been installed, only 17205 the contents are printed: 17206 17207 (gdb) print s 17208 $2 = "abcd" 17209 17210 A pretty-printer is just an object that holds a value and implements 17211 a specific interface, defined here. 17212 17213 -- Operation on pretty printer: children (self) 17214 GDB will call this method on a pretty-printer to compute the 17215 children of the pretty-printer's value. 17216 17217 This method must return an object conforming to the Python iterator 17218 protocol. Each item returned by the iterator must be a tuple 17219 holding two elements. The first element is the "name" of the 17220 child; the second element is the child's value. The value can be 17221 any Python object which is convertible to a GDB value. 17222 17223 This method is optional. If it does not exist, GDB will act as 17224 though the value has no children. 17225 17226 -- Operation on pretty printer: display_hint (self) 17227 The CLI may call this method and use its result to change the 17228 formatting of a value. The result will also be supplied to an MI 17229 consumer as a `displayhint' attribute of the variable being 17230 printed. 17231 17232 This method is optional. If it does exist, this method must 17233 return a string. 17234 17235 Some display hints are predefined by GDB: 17236 17237 `array' 17238 Indicate that the object being printed is "array-like". The 17239 CLI uses this to respect parameters such as `set print 17240 elements' and `set print array'. 17241 17242 `map' 17243 Indicate that the object being printed is "map-like", and 17244 that the children of this value can be assumed to alternate 17245 between keys and values. 17246 17247 `string' 17248 Indicate that the object being printed is "string-like". If 17249 the printer's `to_string' method returns a Python string of 17250 some kind, then GDB will call its internal language-specific 17251 string-printing function to format the string. For the CLI 17252 this means adding quotation marks, possibly escaping some 17253 characters, respecting `set print elements', and the like. 17254 17255 -- Operation on pretty printer: to_string (self) 17256 GDB will call this method to display the string representation of 17257 the value passed to the object's constructor. 17258 17259 When printing from the CLI, if the `to_string' method exists, then 17260 GDB will prepend its result to the values returned by `children'. 17261 Exactly how this formatting is done is dependent on the display 17262 hint, and may change as more hints are added. Also, depending on 17263 the print settings (*note Print Settings::), the CLI may print 17264 just the result of `to_string' in a stack trace, omitting the 17265 result of `children'. 17266 17267 If this method returns a string, it is printed verbatim. 17268 17269 Otherwise, if this method returns an instance of `gdb.Value', then 17270 GDB prints this value. This may result in a call to another 17271 pretty-printer. 17272 17273 If instead the method returns a Python value which is convertible 17274 to a `gdb.Value', then GDB performs the conversion and prints the 17275 resulting value. Again, this may result in a call to another 17276 pretty-printer. Python scalars (integers, floats, and booleans) 17277 and strings are convertible to `gdb.Value'; other types are not. 17278 17279 If the result is not one of these types, an exception is raised. 17280 17281 17282 File: gdb.info, Node: Selecting Pretty-Printers, Next: Commands In Python, Prev: Pretty Printing, Up: Python API 17283 17284 23.2.2.7 Selecting Pretty-Printers 17285 .................................. 17286 17287 The Python list `gdb.pretty_printers' contains an array of functions 17288 that have been registered via addition as a pretty-printer. Each 17289 `gdb.Objfile' also contains a `pretty_printers' attribute. 17290 17291 A function on one of these lists is passed a single `gdb.Value' 17292 argument and should return a pretty-printer object conforming to the 17293 interface definition above (*note Pretty Printing::). If a function 17294 cannot create a pretty-printer for the value, it should return `None'. 17295 17296 GDB first checks the `pretty_printers' attribute of each 17297 `gdb.Objfile' and iteratively calls each function in the list for that 17298 `gdb.Objfile' until it receives a pretty-printer object. After these 17299 lists have been exhausted, it tries the global `gdb.pretty-printers' 17300 list, again calling each function until an object is returned. 17301 17302 The order in which the objfiles are searched is not specified. For a 17303 given list, functions are always invoked from the head of the list, and 17304 iterated over sequentially until the end of the list, or a printer 17305 object is returned. 17306 17307 Here is an example showing how a `std::string' printer might be 17308 written: 17309 17310 class StdStringPrinter: 17311 "Print a std::string" 17312 17313 def __init__ (self, val): 17314 self.val = val 17315 17316 def to_string (self): 17317 return self.val['_M_dataplus']['_M_p'] 17318 17319 def display_hint (self): 17320 return 'string' 17321 17322 And here is an example showing how a lookup function for the printer 17323 example above might be written. 17324 17325 def str_lookup_function (val): 17326 17327 lookup_tag = val.type.tag 17328 regex = re.compile ("^std::basic_string<char,.*>$") 17329 if lookup_tag == None: 17330 return None 17331 if regex.match (lookup_tag): 17332 return StdStringPrinter (val) 17333 17334 return None 17335 17336 The example lookup function extracts the value's type, and attempts 17337 to match it to a type that it can pretty-print. If it is a type the 17338 printer can pretty-print, it will return a printer object. If not, it 17339 returns `None'. 17340 17341 We recommend that you put your core pretty-printers into a Python 17342 package. If your pretty-printers are for use with a library, we 17343 further recommend embedding a version number into the package name. 17344 This practice will enable GDB to load multiple versions of your 17345 pretty-printers at the same time, because they will have different 17346 names. 17347 17348 You should write auto-loaded code (*note Auto-loading::) such that it 17349 can be evaluated multiple times without changing its meaning. An ideal 17350 auto-load file will consist solely of `import's of your printer 17351 modules, followed by a call to a register pretty-printers with the 17352 current objfile. 17353 17354 Taken as a whole, this approach will scale nicely to multiple 17355 inferiors, each potentially using a different library version. 17356 Embedding a version number in the Python package name will ensure that 17357 GDB is able to load both sets of printers simultaneously. Then, 17358 because the search for pretty-printers is done by objfile, and because 17359 your auto-loaded code took care to register your library's printers 17360 with a specific objfile, GDB will find the correct printers for the 17361 specific version of the library used by each inferior. 17362 17363 To continue the `std::string' example (*note Pretty Printing::), 17364 this code might appear in `gdb.libstdcxx.v6': 17365 17366 def register_printers (objfile): 17367 objfile.pretty_printers.add (str_lookup_function) 17368 17369 And then the corresponding contents of the auto-load file would be: 17370 17371 import gdb.libstdcxx.v6 17372 gdb.libstdcxx.v6.register_printers (gdb.current_objfile ()) 17373 17374 17375 File: gdb.info, Node: Commands In Python, Next: Functions In Python, Prev: Selecting Pretty-Printers, Up: Python API 17376 17377 23.2.2.8 Commands In Python 17378 ........................... 17379 17380 You can implement new GDB CLI commands in Python. A CLI command is 17381 implemented using an instance of the `gdb.Command' class, most commonly 17382 using a subclass. 17383 17384 -- Method on Command: __init__ name COMMAND_CLASS [COMPLETER_CLASS] 17385 [PREFIX] 17386 The object initializer for `Command' registers the new command 17387 with GDB. This initializer is normally invoked from the subclass' 17388 own `__init__' method. 17389 17390 NAME is the name of the command. If NAME consists of multiple 17391 words, then the initial words are looked for as prefix commands. 17392 In this case, if one of the prefix commands does not exist, an 17393 exception is raised. 17394 17395 There is no support for multi-line commands. 17396 17397 COMMAND_CLASS should be one of the `COMMAND_' constants defined 17398 below. This argument tells GDB how to categorize the new command 17399 in the help system. 17400 17401 COMPLETER_CLASS is an optional argument. If given, it should be 17402 one of the `COMPLETE_' constants defined below. This argument 17403 tells GDB how to perform completion for this command. If not 17404 given, GDB will attempt to complete using the object's `complete' 17405 method (see below); if no such method is found, an error will 17406 occur when completion is attempted. 17407 17408 PREFIX is an optional argument. If `True', then the new command 17409 is a prefix command; sub-commands of this command may be 17410 registered. 17411 17412 The help text for the new command is taken from the Python 17413 documentation string for the command's class, if there is one. If 17414 no documentation string is provided, the default value "This 17415 command is not documented." is used. 17416 17417 -- Method on Command: dont_repeat 17418 By default, a GDB command is repeated when the user enters a blank 17419 line at the command prompt. A command can suppress this behavior 17420 by invoking the `dont_repeat' method. This is similar to the user 17421 command `dont-repeat', see *Note dont-repeat: Define. 17422 17423 -- Method on Command: invoke argument from_tty 17424 This method is called by GDB when this command is invoked. 17425 17426 ARGUMENT is a string. It is the argument to the command, after 17427 leading and trailing whitespace has been stripped. 17428 17429 FROM_TTY is a boolean argument. When true, this means that the 17430 command was entered by the user at the terminal; when false it 17431 means that the command came from elsewhere. 17432 17433 If this method throws an exception, it is turned into a GDB 17434 `error' call. Otherwise, the return value is ignored. 17435 17436 -- Method on Command: complete text word 17437 This method is called by GDB when the user attempts completion on 17438 this command. All forms of completion are handled by this method, 17439 that is, the <TAB> and <M-?> key bindings (*note Completion::), 17440 and the `complete' command (*note complete: Help.). 17441 17442 The arguments TEXT and WORD are both strings. TEXT holds the 17443 complete command line up to the cursor's location. WORD holds the 17444 last word of the command line; this is computed using a 17445 word-breaking heuristic. 17446 17447 The `complete' method can return several values: 17448 * If the return value is a sequence, the contents of the 17449 sequence are used as the completions. It is up to `complete' 17450 to ensure that the contents actually do complete the word. A 17451 zero-length sequence is allowed, it means that there were no 17452 completions available. Only string elements of the sequence 17453 are used; other elements in the sequence are ignored. 17454 17455 * If the return value is one of the `COMPLETE_' constants 17456 defined below, then the corresponding GDB-internal completion 17457 function is invoked, and its result is used. 17458 17459 * All other results are treated as though there were no 17460 available completions. 17461 17462 When a new command is registered, it must be declared as a member of 17463 some general class of commands. This is used to classify top-level 17464 commands in the on-line help system; note that prefix commands are not 17465 listed under their own category but rather that of their top-level 17466 command. The available classifications are represented by constants 17467 defined in the `gdb' module: 17468 17469 `COMMAND_NONE' 17470 The command does not belong to any particular class. A command in 17471 this category will not be displayed in any of the help categories. 17472 17473 `COMMAND_RUNNING' 17474 The command is related to running the inferior. For example, 17475 `start', `step', and `continue' are in this category. Type `help 17476 running' at the GDB prompt to see a list of commands in this 17477 category. 17478 17479 `COMMAND_DATA' 17480 The command is related to data or variables. For example, `call', 17481 `find', and `print' are in this category. Type `help data' at the 17482 GDB prompt to see a list of commands in this category. 17483 17484 `COMMAND_STACK' 17485 The command has to do with manipulation of the stack. For example, 17486 `backtrace', `frame', and `return' are in this category. Type 17487 `help stack' at the GDB prompt to see a list of commands in this 17488 category. 17489 17490 `COMMAND_FILES' 17491 This class is used for file-related commands. For example, 17492 `file', `list' and `section' are in this category. Type `help 17493 files' at the GDB prompt to see a list of commands in this 17494 category. 17495 17496 `COMMAND_SUPPORT' 17497 This should be used for "support facilities", generally meaning 17498 things that are useful to the user when interacting with GDB, but 17499 not related to the state of the inferior. For example, `help', 17500 `make', and `shell' are in this category. Type `help support' at 17501 the GDB prompt to see a list of commands in this category. 17502 17503 `COMMAND_STATUS' 17504 The command is an `info'-related command, that is, related to the 17505 state of GDB itself. For example, `info', `macro', and `show' are 17506 in this category. Type `help status' at the GDB prompt to see a 17507 list of commands in this category. 17508 17509 `COMMAND_BREAKPOINTS' 17510 The command has to do with breakpoints. For example, `break', 17511 `clear', and `delete' are in this category. Type `help 17512 breakpoints' at the GDB prompt to see a list of commands in this 17513 category. 17514 17515 `COMMAND_TRACEPOINTS' 17516 The command has to do with tracepoints. For example, `trace', 17517 `actions', and `tfind' are in this category. Type `help 17518 tracepoints' at the GDB prompt to see a list of commands in this 17519 category. 17520 17521 `COMMAND_OBSCURE' 17522 The command is only used in unusual circumstances, or is not of 17523 general interest to users. For example, `checkpoint', `fork', and 17524 `stop' are in this category. Type `help obscure' at the GDB 17525 prompt to see a list of commands in this category. 17526 17527 `COMMAND_MAINTENANCE' 17528 The command is only useful to GDB maintainers. The `maintenance' 17529 and `flushregs' commands are in this category. Type `help 17530 internals' at the GDB prompt to see a list of commands in this 17531 category. 17532 17533 A new command can use a predefined completion function, either by 17534 specifying it via an argument at initialization, or by returning it 17535 from the `complete' method. These predefined completion constants are 17536 all defined in the `gdb' module: 17537 17538 `COMPLETE_NONE' 17539 This constant means that no completion should be done. 17540 17541 `COMPLETE_FILENAME' 17542 This constant means that filename completion should be performed. 17543 17544 `COMPLETE_LOCATION' 17545 This constant means that location completion should be done. 17546 *Note Specify Location::. 17547 17548 `COMPLETE_COMMAND' 17549 This constant means that completion should examine GDB command 17550 names. 17551 17552 `COMPLETE_SYMBOL' 17553 This constant means that completion should be done using symbol 17554 names as the source. 17555 17556 The following code snippet shows how a trivial CLI command can be 17557 implemented in Python: 17558 17559 class HelloWorld (gdb.Command): 17560 """Greet the whole world.""" 17561 17562 def __init__ (self): 17563 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) 17564 17565 def invoke (self, arg, from_tty): 17566 print "Hello, World!" 17567 17568 HelloWorld () 17569 17570 The last line instantiates the class, and is necessary to trigger the 17571 registration of the command with GDB. Depending on how the Python code 17572 is read into GDB, you may need to import the `gdb' module explicitly. 17573 17574 17575 File: gdb.info, Node: Functions In Python, Next: Objfiles In Python, Prev: Commands In Python, Up: Python API 17576 17577 23.2.2.9 Writing new convenience functions 17578 .......................................... 17579 17580 You can implement new convenience functions (*note Convenience Vars::) 17581 in Python. A convenience function is an instance of a subclass of the 17582 class `gdb.Function'. 17583 17584 -- Method on Function: __init__ name 17585 The initializer for `Function' registers the new function with 17586 GDB. The argument NAME is the name of the function, a string. 17587 The function will be visible to the user as a convenience variable 17588 of type `internal function', whose name is the same as the given 17589 NAME. 17590 17591 The documentation for the new function is taken from the 17592 documentation string for the new class. 17593 17594 -- Method on Function: invoke *ARGS 17595 When a convenience function is evaluated, its arguments are 17596 converted to instances of `gdb.Value', and then the function's 17597 `invoke' method is called. Note that GDB does not predetermine 17598 the arity of convenience functions. Instead, all available 17599 arguments are passed to `invoke', following the standard Python 17600 calling convention. In particular, a convenience function can 17601 have default values for parameters without ill effect. 17602 17603 The return value of this method is used as its value in the 17604 enclosing expression. If an ordinary Python value is returned, it 17605 is converted to a `gdb.Value' following the usual rules. 17606 17607 The following code snippet shows how a trivial convenience function 17608 can be implemented in Python: 17609 17610 class Greet (gdb.Function): 17611 """Return string to greet someone. 17612 Takes a name as argument.""" 17613 17614 def __init__ (self): 17615 super (Greet, self).__init__ ("greet") 17616 17617 def invoke (self, name): 17618 return "Hello, %s!" % name.string () 17619 17620 Greet () 17621 17622 The last line instantiates the class, and is necessary to trigger the 17623 registration of the function with GDB. Depending on how the Python 17624 code is read into GDB, you may need to import the `gdb' module 17625 explicitly. 17626 17627 17628 File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Functions In Python, Up: Python API 17629 17630 23.2.2.10 Objfiles In Python 17631 ............................ 17632 17633 GDB loads symbols for an inferior from various symbol-containing files 17634 (*note Files::). These include the primary executable file, any shared 17635 libraries used by the inferior, and any separate debug info files 17636 (*note Separate Debug Files::). GDB calls these symbol-containing 17637 files "objfiles". 17638 17639 The following objfile-related functions are available in the `gdb' 17640 module: 17641 17642 -- Function: current_objfile 17643 When auto-loading a Python script (*note Auto-loading::), GDB sets 17644 the "current objfile" to the corresponding objfile. This function 17645 returns the current objfile. If there is no current objfile, this 17646 function returns `None'. 17647 17648 -- Function: objfiles 17649 Return a sequence of all the objfiles current known to GDB. *Note 17650 Objfiles In Python::. 17651 17652 Each objfile is represented by an instance of the `gdb.Objfile' 17653 class. 17654 17655 -- Instance Variable of Objfile: filename 17656 The file name of the objfile as a string. 17657 17658 -- Instance Variable of Objfile: pretty_printers 17659 The `pretty_printers' attribute is a list of functions. It is 17660 used to look up pretty-printers. A `Value' is passed to each 17661 function in order; if the function returns `None', then the search 17662 continues. Otherwise, the return value should be an object which 17663 is used to format the value. *Note Pretty Printing::, for more 17664 information. 17665 17666 17667 File: gdb.info, Node: Frames In Python, Next: Lazy Strings In Python, Prev: Objfiles In Python, Up: Python API 17668 17669 23.2.2.11 Acessing inferior stack frames from Python. 17670 ..................................................... 17671 17672 When the debugged program stops, GDB is able to analyze its call stack 17673 (*note Stack frames: Frames.). The `gdb.Frame' class represents a 17674 frame in the stack. A `gdb.Frame' object is only valid while its 17675 corresponding frame exists in the inferior's stack. If you try to use 17676 an invalid frame object, GDB will throw a `RuntimeError' exception. 17677 17678 Two `gdb.Frame' objects can be compared for equality with the `==' 17679 operator, like: 17680 17681 (gdb) python print gdb.newest_frame() == gdb.selected_frame () 17682 True 17683 17684 The following frame-related functions are available in the `gdb' 17685 module: 17686 17687 -- Function: selected_frame 17688 Return the selected frame object. (*note Selecting a Frame: 17689 Selection.). 17690 17691 -- Function: frame_stop_reason_string reason 17692 Return a string explaining the reason why GDB stopped unwinding 17693 frames, as expressed by the given REASON code (an integer, see the 17694 `unwind_stop_reason' method further down in this section). 17695 17696 A `gdb.Frame' object has the following methods: 17697 17698 -- Method on Frame: is_valid 17699 Returns true if the `gdb.Frame' object is valid, false if not. 17700 A frame object can become invalid if the frame it refers to 17701 doesn't exist anymore in the inferior. All `gdb.Frame' 17702 methods will throw an exception if it is invalid at the time 17703 the method is called. 17704 17705 -- Method on Frame: name 17706 Returns the function name of the frame, or `None' if it can't 17707 be obtained. 17708 17709 -- Method on Frame: type 17710 Returns the type of the frame. The value can be one of 17711 `gdb.NORMAL_FRAME', `gdb.DUMMY_FRAME', `gdb.SIGTRAMP_FRAME' 17712 or `gdb.SENTINEL_FRAME'. 17713 17714 -- Method on Frame: unwind_stop_reason 17715 Return an integer representing the reason why it's not 17716 possible to find more frames toward the outermost frame. Use 17717 `gdb.frame_stop_reason_string' to convert the value returned 17718 by this function to a string. 17719 17720 -- Method on Frame: pc 17721 Returns the frame's resume address. 17722 17723 -- Method on Frame: older 17724 Return the frame that called this frame. 17725 17726 -- Method on Frame: newer 17727 Return the frame called by this frame. 17728 17729 -- Method on Frame: read_var variable 17730 Return the value of the given variable in this frame. 17731 VARIABLE must be a string. 17732 17733 17734 File: gdb.info, Node: Lazy Strings In Python, Prev: Frames In Python, Up: Python API 17735 17736 23.2.2.12 Python representation of lazy strings. 17737 ................................................ 17738 17739 A "lazy string" is a string whose contents is not retrieved or encoded 17740 until it is needed. 17741 17742 A `gdb.LazyString' is represented in GDB as an `address' that points 17743 to a region of memory, an `encoding' that will be used to encode that 17744 region of memory, and a `length' to delimit the region of memory that 17745 represents the string. The difference between a `gdb.LazyString' and a 17746 string wrapped within a `gdb.Value' is that a `gdb.LazyString' will be 17747 treated differently by GDB when printing. A `gdb.LazyString' is 17748 retrieved and encoded during printing, while a `gdb.Value' wrapping a 17749 string is immediately retrieved and encoded on creation. 17750 17751 A `gdb.LazyString' object has the following functions: 17752 17753 -- Method on LazyString: value 17754 Convert the `gdb.LazyString' to a `gdb.Value'. This value will 17755 point to the string in memory, but will lose all the delayed 17756 retrieval, encoding and handling that GDB applies to a 17757 `gdb.LazyString'. 17758 17759 -- Instance Variable of LazyString: address 17760 This attribute holds the address of the string. This attribute is 17761 not writable. 17762 17763 -- Instance Variable of LazyString: length 17764 This attribute holds the length of the string in characters. If 17765 the length is -1, then the string will be fetched and encoded up 17766 to the first null of appropriate width. This attribute is not 17767 writable. 17768 17769 -- Instance Variable of LazyString: encoding 17770 This attribute holds the encoding that will be applied to the 17771 string when the string is printed by GDB. If the encoding is not 17772 set, or contains an empty string, then GDB will select the most 17773 appropriate encoding when the string is printed. This attribute 17774 is not writable. 17775 17776 -- Instance Variable of LazyString: type 17777 This attribute holds the type that is represented by the lazy 17778 string's type. For a lazy string this will always be a pointer 17779 type. To resolve this to the lazy string's character type, use 17780 the type's `target' method. *Note Types In Python::. This 17781 attribute is not writable. 17782 17783 17784 File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top 17785 17786 24 Command Interpreters 17787 *********************** 17788 17789 GDB supports multiple command interpreters, and some command 17790 infrastructure to allow users or user interface writers to switch 17791 between interpreters or run commands in other interpreters. 17792 17793 GDB currently supports two command interpreters, the console 17794 interpreter (sometimes called the command-line interpreter or CLI) and 17795 the machine interface interpreter (or GDB/MI). This manual describes 17796 both of these interfaces in great detail. 17797 17798 By default, GDB will start with the console interpreter. However, 17799 the user may choose to start GDB with another interpreter by specifying 17800 the `-i' or `--interpreter' startup options. Defined interpreters 17801 include: 17802 17803 `console' 17804 The traditional console or command-line interpreter. This is the 17805 most often used interpreter with GDB. With no interpreter 17806 specified at runtime, GDB will use this interpreter. 17807 17808 `mi' 17809 The newest GDB/MI interface (currently `mi2'). Used primarily by 17810 programs wishing to use GDB as a backend for a debugger GUI or an 17811 IDE. For more information, see *Note The GDB/MI Interface: GDB/MI. 17812 17813 `mi2' 17814 The current GDB/MI interface. 17815 17816 `mi1' 17817 The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. 17818 17819 17820 The interpreter being used by GDB may not be dynamically switched at 17821 runtime. Although possible, this could lead to a very precarious 17822 situation. Consider an IDE using GDB/MI. If a user enters the command 17823 "interpreter-set console" in a console view, GDB would switch to using 17824 the console interpreter, rendering the IDE inoperable! 17825 17826 Although you may only choose a single interpreter at startup, you 17827 may execute commands in any interpreter from the current interpreter 17828 using the appropriate command. If you are running the console 17829 interpreter, simply use the `interpreter-exec' command: 17830 17831 interpreter-exec mi "-data-list-register-names" 17832 17833 GDB/MI has a similar command, although it is only available in 17834 versions of GDB which support GDB/MI version 2 (or greater). 17835 17836 17837 File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top 17838 17839 25 GDB Text User Interface 17840 ************************** 17841 17842 * Menu: 17843 17844 * TUI Overview:: TUI overview 17845 * TUI Keys:: TUI key bindings 17846 * TUI Single Key Mode:: TUI single key mode 17847 * TUI Commands:: TUI-specific commands 17848 * TUI Configuration:: TUI configuration variables 17849 17850 The GDB Text User Interface (TUI) is a terminal interface which uses 17851 the `curses' library to show the source file, the assembly output, the 17852 program registers and GDB commands in separate text windows. The TUI 17853 mode is supported only on platforms where a suitable version of the 17854 `curses' library is available. 17855 17856 The TUI mode is enabled by default when you invoke GDB as either 17857 `gdbtui' or `gdb -tui'. You can also switch in and out of TUI mode 17858 while GDB runs by using various TUI commands and key bindings, such as 17859 `C-x C-a'. *Note TUI Key Bindings: TUI Keys. 17860 17861 17862 File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI 17863 17864 25.1 TUI Overview 17865 ================= 17866 17867 In TUI mode, GDB can display several text windows: 17868 17869 _command_ 17870 This window is the GDB command window with the GDB prompt and the 17871 GDB output. The GDB input is still managed using readline. 17872 17873 _source_ 17874 The source window shows the source file of the program. The 17875 current line and active breakpoints are displayed in this window. 17876 17877 _assembly_ 17878 The assembly window shows the disassembly output of the program. 17879 17880 _register_ 17881 This window shows the processor registers. Registers are 17882 highlighted when their values change. 17883 17884 The source and assembly windows show the current program position by 17885 highlighting the current line and marking it with a `>' marker. 17886 Breakpoints are indicated with two markers. The first marker indicates 17887 the breakpoint type: 17888 17889 `B' 17890 Breakpoint which was hit at least once. 17891 17892 `b' 17893 Breakpoint which was never hit. 17894 17895 `H' 17896 Hardware breakpoint which was hit at least once. 17897 17898 `h' 17899 Hardware breakpoint which was never hit. 17900 17901 The second marker indicates whether the breakpoint is enabled or not: 17902 17903 `+' 17904 Breakpoint is enabled. 17905 17906 `-' 17907 Breakpoint is disabled. 17908 17909 The source, assembly and register windows are updated when the 17910 current thread changes, when the frame changes, or when the program 17911 counter changes. 17912 17913 These windows are not all visible at the same time. The command 17914 window is always visible. The others can be arranged in several 17915 layouts: 17916 17917 * source only, 17918 17919 * assembly only, 17920 17921 * source and assembly, 17922 17923 * source and registers, or 17924 17925 * assembly and registers. 17926 17927 A status line above the command window shows the following 17928 information: 17929 17930 _target_ 17931 Indicates the current GDB target. (*note Specifying a Debugging 17932 Target: Targets.). 17933 17934 _process_ 17935 Gives the current process or thread number. When no process is 17936 being debugged, this field is set to `No process'. 17937 17938 _function_ 17939 Gives the current function name for the selected frame. The name 17940 is demangled if demangling is turned on (*note Print Settings::). 17941 When there is no symbol corresponding to the current program 17942 counter, the string `??' is displayed. 17943 17944 _line_ 17945 Indicates the current line number for the selected frame. When 17946 the current line number is not known, the string `??' is displayed. 17947 17948 _pc_ 17949 Indicates the current program counter address. 17950 17951 17952 File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI 17953 17954 25.2 TUI Key Bindings 17955 ===================== 17956 17957 The TUI installs several key bindings in the readline keymaps (*note 17958 Command Line Editing::). The following key bindings are installed for 17959 both TUI mode and the GDB standard mode. 17960 17961 `C-x C-a' 17962 `C-x a' 17963 `C-x A' 17964 Enter or leave the TUI mode. When leaving the TUI mode, the 17965 curses window management stops and GDB operates using its standard 17966 mode, writing on the terminal directly. When reentering the TUI 17967 mode, control is given back to the curses windows. The screen is 17968 then refreshed. 17969 17970 `C-x 1' 17971 Use a TUI layout with only one window. The layout will either be 17972 `source' or `assembly'. When the TUI mode is not active, it will 17973 switch to the TUI mode. 17974 17975 Think of this key binding as the Emacs `C-x 1' binding. 17976 17977 `C-x 2' 17978 Use a TUI layout with at least two windows. When the current 17979 layout already has two windows, the next layout with two windows 17980 is used. When a new layout is chosen, one window will always be 17981 common to the previous layout and the new one. 17982 17983 Think of it as the Emacs `C-x 2' binding. 17984 17985 `C-x o' 17986 Change the active window. The TUI associates several key bindings 17987 (like scrolling and arrow keys) with the active window. This 17988 command gives the focus to the next TUI window. 17989 17990 Think of it as the Emacs `C-x o' binding. 17991 17992 `C-x s' 17993 Switch in and out of the TUI SingleKey mode that binds single keys 17994 to GDB commands (*note TUI Single Key Mode::). 17995 17996 The following key bindings only work in the TUI mode: 17997 17998 <PgUp> 17999 Scroll the active window one page up. 18000 18001 <PgDn> 18002 Scroll the active window one page down. 18003 18004 <Up> 18005 Scroll the active window one line up. 18006 18007 <Down> 18008 Scroll the active window one line down. 18009 18010 <Left> 18011 Scroll the active window one column left. 18012 18013 <Right> 18014 Scroll the active window one column right. 18015 18016 `C-L' 18017 Refresh the screen. 18018 18019 Because the arrow keys scroll the active window in the TUI mode, they 18020 are not available for their normal use by readline unless the command 18021 window has the focus. When another window is active, you must use 18022 other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to 18023 control the command window. 18024 18025 18026 File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI 18027 18028 25.3 TUI Single Key Mode 18029 ======================== 18030 18031 The TUI also provides a "SingleKey" mode, which binds several 18032 frequently used GDB commands to single keys. Type `C-x s' to switch 18033 into this mode, where the following key bindings are used: 18034 18035 `c' 18036 continue 18037 18038 `d' 18039 down 18040 18041 `f' 18042 finish 18043 18044 `n' 18045 next 18046 18047 `q' 18048 exit the SingleKey mode. 18049 18050 `r' 18051 run 18052 18053 `s' 18054 step 18055 18056 `u' 18057 up 18058 18059 `v' 18060 info locals 18061 18062 `w' 18063 where 18064 18065 Other keys temporarily switch to the GDB command prompt. The key 18066 that was pressed is inserted in the editing buffer so that it is 18067 possible to type most GDB commands without interaction with the TUI 18068 SingleKey mode. Once the command is entered the TUI SingleKey mode is 18069 restored. The only way to permanently leave this mode is by typing `q' 18070 or `C-x s'. 18071 18072 18073 File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI 18074 18075 25.4 TUI-specific Commands 18076 ========================== 18077 18078 The TUI has specific commands to control the text windows. These 18079 commands are always available, even when GDB is not in the TUI mode. 18080 When GDB is in the standard mode, most of these commands will 18081 automatically switch to the TUI mode. 18082 18083 `info win' 18084 List and give the size of all displayed windows. 18085 18086 `layout next' 18087 Display the next layout. 18088 18089 `layout prev' 18090 Display the previous layout. 18091 18092 `layout src' 18093 Display the source window only. 18094 18095 `layout asm' 18096 Display the assembly window only. 18097 18098 `layout split' 18099 Display the source and assembly window. 18100 18101 `layout regs' 18102 Display the register window together with the source or assembly 18103 window. 18104 18105 `focus next' 18106 Make the next window active for scrolling. 18107 18108 `focus prev' 18109 Make the previous window active for scrolling. 18110 18111 `focus src' 18112 Make the source window active for scrolling. 18113 18114 `focus asm' 18115 Make the assembly window active for scrolling. 18116 18117 `focus regs' 18118 Make the register window active for scrolling. 18119 18120 `focus cmd' 18121 Make the command window active for scrolling. 18122 18123 `refresh' 18124 Refresh the screen. This is similar to typing `C-L'. 18125 18126 `tui reg float' 18127 Show the floating point registers in the register window. 18128 18129 `tui reg general' 18130 Show the general registers in the register window. 18131 18132 `tui reg next' 18133 Show the next register group. The list of register groups as well 18134 as their order is target specific. The predefined register groups 18135 are the following: `general', `float', `system', `vector', `all', 18136 `save', `restore'. 18137 18138 `tui reg system' 18139 Show the system registers in the register window. 18140 18141 `update' 18142 Update the source window and the current execution point. 18143 18144 `winheight NAME +COUNT' 18145 `winheight NAME -COUNT' 18146 Change the height of the window NAME by COUNT lines. Positive 18147 counts increase the height, while negative counts decrease it. 18148 18149 `tabset NCHARS' 18150 Set the width of tab stops to be NCHARS characters. 18151 18152 18153 File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI 18154 18155 25.5 TUI Configuration Variables 18156 ================================ 18157 18158 Several configuration variables control the appearance of TUI windows. 18159 18160 `set tui border-kind KIND' 18161 Select the border appearance for the source, assembly and register 18162 windows. The possible values are the following: 18163 `space' 18164 Use a space character to draw the border. 18165 18166 `ascii' 18167 Use ASCII characters `+', `-' and `|' to draw the border. 18168 18169 `acs' 18170 Use the Alternate Character Set to draw the border. The 18171 border is drawn using character line graphics if the terminal 18172 supports them. 18173 18174 `set tui border-mode MODE' 18175 `set tui active-border-mode MODE' 18176 Select the display attributes for the borders of the inactive 18177 windows or the active window. The MODE can be one of the 18178 following: 18179 `normal' 18180 Use normal attributes to display the border. 18181 18182 `standout' 18183 Use standout mode. 18184 18185 `reverse' 18186 Use reverse video mode. 18187 18188 `half' 18189 Use half bright mode. 18190 18191 `half-standout' 18192 Use half bright and standout mode. 18193 18194 `bold' 18195 Use extra bright or bold mode. 18196 18197 `bold-standout' 18198 Use extra bright or bold and standout mode. 18199 18200 18201 File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top 18202 18203 26 Using GDB under GNU Emacs 18204 **************************** 18205 18206 A special interface allows you to use GNU Emacs to view (and edit) the 18207 source files for the program you are debugging with GDB. 18208 18209 To use this interface, use the command `M-x gdb' in Emacs. Give the 18210 executable file you want to debug as an argument. This command starts 18211 GDB as a subprocess of Emacs, with input and output through a newly 18212 created Emacs buffer. 18213 18214 Running GDB under Emacs can be just like running GDB normally except 18215 for two things: 18216 18217 * All "terminal" input and output goes through an Emacs buffer, 18218 called the GUD buffer. 18219 18220 This applies both to GDB commands and their output, and to the 18221 input and output done by the program you are debugging. 18222 18223 This is useful because it means that you can copy the text of 18224 previous commands and input them again; you can even use parts of 18225 the output in this way. 18226 18227 All the facilities of Emacs' Shell mode are available for 18228 interacting with your program. In particular, you can send 18229 signals the usual way--for example, `C-c C-c' for an interrupt, 18230 `C-c C-z' for a stop. 18231 18232 * GDB displays source code through Emacs. 18233 18234 Each time GDB displays a stack frame, Emacs automatically finds the 18235 source file for that frame and puts an arrow (`=>') at the left 18236 margin of the current line. Emacs uses a separate buffer for 18237 source display, and splits the screen to show both your GDB session 18238 and the source. 18239 18240 Explicit GDB `list' or search commands still produce output as 18241 usual, but you probably have no reason to use them from Emacs. 18242 18243 We call this "text command mode". Emacs 22.1, and later, also uses 18244 a graphical mode, enabled by default, which provides further buffers 18245 that can control the execution and describe the state of your program. 18246 *Note GDB Graphical Interface: (Emacs)GDB Graphical Interface. 18247 18248 If you specify an absolute file name when prompted for the `M-x gdb' 18249 argument, then Emacs sets your current working directory to where your 18250 program resides. If you only specify the file name, then Emacs sets 18251 your current working directory to to the directory associated with the 18252 previous buffer. In this case, GDB may find your program by searching 18253 your environment's `PATH' variable, but on some operating systems it 18254 might not find the source. So, although the GDB input and output 18255 session proceeds normally, the auxiliary buffer does not display the 18256 current source and line of execution. 18257 18258 The initial working directory of GDB is printed on the top line of 18259 the GUD buffer and this serves as a default for the commands that 18260 specify files for GDB to operate on. *Note Commands to Specify Files: 18261 Files. 18262 18263 By default, `M-x gdb' calls the program called `gdb'. If you need 18264 to call GDB by a different name (for example, if you keep several 18265 configurations around, with different names) you can customize the 18266 Emacs variable `gud-gdb-command-name' to run the one you want. 18267 18268 In the GUD buffer, you can use these special Emacs commands in 18269 addition to the standard Shell mode commands: 18270 18271 `C-h m' 18272 Describe the features of Emacs' GUD Mode. 18273 18274 `C-c C-s' 18275 Execute to another source line, like the GDB `step' command; also 18276 update the display window to show the current file and location. 18277 18278 `C-c C-n' 18279 Execute to next source line in this function, skipping all function 18280 calls, like the GDB `next' command. Then update the display window 18281 to show the current file and location. 18282 18283 `C-c C-i' 18284 Execute one instruction, like the GDB `stepi' command; update 18285 display window accordingly. 18286 18287 `C-c C-f' 18288 Execute until exit from the selected stack frame, like the GDB 18289 `finish' command. 18290 18291 `C-c C-r' 18292 Continue execution of your program, like the GDB `continue' 18293 command. 18294 18295 `C-c <' 18296 Go up the number of frames indicated by the numeric argument 18297 (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' 18298 command. 18299 18300 `C-c >' 18301 Go down the number of frames indicated by the numeric argument, 18302 like the GDB `down' command. 18303 18304 In any source file, the Emacs command `C-x <SPC>' (`gud-break') 18305 tells GDB to set a breakpoint on the source line point is on. 18306 18307 In text command mode, if you type `M-x speedbar', Emacs displays a 18308 separate frame which shows a backtrace when the GUD buffer is current. 18309 Move point to any frame in the stack and type <RET> to make it become 18310 the current frame and display the associated source in the source 18311 buffer. Alternatively, click `Mouse-2' to make the selected frame 18312 become the current one. In graphical mode, the speedbar displays watch 18313 expressions. 18314 18315 If you accidentally delete the source-display buffer, an easy way to 18316 get it back is to type the command `f' in the GDB buffer, to request a 18317 frame display; when you run under Emacs, this recreates the source 18318 buffer if necessary to show you the context of the current frame. 18319 18320 The source files displayed in Emacs are in ordinary Emacs buffers 18321 which are visiting the source files in the usual way. You can edit the 18322 files with these buffers if you wish; but keep in mind that GDB 18323 communicates with Emacs in terms of line numbers. If you add or delete 18324 lines from the text, the line numbers that GDB knows cease to 18325 correspond properly with the code. 18326 18327 A more detailed description of Emacs' interaction with GDB is given 18328 in the Emacs manual (*note Debuggers: (Emacs)Debuggers.). 18329 18330 18331 File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top 18332 18333 27 The GDB/MI Interface 18334 *********************** 18335 18336 Function and Purpose 18337 ==================== 18338 18339 GDB/MI is a line based machine oriented text interface to GDB and is 18340 activated by specifying using the `--interpreter' command line option 18341 (*note Mode Options::). It is specifically intended to support the 18342 development of systems which use the debugger as just one small 18343 component of a larger system. 18344 18345 This chapter is a specification of the GDB/MI interface. It is 18346 written in the form of a reference manual. 18347 18348 Note that GDB/MI is still under construction, so some of the 18349 features described below are incomplete and subject to change (*note 18350 GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.). 18351 18352 Notation and Terminology 18353 ======================== 18354 18355 This chapter uses the following notation: 18356 18357 * `|' separates two alternatives. 18358 18359 * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or 18360 may not be given. 18361 18362 * `( GROUP )*' means that GROUP inside the parentheses may repeat 18363 zero or more times. 18364 18365 * `( GROUP )+' means that GROUP inside the parentheses may repeat 18366 one or more times. 18367 18368 * `"STRING"' means a literal STRING. 18369 18370 * Menu: 18371 18372 * GDB/MI General Design:: 18373 * GDB/MI Command Syntax:: 18374 * GDB/MI Compatibility with CLI:: 18375 * GDB/MI Development and Front Ends:: 18376 * GDB/MI Output Records:: 18377 * GDB/MI Simple Examples:: 18378 * GDB/MI Command Description Format:: 18379 * GDB/MI Breakpoint Commands:: 18380 * GDB/MI Program Context:: 18381 * GDB/MI Thread Commands:: 18382 * GDB/MI Program Execution:: 18383 * GDB/MI Stack Manipulation:: 18384 * GDB/MI Variable Objects:: 18385 * GDB/MI Data Manipulation:: 18386 * GDB/MI Tracepoint Commands:: 18387 * GDB/MI Symbol Query:: 18388 * GDB/MI File Commands:: 18389 * GDB/MI Target Manipulation:: 18390 * GDB/MI File Transfer Commands:: 18391 * GDB/MI Miscellaneous Commands:: 18392 18393 18394 File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI 18395 18396 27.1 GDB/MI General Design 18397 ========================== 18398 18399 Interaction of a GDB/MI frontend with GDB involves three 18400 parts--commands sent to GDB, responses to those commands and 18401 notifications. Each command results in exactly one response, 18402 indicating either successful completion of the command, or an error. 18403 For the commands that do not resume the target, the response contains 18404 the requested information. For the commands that resume the target, the 18405 response only indicates whether the target was successfully resumed. 18406 Notifications is the mechanism for reporting changes in the state of the 18407 target, or in GDB state, that cannot conveniently be associated with a 18408 command and reported as part of that command response. 18409 18410 The important examples of notifications are: 18411 * Exec notifications. These are used to report changes in target 18412 state--when a target is resumed, or stopped. It would not be 18413 feasible to include this information in response of resuming 18414 commands, because one resume commands can result in multiple 18415 events in different threads. Also, quite some time may pass 18416 before any event happens in the target, while a frontend needs to 18417 know whether the resuming command itself was successfully executed. 18418 18419 * Console output, and status notifications. Console output 18420 notifications are used to report output of CLI commands, as well as 18421 diagnostics for other commands. Status notifications are used to 18422 report the progress of a long-running operation. Naturally, 18423 including this information in command response would mean no 18424 output is produced until the command is finished, which is 18425 undesirable. 18426 18427 * General notifications. Commands may have various side effects on 18428 the GDB or target state beyond their official purpose. For 18429 example, a command may change the selected thread. Although such 18430 changes can be included in command response, using notification 18431 allows for more orthogonal frontend design. 18432 18433 18434 There's no guarantee that whenever an MI command reports an error, 18435 GDB or the target are in any specific state, and especially, the state 18436 is not reverted to the state before the MI command was processed. 18437 Therefore, whenever an MI command results in an error, we recommend 18438 that the frontend refreshes all the information shown in the user 18439 interface. 18440 18441 * Menu: 18442 18443 * Context management:: 18444 * Asynchronous and non-stop modes:: 18445 * Thread groups:: 18446 18447 18448 File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design 18449 18450 27.1.1 Context management 18451 ------------------------- 18452 18453 In most cases when GDB accesses the target, this access is done in 18454 context of a specific thread and frame (*note Frames::). Often, even 18455 when accessing global data, the target requires that a thread be 18456 specified. The CLI interface maintains the selected thread and frame, 18457 and supplies them to target on each command. This is convenient, 18458 because a command line user would not want to specify that information 18459 explicitly on each command, and because user interacts with GDB via a 18460 single terminal, so no confusion is possible as to what thread and 18461 frame are the current ones. 18462 18463 In the case of MI, the concept of selected thread and frame is less 18464 useful. First, a frontend can easily remember this information itself. 18465 Second, a graphical frontend can have more than one window, each one 18466 used for debugging a different thread, and the frontend might want to 18467 access additional threads for internal purposes. This increases the 18468 risk that by relying on implicitly selected thread, the frontend may be 18469 operating on a wrong one. Therefore, each MI command should explicitly 18470 specify which thread and frame to operate on. To make it possible, 18471 each MI command accepts the `--thread' and `--frame' options, the value 18472 to each is GDB identifier for thread and frame to operate on. 18473 18474 Usually, each top-level window in a frontend allows the user to 18475 select a thread and a frame, and remembers the user selection for 18476 further operations. However, in some cases GDB may suggest that the 18477 current thread be changed. For example, when stopping on a breakpoint 18478 it is reasonable to switch to the thread where breakpoint is hit. For 18479 another example, if the user issues the CLI `thread' command via the 18480 frontend, it is desirable to change the frontend's selected thread to 18481 the one specified by user. GDB communicates the suggestion to change 18482 current thread using the `=thread-selected' notification. No such 18483 notification is available for the selected frame at the moment. 18484 18485 Note that historically, MI shares the selected thread with CLI, so 18486 frontends used the `-thread-select' to execute commands in the right 18487 context. However, getting this to work right is cumbersome. The 18488 simplest way is for frontend to emit `-thread-select' command before 18489 every command. This doubles the number of commands that need to be 18490 sent. The alternative approach is to suppress `-thread-select' if the 18491 selected thread in GDB is supposed to be identical to the thread the 18492 frontend wants to operate on. However, getting this optimization right 18493 can be tricky. In particular, if the frontend sends several commands 18494 to GDB, and one of the commands changes the selected thread, then the 18495 behaviour of subsequent commands will change. So, a frontend should 18496 either wait for response from such problematic commands, or explicitly 18497 add `-thread-select' for all subsequent commands. No frontend is known 18498 to do this exactly right, so it is suggested to just always pass the 18499 `--thread' and `--frame' options. 18500 18501 18502 File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design 18503 18504 27.1.2 Asynchronous command execution and non-stop mode 18505 ------------------------------------------------------- 18506 18507 On some targets, GDB is capable of processing MI commands even while 18508 the target is running. This is called "asynchronous command execution" 18509 (*note Background Execution::). The frontend may specify a preferrence 18510 for asynchronous execution using the `-gdb-set target-async 1' command, 18511 which should be emitted before either running the executable or 18512 attaching to the target. After the frontend has started the executable 18513 or attached to the target, it can find if asynchronous execution is 18514 enabled using the `-list-target-features' command. 18515 18516 Even if GDB can accept a command while target is running, many 18517 commands that access the target do not work when the target is running. 18518 Therefore, asynchronous command execution is most useful when combined 18519 with non-stop mode (*note Non-Stop Mode::). Then, it is possible to 18520 examine the state of one thread, while other threads are running. 18521 18522 When a given thread is running, MI commands that try to access the 18523 target in the context of that thread may not work, or may work only on 18524 some targets. In particular, commands that try to operate on thread's 18525 stack will not work, on any target. Commands that read memory, or 18526 modify breakpoints, may work or not work, depending on the target. Note 18527 that even commands that operate on global state, such as `print', 18528 `set', and breakpoint commands, still access the target in the context 18529 of a specific thread, so frontend should try to find a stopped thread 18530 and perform the operation on that thread (using the `--thread' option). 18531 18532 Which commands will work in the context of a running thread is 18533 highly target dependent. However, the two commands `-exec-interrupt', 18534 to stop a thread, and `-thread-info', to find the state of a thread, 18535 will always work. 18536 18537 18538 File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design 18539 18540 27.1.3 Thread groups 18541 -------------------- 18542 18543 GDB may be used to debug several processes at the same time. On some 18544 platfroms, GDB may support debugging of several hardware systems, each 18545 one having several cores with several different processes running on 18546 each core. This section describes the MI mechanism to support such 18547 debugging scenarios. 18548 18549 The key observation is that regardless of the structure of the 18550 target, MI can have a global list of threads, because most commands that 18551 accept the `--thread' option do not need to know what process that 18552 thread belongs to. Therefore, it is not necessary to introduce neither 18553 additional `--process' option, nor an notion of the current process in 18554 the MI interface. The only strictly new feature that is required is 18555 the ability to find how the threads are grouped into processes. 18556 18557 To allow the user to discover such grouping, and to support arbitrary 18558 hierarchy of machines/cores/processes, MI introduces the concept of a 18559 "thread group". Thread group is a collection of threads and other 18560 thread groups. A thread group always has a string identifier, a type, 18561 and may have additional attributes specific to the type. A new 18562 command, `-list-thread-groups', returns the list of top-level thread 18563 groups, which correspond to processes that GDB is debugging at the 18564 moment. By passing an identifier of a thread group to the 18565 `-list-thread-groups' command, it is possible to obtain the members of 18566 specific thread group. 18567 18568 To allow the user to easily discover processes, and other objects, he 18569 wishes to debug, a concept of "available thread group" is introduced. 18570 Available thread group is an thread group that GDB is not debugging, 18571 but that can be attached to, using the `-target-attach' command. The 18572 list of available top-level thread groups can be obtained using 18573 `-list-thread-groups --available'. In general, the content of a thread 18574 group may be only retrieved only after attaching to that thread group. 18575 18576 18577 File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI 18578 18579 27.2 GDB/MI Command Syntax 18580 ========================== 18581 18582 * Menu: 18583 18584 * GDB/MI Input Syntax:: 18585 * GDB/MI Output Syntax:: 18586 18587 18588 File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax 18589 18590 27.2.1 GDB/MI Input Syntax 18591 -------------------------- 18592 18593 `COMMAND ==>' 18594 `CLI-COMMAND | MI-COMMAND' 18595 18596 `CLI-COMMAND ==>' 18597 `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB 18598 CLI command. 18599 18600 `MI-COMMAND ==>' 18601 `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " 18602 PARAMETER )* NL' 18603 18604 `TOKEN ==>' 18605 "any sequence of digits" 18606 18607 `OPTION ==>' 18608 `"-" PARAMETER [ " " PARAMETER ]' 18609 18610 `PARAMETER ==>' 18611 `NON-BLANK-SEQUENCE | C-STRING' 18612 18613 `OPERATION ==>' 18614 _any of the operations described in this chapter_ 18615 18616 `NON-BLANK-SEQUENCE ==>' 18617 _anything, provided it doesn't contain special characters such as 18618 "-", NL, """ and of course " "_ 18619 18620 `C-STRING ==>' 18621 `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' 18622 18623 `NL ==>' 18624 `CR | CR-LF' 18625 18626 Notes: 18627 18628 * The CLI commands are still handled by the MI interpreter; their 18629 output is described below. 18630 18631 * The `TOKEN', when present, is passed back when the command 18632 finishes. 18633 18634 * Some MI commands accept optional arguments as part of the parameter 18635 list. Each option is identified by a leading `-' (dash) and may be 18636 followed by an optional argument parameter. Options occur first 18637 in the parameter list and can be delimited from normal parameters 18638 using `--' (this is useful when some parameters begin with a dash). 18639 18640 Pragmatics: 18641 18642 * We want easy access to the existing CLI syntax (for debugging). 18643 18644 * We want it to be easy to spot a MI operation. 18645 18646 18647 File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax 18648 18649 27.2.2 GDB/MI Output Syntax 18650 --------------------------- 18651 18652 The output from GDB/MI consists of zero or more out-of-band records 18653 followed, optionally, by a single result record. This result record is 18654 for the most recent command. The sequence of output records is 18655 terminated by `(gdb)'. 18656 18657 If an input command was prefixed with a `TOKEN' then the 18658 corresponding output for that command will also be prefixed by that same 18659 TOKEN. 18660 18661 `OUTPUT ==>' 18662 `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' 18663 18664 `RESULT-RECORD ==>' 18665 ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' 18666 18667 `OUT-OF-BAND-RECORD ==>' 18668 `ASYNC-RECORD | STREAM-RECORD' 18669 18670 `ASYNC-RECORD ==>' 18671 `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' 18672 18673 `EXEC-ASYNC-OUTPUT ==>' 18674 `[ TOKEN ] "*" ASYNC-OUTPUT' 18675 18676 `STATUS-ASYNC-OUTPUT ==>' 18677 `[ TOKEN ] "+" ASYNC-OUTPUT' 18678 18679 `NOTIFY-ASYNC-OUTPUT ==>' 18680 `[ TOKEN ] "=" ASYNC-OUTPUT' 18681 18682 `ASYNC-OUTPUT ==>' 18683 `ASYNC-CLASS ( "," RESULT )* NL' 18684 18685 `RESULT-CLASS ==>' 18686 `"done" | "running" | "connected" | "error" | "exit"' 18687 18688 `ASYNC-CLASS ==>' 18689 `"stopped" | OTHERS' (where OTHERS will be added depending on the 18690 needs--this is still in development). 18691 18692 `RESULT ==>' 18693 ` VARIABLE "=" VALUE' 18694 18695 `VARIABLE ==>' 18696 ` STRING ' 18697 18698 `VALUE ==>' 18699 ` CONST | TUPLE | LIST ' 18700 18701 `CONST ==>' 18702 `C-STRING' 18703 18704 `TUPLE ==>' 18705 ` "{}" | "{" RESULT ( "," RESULT )* "}" ' 18706 18707 `LIST ==>' 18708 ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* 18709 "]" ' 18710 18711 `STREAM-RECORD ==>' 18712 `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' 18713 18714 `CONSOLE-STREAM-OUTPUT ==>' 18715 `"~" C-STRING' 18716 18717 `TARGET-STREAM-OUTPUT ==>' 18718 `"@" C-STRING' 18719 18720 `LOG-STREAM-OUTPUT ==>' 18721 `"&" C-STRING' 18722 18723 `NL ==>' 18724 `CR | CR-LF' 18725 18726 `TOKEN ==>' 18727 _any sequence of digits_. 18728 18729 Notes: 18730 18731 * All output sequences end in a single line containing a period. 18732 18733 * The `TOKEN' is from the corresponding request. Note that for all 18734 async output, while the token is allowed by the grammar and may be 18735 output by future versions of GDB for select async output messages, 18736 it is generally omitted. Frontends should treat all async output 18737 as reporting general changes in the state of the target and there 18738 should be no need to associate async output to any prior command. 18739 18740 * STATUS-ASYNC-OUTPUT contains on-going status information about the 18741 progress of a slow operation. It can be discarded. All status 18742 output is prefixed by `+'. 18743 18744 * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target 18745 (stopped, started, disappeared). All async output is prefixed by 18746 `*'. 18747 18748 * NOTIFY-ASYNC-OUTPUT contains supplementary information that the 18749 client should handle (e.g., a new breakpoint information). All 18750 notify output is prefixed by `='. 18751 18752 * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in 18753 the console. It is the textual response to a CLI command. All 18754 the console output is prefixed by `~'. 18755 18756 * TARGET-STREAM-OUTPUT is the output produced by the target program. 18757 All the target output is prefixed by `@'. 18758 18759 * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for 18760 instance messages that should be displayed as part of an error 18761 log. All the log output is prefixed by `&'. 18762 18763 * New GDB/MI commands should only output LISTS containing VALUES. 18764 18765 18766 *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details 18767 about the various output records. 18768 18769 18770 File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI 18771 18772 27.3 GDB/MI Compatibility with CLI 18773 ================================== 18774 18775 For the developers convenience CLI commands can be entered directly, 18776 but there may be some unexpected behaviour. For example, commands that 18777 query the user will behave as if the user replied yes, breakpoint 18778 command lists are not executed and some CLI commands, such as `if', 18779 `when' and `define', prompt for further input with `>', which is not 18780 valid MI output. 18781 18782 This feature may be removed at some stage in the future and it is 18783 recommended that front ends use the `-interpreter-exec' command (*note 18784 -interpreter-exec::). 18785 18786 18787 File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI 18788 18789 27.4 GDB/MI Development and Front Ends 18790 ====================================== 18791 18792 The application which takes the MI output and presents the state of the 18793 program being debugged to the user is called a "front end". 18794 18795 Although GDB/MI is still incomplete, it is currently being used by a 18796 variety of front ends to GDB. This makes it difficult to introduce new 18797 functionality without breaking existing usage. This section tries to 18798 minimize the problems by describing how the protocol might change. 18799 18800 Some changes in MI need not break a carefully designed front end, and 18801 for these the MI version will remain unchanged. The following is a 18802 list of changes that may occur within one level, so front ends should 18803 parse MI output in a way that can handle them: 18804 18805 * New MI commands may be added. 18806 18807 * New fields may be added to the output of any MI command. 18808 18809 * The range of values for fields with specified values, e.g., 18810 `in_scope' (*note -var-update::) may be extended. 18811 18812 18813 If the changes are likely to break front ends, the MI version level 18814 will be increased by one. This will allow the front end to parse the 18815 output according to the MI version. Apart from mi0, new versions of 18816 GDB will not support old versions of MI and it will be the 18817 responsibility of the front end to work with the new one. 18818 18819 The best way to avoid unexpected changes in MI that might break your 18820 front end is to make your project known to GDB developers and follow 18821 development on <gdb (a] sourceware.org> and <gdb-patches (a] sourceware.org>. 18822 18823 18824 File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI 18825 18826 27.5 GDB/MI Output Records 18827 ========================== 18828 18829 * Menu: 18830 18831 * GDB/MI Result Records:: 18832 * GDB/MI Stream Records:: 18833 * GDB/MI Async Records:: 18834 * GDB/MI Frame Information:: 18835 * GDB/MI Thread Information:: 18836 18837 18838 File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records 18839 18840 27.5.1 GDB/MI Result Records 18841 ---------------------------- 18842 18843 In addition to a number of out-of-band notifications, the response to a 18844 GDB/MI command includes one of the following result indications: 18845 18846 `"^done" [ "," RESULTS ]' 18847 The synchronous operation was successful, `RESULTS' are the return 18848 values. 18849 18850 `"^running"' 18851 This result record is equivalent to `^done'. Historically, it was 18852 output instead of `^done' if the command has resumed the target. 18853 This behaviour is maintained for backward compatibility, but all 18854 frontends should treat `^done' and `^running' identically and rely 18855 on the `*running' output record to determine which threads are 18856 resumed. 18857 18858 `"^connected"' 18859 GDB has connected to a remote target. 18860 18861 `"^error" "," C-STRING' 18862 The operation failed. The `C-STRING' contains the corresponding 18863 error message. 18864 18865 `"^exit"' 18866 GDB has terminated. 18867 18868 18869 18870 File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records 18871 18872 27.5.2 GDB/MI Stream Records 18873 ---------------------------- 18874 18875 GDB internally maintains a number of output streams: the console, the 18876 target, and the log. The output intended for each of these streams is 18877 funneled through the GDB/MI interface using "stream records". 18878 18879 Each stream record begins with a unique "prefix character" which 18880 identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output 18881 Syntax.). In addition to the prefix, each stream record contains a 18882 `STRING-OUTPUT'. This is either raw text (with an implicit new line) 18883 or a quoted C string (which does not contain an implicit newline). 18884 18885 `"~" STRING-OUTPUT' 18886 The console output stream contains text that should be displayed 18887 in the CLI console window. It contains the textual responses to 18888 CLI commands. 18889 18890 `"@" STRING-OUTPUT' 18891 The target output stream contains any textual output from the 18892 running target. This is only present when GDB's event loop is 18893 truly asynchronous, which is currently only the case for remote 18894 targets. 18895 18896 `"&" STRING-OUTPUT' 18897 The log stream contains debugging messages being produced by GDB's 18898 internals. 18899 18900 18901 File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Frame Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records 18902 18903 27.5.3 GDB/MI Async Records 18904 --------------------------- 18905 18906 "Async" records are used to notify the GDB/MI client of additional 18907 changes that have occurred. Those changes can either be a consequence 18908 of GDB/MI commands (e.g., a breakpoint modified) or a result of target 18909 activity (e.g., target stopped). 18910 18911 The following is the list of possible async records: 18912 18913 `*running,thread-id="THREAD"' 18914 The target is now running. The THREAD field tells which specific 18915 thread is now running, and can be `all' if all threads are 18916 running. The frontend should assume that no interaction with a 18917 running thread is possible after this notification is produced. 18918 The frontend should not assume that this notification is output 18919 only once for any command. GDB may emit this notification several 18920 times, either for different threads, because it cannot resume all 18921 threads together, or even for a single thread, if the thread must 18922 be stepped though some code before letting it run freely. 18923 18924 `*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"' 18925 The target has stopped. The REASON field can have one of the 18926 following values: 18927 18928 `breakpoint-hit' 18929 A breakpoint was reached. 18930 18931 `watchpoint-trigger' 18932 A watchpoint was triggered. 18933 18934 `read-watchpoint-trigger' 18935 A read watchpoint was triggered. 18936 18937 `access-watchpoint-trigger' 18938 An access watchpoint was triggered. 18939 18940 `function-finished' 18941 An -exec-finish or similar CLI command was accomplished. 18942 18943 `location-reached' 18944 An -exec-until or similar CLI command was accomplished. 18945 18946 `watchpoint-scope' 18947 A watchpoint has gone out of scope. 18948 18949 `end-stepping-range' 18950 An -exec-next, -exec-next-instruction, -exec-step, 18951 -exec-step-instruction or similar CLI command was 18952 accomplished. 18953 18954 `exited-signalled' 18955 The inferior exited because of a signal. 18956 18957 `exited' 18958 The inferior exited. 18959 18960 `exited-normally' 18961 The inferior exited normally. 18962 18963 `signal-received' 18964 A signal was received by the inferior. 18965 18966 The ID field identifies the thread that directly caused the stop - 18967 for example by hitting a breakpoint. Depending on whether all-stop 18968 mode is in effect (*note All-Stop Mode::), GDB may either stop all 18969 threads, or only the thread that directly triggered the stop. If 18970 all threads are stopped, the STOPPED field will have the value of 18971 `"all"'. Otherwise, the value of the STOPPED field will be a list 18972 of thread identifiers. Presently, this list will always include a 18973 single thread, but frontend should be prepared to see several 18974 threads in the list. The CORE field reports the processor core on 18975 which the stop event has happened. This field may be absent if 18976 such information is not available. 18977 18978 `=thread-group-created,id="ID"' 18979 `=thread-group-exited,id="ID"' 18980 A thread thread group either was attached to, or has 18981 exited/detached from. The ID field contains the GDB identifier of 18982 the thread group. 18983 18984 `=thread-created,id="ID",group-id="GID"' 18985 `=thread-exited,id="ID",group-id="GID"' 18986 A thread either was created, or has exited. The ID field contains 18987 the GDB identifier of the thread. The GID field identifies the 18988 thread group this thread belongs to. 18989 18990 `=thread-selected,id="ID"' 18991 Informs that the selected thread was changed as result of the last 18992 command. This notification is not emitted as result of 18993 `-thread-select' command but is emitted whenever an MI command 18994 that is not documented to change the selected thread actually 18995 changes it. In particular, invoking, directly or indirectly (via 18996 user-defined command), the CLI `thread' command, will generate 18997 this notification. 18998 18999 We suggest that in response to this notification, front ends 19000 highlight the selected thread and cause subsequent commands to 19001 apply to that thread. 19002 19003 `=library-loaded,...' 19004 Reports that a new library file was loaded by the program. This 19005 notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and 19006 SYMBOLS-LOADED. The ID field is an opaque identifier of the 19007 library. For remote debugging case, TARGET-NAME and HOST-NAME 19008 fields give the name of the library file on the target, and on the 19009 host respectively. For native debugging, both those fields have 19010 the same value. The SYMBOLS-LOADED field reports if the debug 19011 symbols for this library are loaded. 19012 19013 `=library-unloaded,...' 19014 Reports that a library was unloaded by the program. This 19015 notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the 19016 same meaning as for the `=library-loaded' notification 19017 19018 19019 19020 File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records 19021 19022 27.5.4 GDB/MI Frame Information 19023 ------------------------------- 19024 19025 Response from many MI commands includes an information about stack 19026 frame. This information is a tuple that may have the following fields: 19027 19028 `level' 19029 The level of the stack frame. The innermost frame has the level of 19030 zero. This field is always present. 19031 19032 `func' 19033 The name of the function corresponding to the frame. This field 19034 may be absent if GDB is unable to determine the function name. 19035 19036 `addr' 19037 The code address for the frame. This field is always present. 19038 19039 `file' 19040 The name of the source files that correspond to the frame's code 19041 address. This field may be absent. 19042 19043 `line' 19044 The source line corresponding to the frames' code address. This 19045 field may be absent. 19046 19047 `from' 19048 The name of the binary file (either executable or shared library) 19049 the corresponds to the frame's code address. This field may be 19050 absent. 19051 19052 19053 19054 File: gdb.info, Node: GDB/MI Thread Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records 19055 19056 27.5.5 GDB/MI Thread Information 19057 -------------------------------- 19058 19059 Whenever GDB has to report an information about a thread, it uses a 19060 tuple with the following fields: 19061 19062 `id' 19063 The numeric id assigned to the thread by GDB. This field is 19064 always present. 19065 19066 `target-id' 19067 Target-specific string identifying the thread. This field is 19068 always present. 19069 19070 `details' 19071 Additional information about the thread provided by the target. 19072 It is supposed to be human-readable and not interpreted by the 19073 frontend. This field is optional. 19074 19075 `state' 19076 Either `stopped' or `running', depending on whether the thread is 19077 presently running. This field is always present. 19078 19079 `core' 19080 The value of this field is an integer number of the processor core 19081 the thread was last seen on. This field is optional. 19082 19083 19084 File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI 19085 19086 27.6 Simple Examples of GDB/MI Interaction 19087 ========================================== 19088 19089 This subsection presents several simple examples of interaction using 19090 the GDB/MI interface. In these examples, `->' means that the following 19091 line is passed to GDB/MI as input, while `<-' means the output received 19092 from GDB/MI. 19093 19094 Note the line breaks shown in the examples are here only for 19095 readability, they don't appear in the real output. 19096 19097 Setting a Breakpoint 19098 -------------------- 19099 19100 Setting a breakpoint generates synchronous output which contains 19101 detailed information of the breakpoint. 19102 19103 -> -break-insert main 19104 <- ^done,bkpt={number="1",type="breakpoint",disp="keep", 19105 enabled="y",addr="0x08048564",func="main",file="myprog.c", 19106 fullname="/home/nickrob/myprog.c",line="68",times="0"} 19107 <- (gdb) 19108 19109 Program Execution 19110 ----------------- 19111 19112 Program execution generates asynchronous records and MI gives the 19113 reason that execution stopped. 19114 19115 -> -exec-run 19116 <- ^running 19117 <- (gdb) 19118 <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 19119 frame={addr="0x08048564",func="main", 19120 args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], 19121 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"} 19122 <- (gdb) 19123 -> -exec-continue 19124 <- ^running 19125 <- (gdb) 19126 <- *stopped,reason="exited-normally" 19127 <- (gdb) 19128 19129 Quitting GDB 19130 ------------ 19131 19132 Quitting GDB just prints the result class `^exit'. 19133 19134 -> (gdb) 19135 <- -gdb-exit 19136 <- ^exit 19137 19138 Please note that `^exit' is printed immediately, but it might take 19139 some time for GDB to actually exit. During that time, GDB performs 19140 necessary cleanups, including killing programs being debugged or 19141 disconnecting from debug hardware, so the frontend should wait till GDB 19142 exits and should only forcibly kill GDB if it fails to exit in 19143 reasonable time. 19144 19145 A Bad Command 19146 ------------- 19147 19148 Here's what happens if you pass a non-existent command: 19149 19150 -> -rubbish 19151 <- ^error,msg="Undefined MI command: rubbish" 19152 <- (gdb) 19153 19154 19155 File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI 19156 19157 27.7 GDB/MI Command Description Format 19158 ====================================== 19159 19160 The remaining sections describe blocks of commands. Each block of 19161 commands is laid out in a fashion similar to this section. 19162 19163 Motivation 19164 ---------- 19165 19166 The motivation for this collection of commands. 19167 19168 Introduction 19169 ------------ 19170 19171 A brief introduction to this collection of commands as a whole. 19172 19173 Commands 19174 -------- 19175 19176 For each command in the block, the following is described: 19177 19178 Synopsis 19179 ........ 19180 19181 -command ARGS... 19182 19183 Result 19184 ...... 19185 19186 GDB Command 19187 ........... 19188 19189 The corresponding GDB CLI command(s), if any. 19190 19191 Example 19192 ....... 19193 19194 Example(s) formatted for readability. Some of the described commands 19195 have not been implemented yet and these are labeled N.A. (not 19196 available). 19197 19198 19199 File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI 19200 19201 27.8 GDB/MI Breakpoint Commands 19202 =============================== 19203 19204 This section documents GDB/MI commands for manipulating breakpoints. 19205 19206 The `-break-after' Command 19207 -------------------------- 19208 19209 Synopsis 19210 ........ 19211 19212 -break-after NUMBER COUNT 19213 19214 The breakpoint number NUMBER is not in effect until it has been hit 19215 COUNT times. To see how this is reflected in the output of the 19216 `-break-list' command, see the description of the `-break-list' command 19217 below. 19218 19219 GDB Command 19220 ........... 19221 19222 The corresponding GDB command is `ignore'. 19223 19224 Example 19225 ....... 19226 19227 (gdb) 19228 -break-insert main 19229 ^done,bkpt={number="1",type="breakpoint",disp="keep", 19230 enabled="y",addr="0x000100d0",func="main",file="hello.c", 19231 fullname="/home/foo/hello.c",line="5",times="0"} 19232 (gdb) 19233 -break-after 1 3 19234 ~ 19235 ^done 19236 (gdb) 19237 -break-list 19238 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 19239 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19240 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19241 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19242 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19243 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19244 {width="40",alignment="2",col_name="what",colhdr="What"}], 19245 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 19246 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 19247 line="5",times="0",ignore="3"}]} 19248 (gdb) 19249 19250 The `-break-commands' Command 19251 ----------------------------- 19252 19253 Synopsis 19254 ........ 19255 19256 -break-commands NUMBER [ COMMAND1 ... COMMANDN ] 19257 19258 Specifies the CLI commands that should be executed when breakpoint 19259 NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands. 19260 If no command is specified, any previously-set commands are cleared. 19261 *Note Break Commands::. Typical use of this functionality is tracing a 19262 program, that is, printing of values of some variables whenever 19263 breakpoint is hit and then continuing. 19264 19265 GDB Command 19266 ........... 19267 19268 The corresponding GDB command is `commands'. 19269 19270 Example 19271 ....... 19272 19273 (gdb) 19274 -break-insert main 19275 ^done,bkpt={number="1",type="breakpoint",disp="keep", 19276 enabled="y",addr="0x000100d0",func="main",file="hello.c", 19277 fullname="/home/foo/hello.c",line="5",times="0"} 19278 (gdb) 19279 -break-commands 1 "print v" "continue" 19280 ^done 19281 (gdb) 19282 19283 The `-break-condition' Command 19284 ------------------------------ 19285 19286 Synopsis 19287 ........ 19288 19289 -break-condition NUMBER EXPR 19290 19291 Breakpoint NUMBER will stop the program only if the condition in 19292 EXPR is true. The condition becomes part of the `-break-list' output 19293 (see the description of the `-break-list' command below). 19294 19295 GDB Command 19296 ........... 19297 19298 The corresponding GDB command is `condition'. 19299 19300 Example 19301 ....... 19302 19303 (gdb) 19304 -break-condition 1 1 19305 ^done 19306 (gdb) 19307 -break-list 19308 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 19309 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19310 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19311 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19312 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19313 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19314 {width="40",alignment="2",col_name="what",colhdr="What"}], 19315 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 19316 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 19317 line="5",cond="1",times="0",ignore="3"}]} 19318 (gdb) 19319 19320 The `-break-delete' Command 19321 --------------------------- 19322 19323 Synopsis 19324 ........ 19325 19326 -break-delete ( BREAKPOINT )+ 19327 19328 Delete the breakpoint(s) whose number(s) are specified in the 19329 argument list. This is obviously reflected in the breakpoint list. 19330 19331 GDB Command 19332 ........... 19333 19334 The corresponding GDB command is `delete'. 19335 19336 Example 19337 ....... 19338 19339 (gdb) 19340 -break-delete 1 19341 ^done 19342 (gdb) 19343 -break-list 19344 ^done,BreakpointTable={nr_rows="0",nr_cols="6", 19345 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19346 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19347 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19348 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19349 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19350 {width="40",alignment="2",col_name="what",colhdr="What"}], 19351 body=[]} 19352 (gdb) 19353 19354 The `-break-disable' Command 19355 ---------------------------- 19356 19357 Synopsis 19358 ........ 19359 19360 -break-disable ( BREAKPOINT )+ 19361 19362 Disable the named BREAKPOINT(s). The field `enabled' in the break 19363 list is now set to `n' for the named BREAKPOINT(s). 19364 19365 GDB Command 19366 ........... 19367 19368 The corresponding GDB command is `disable'. 19369 19370 Example 19371 ....... 19372 19373 (gdb) 19374 -break-disable 2 19375 ^done 19376 (gdb) 19377 -break-list 19378 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 19379 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19380 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19381 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19382 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19383 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19384 {width="40",alignment="2",col_name="what",colhdr="What"}], 19385 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", 19386 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 19387 line="5",times="0"}]} 19388 (gdb) 19389 19390 The `-break-enable' Command 19391 --------------------------- 19392 19393 Synopsis 19394 ........ 19395 19396 -break-enable ( BREAKPOINT )+ 19397 19398 Enable (previously disabled) BREAKPOINT(s). 19399 19400 GDB Command 19401 ........... 19402 19403 The corresponding GDB command is `enable'. 19404 19405 Example 19406 ....... 19407 19408 (gdb) 19409 -break-enable 2 19410 ^done 19411 (gdb) 19412 -break-list 19413 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 19414 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19415 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19416 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19417 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19418 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19419 {width="40",alignment="2",col_name="what",colhdr="What"}], 19420 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", 19421 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 19422 line="5",times="0"}]} 19423 (gdb) 19424 19425 The `-break-info' Command 19426 ------------------------- 19427 19428 Synopsis 19429 ........ 19430 19431 -break-info BREAKPOINT 19432 19433 Get information about a single breakpoint. 19434 19435 GDB Command 19436 ........... 19437 19438 The corresponding GDB command is `info break BREAKPOINT'. 19439 19440 Example 19441 ....... 19442 19443 N.A. 19444 19445 The `-break-insert' Command 19446 --------------------------- 19447 19448 Synopsis 19449 ........ 19450 19451 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] 19452 [ -c CONDITION ] [ -i IGNORE-COUNT ] 19453 [ -p THREAD ] [ LOCATION ] 19454 19455 If specified, LOCATION, can be one of: 19456 19457 * function 19458 19459 * filename:linenum 19460 19461 * filename:function 19462 19463 * *address 19464 19465 The possible optional parameters of this command are: 19466 19467 `-t' 19468 Insert a temporary breakpoint. 19469 19470 `-h' 19471 Insert a hardware breakpoint. 19472 19473 `-c CONDITION' 19474 Make the breakpoint conditional on CONDITION. 19475 19476 `-i IGNORE-COUNT' 19477 Initialize the IGNORE-COUNT. 19478 19479 `-f' 19480 If LOCATION cannot be parsed (for example if it refers to unknown 19481 files or functions), create a pending breakpoint. Without this 19482 flag, GDB will report an error, and won't create a breakpoint, if 19483 LOCATION cannot be parsed. 19484 19485 `-d' 19486 Create a disabled breakpoint. 19487 19488 Result 19489 ...... 19490 19491 The result is in the form: 19492 19493 ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep", 19494 enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME", 19495 fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,] 19496 times="TIMES"} 19497 19498 where NUMBER is the GDB number for this breakpoint, FUNCNAME is the 19499 name of the function where the breakpoint was inserted, FILENAME is the 19500 name of the source file which contains this function, LINENO is the 19501 source line number within that file and TIMES the number of times that 19502 the breakpoint has been hit (always 0 for -break-insert but may be 19503 greater for -break-info or -break-list which use the same output). 19504 19505 Note: this format is open to change. 19506 19507 GDB Command 19508 ........... 19509 19510 The corresponding GDB commands are `break', `tbreak', `hbreak', 19511 `thbreak', and `rbreak'. 19512 19513 Example 19514 ....... 19515 19516 (gdb) 19517 -break-insert main 19518 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", 19519 fullname="/home/foo/recursive2.c,line="4",times="0"} 19520 (gdb) 19521 -break-insert -t foo 19522 ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", 19523 fullname="/home/foo/recursive2.c,line="11",times="0"} 19524 (gdb) 19525 -break-list 19526 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 19527 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19528 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19529 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19530 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19531 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19532 {width="40",alignment="2",col_name="what",colhdr="What"}], 19533 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 19534 addr="0x0001072c", func="main",file="recursive2.c", 19535 fullname="/home/foo/recursive2.c,"line="4",times="0"}, 19536 bkpt={number="2",type="breakpoint",disp="del",enabled="y", 19537 addr="0x00010774",func="foo",file="recursive2.c", 19538 fullname="/home/foo/recursive2.c",line="11",times="0"}]} 19539 (gdb) 19540 -break-insert -r foo.* 19541 ~int foo(int, int); 19542 ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c, 19543 "fullname="/home/foo/recursive2.c",line="11",times="0"} 19544 (gdb) 19545 19546 The `-break-list' Command 19547 ------------------------- 19548 19549 Synopsis 19550 ........ 19551 19552 -break-list 19553 19554 Displays the list of inserted breakpoints, showing the following 19555 fields: 19556 19557 `Number' 19558 number of the breakpoint 19559 19560 `Type' 19561 type of the breakpoint: `breakpoint' or `watchpoint' 19562 19563 `Disposition' 19564 should the breakpoint be deleted or disabled when it is hit: `keep' 19565 or `nokeep' 19566 19567 `Enabled' 19568 is the breakpoint enabled or no: `y' or `n' 19569 19570 `Address' 19571 memory location at which the breakpoint is set 19572 19573 `What' 19574 logical location of the breakpoint, expressed by function name, 19575 file name, line number 19576 19577 `Times' 19578 number of times the breakpoint has been hit 19579 19580 If there are no breakpoints or watchpoints, the `BreakpointTable' 19581 `body' field is an empty list. 19582 19583 GDB Command 19584 ........... 19585 19586 The corresponding GDB command is `info break'. 19587 19588 Example 19589 ....... 19590 19591 (gdb) 19592 -break-list 19593 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 19594 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19595 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19596 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19597 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19598 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19599 {width="40",alignment="2",col_name="what",colhdr="What"}], 19600 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 19601 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}, 19602 bkpt={number="2",type="breakpoint",disp="keep",enabled="y", 19603 addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", 19604 line="13",times="0"}]} 19605 (gdb) 19606 19607 Here's an example of the result when there are no breakpoints: 19608 19609 (gdb) 19610 -break-list 19611 ^done,BreakpointTable={nr_rows="0",nr_cols="6", 19612 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19613 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19614 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19615 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19616 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19617 {width="40",alignment="2",col_name="what",colhdr="What"}], 19618 body=[]} 19619 (gdb) 19620 19621 The `-break-watch' Command 19622 -------------------------- 19623 19624 Synopsis 19625 ........ 19626 19627 -break-watch [ -a | -r ] 19628 19629 Create a watchpoint. With the `-a' option it will create an 19630 "access" watchpoint, i.e., a watchpoint that triggers either on a read 19631 from or on a write to the memory location. With the `-r' option, the 19632 watchpoint created is a "read" watchpoint, i.e., it will trigger only 19633 when the memory location is accessed for reading. Without either of 19634 the options, the watchpoint created is a regular watchpoint, i.e., it 19635 will trigger when the memory location is accessed for writing. *Note 19636 Setting Watchpoints: Set Watchpoints. 19637 19638 Note that `-break-list' will report a single list of watchpoints and 19639 breakpoints inserted. 19640 19641 GDB Command 19642 ........... 19643 19644 The corresponding GDB commands are `watch', `awatch', and `rwatch'. 19645 19646 Example 19647 ....... 19648 19649 Setting a watchpoint on a variable in the `main' function: 19650 19651 (gdb) 19652 -break-watch x 19653 ^done,wpt={number="2",exp="x"} 19654 (gdb) 19655 -exec-continue 19656 ^running 19657 (gdb) 19658 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, 19659 value={old="-268439212",new="55"}, 19660 frame={func="main",args=[],file="recursive2.c", 19661 fullname="/home/foo/bar/recursive2.c",line="5"} 19662 (gdb) 19663 19664 Setting a watchpoint on a variable local to a function. GDB will 19665 stop the program execution twice: first for the variable changing 19666 value, then for the watchpoint going out of scope. 19667 19668 (gdb) 19669 -break-watch C 19670 ^done,wpt={number="5",exp="C"} 19671 (gdb) 19672 -exec-continue 19673 ^running 19674 (gdb) 19675 *stopped,reason="watchpoint-trigger", 19676 wpt={number="5",exp="C"},value={old="-276895068",new="3"}, 19677 frame={func="callee4",args=[], 19678 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19679 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} 19680 (gdb) 19681 -exec-continue 19682 ^running 19683 (gdb) 19684 *stopped,reason="watchpoint-scope",wpnum="5", 19685 frame={func="callee3",args=[{name="strarg", 19686 value="0x11940 \"A string argument.\""}], 19687 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19688 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} 19689 (gdb) 19690 19691 Listing breakpoints and watchpoints, at different points in the 19692 program execution. Note that once the watchpoint goes out of scope, it 19693 is deleted. 19694 19695 (gdb) 19696 -break-watch C 19697 ^done,wpt={number="2",exp="C"} 19698 (gdb) 19699 -break-list 19700 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 19701 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19702 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19703 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19704 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19705 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19706 {width="40",alignment="2",col_name="what",colhdr="What"}], 19707 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 19708 addr="0x00010734",func="callee4", 19709 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19710 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"}, 19711 bkpt={number="2",type="watchpoint",disp="keep", 19712 enabled="y",addr="",what="C",times="0"}]} 19713 (gdb) 19714 -exec-continue 19715 ^running 19716 (gdb) 19717 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, 19718 value={old="-276895068",new="3"}, 19719 frame={func="callee4",args=[], 19720 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19721 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} 19722 (gdb) 19723 -break-list 19724 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 19725 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19726 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19727 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19728 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19729 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19730 {width="40",alignment="2",col_name="what",colhdr="What"}], 19731 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 19732 addr="0x00010734",func="callee4", 19733 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19734 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, 19735 bkpt={number="2",type="watchpoint",disp="keep", 19736 enabled="y",addr="",what="C",times="-5"}]} 19737 (gdb) 19738 -exec-continue 19739 ^running 19740 ^done,reason="watchpoint-scope",wpnum="2", 19741 frame={func="callee3",args=[{name="strarg", 19742 value="0x11940 \"A string argument.\""}], 19743 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19744 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} 19745 (gdb) 19746 -break-list 19747 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 19748 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 19749 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 19750 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 19751 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 19752 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 19753 {width="40",alignment="2",col_name="what",colhdr="What"}], 19754 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 19755 addr="0x00010734",func="callee4", 19756 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 19757 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 19758 times="1"}]} 19759 (gdb) 19760 19761 19762 File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI 19763 19764 27.9 GDB/MI Program Context 19765 ============================ 19766 19767 The `-exec-arguments' Command 19768 ----------------------------- 19769 19770 Synopsis 19771 ........ 19772 19773 -exec-arguments ARGS 19774 19775 Set the inferior program arguments, to be used in the next 19776 `-exec-run'. 19777 19778 GDB Command 19779 ........... 19780 19781 The corresponding GDB command is `set args'. 19782 19783 Example 19784 ....... 19785 19786 (gdb) 19787 -exec-arguments -v word 19788 ^done 19789 (gdb) 19790 19791 The `-environment-cd' Command 19792 ----------------------------- 19793 19794 Synopsis 19795 ........ 19796 19797 -environment-cd PATHDIR 19798 19799 Set GDB's working directory. 19800 19801 GDB Command 19802 ........... 19803 19804 The corresponding GDB command is `cd'. 19805 19806 Example 19807 ....... 19808 19809 (gdb) 19810 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 19811 ^done 19812 (gdb) 19813 19814 The `-environment-directory' Command 19815 ------------------------------------ 19816 19817 Synopsis 19818 ........ 19819 19820 -environment-directory [ -r ] [ PATHDIR ]+ 19821 19822 Add directories PATHDIR to beginning of search path for source files. 19823 If the `-r' option is used, the search path is reset to the default 19824 search path. If directories PATHDIR are supplied in addition to the 19825 `-r' option, the search path is first reset and then addition occurs as 19826 normal. Multiple directories may be specified, separated by blanks. 19827 Specifying multiple directories in a single command results in the 19828 directories added to the beginning of the search path in the same order 19829 they were presented in the command. If blanks are needed as part of a 19830 directory name, double-quotes should be used around the name. In the 19831 command output, the path will show up separated by the system 19832 directory-separator character. The directory-separator character must 19833 not be used in any directory name. If no directories are specified, 19834 the current search path is displayed. 19835 19836 GDB Command 19837 ........... 19838 19839 The corresponding GDB command is `dir'. 19840 19841 Example 19842 ....... 19843 19844 (gdb) 19845 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 19846 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 19847 (gdb) 19848 -environment-directory "" 19849 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 19850 (gdb) 19851 -environment-directory -r /home/jjohnstn/src/gdb /usr/src 19852 ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" 19853 (gdb) 19854 -environment-directory -r 19855 ^done,source-path="$cdir:$cwd" 19856 (gdb) 19857 19858 The `-environment-path' Command 19859 ------------------------------- 19860 19861 Synopsis 19862 ........ 19863 19864 -environment-path [ -r ] [ PATHDIR ]+ 19865 19866 Add directories PATHDIR to beginning of search path for object files. 19867 If the `-r' option is used, the search path is reset to the original 19868 search path that existed at gdb start-up. If directories PATHDIR are 19869 supplied in addition to the `-r' option, the search path is first reset 19870 and then addition occurs as normal. Multiple directories may be 19871 specified, separated by blanks. Specifying multiple directories in a 19872 single command results in the directories added to the beginning of the 19873 search path in the same order they were presented in the command. If 19874 blanks are needed as part of a directory name, double-quotes should be 19875 used around the name. In the command output, the path will show up 19876 separated by the system directory-separator character. The 19877 directory-separator character must not be used in any directory name. 19878 If no directories are specified, the current path is displayed. 19879 19880 GDB Command 19881 ........... 19882 19883 The corresponding GDB command is `path'. 19884 19885 Example 19886 ....... 19887 19888 (gdb) 19889 -environment-path 19890 ^done,path="/usr/bin" 19891 (gdb) 19892 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin 19893 ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" 19894 (gdb) 19895 -environment-path -r /usr/local/bin 19896 ^done,path="/usr/local/bin:/usr/bin" 19897 (gdb) 19898 19899 The `-environment-pwd' Command 19900 ------------------------------ 19901 19902 Synopsis 19903 ........ 19904 19905 -environment-pwd 19906 19907 Show the current working directory. 19908 19909 GDB Command 19910 ........... 19911 19912 The corresponding GDB command is `pwd'. 19913 19914 Example 19915 ....... 19916 19917 (gdb) 19918 -environment-pwd 19919 ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" 19920 (gdb) 19921 19922 19923 File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Program Context, Up: GDB/MI 19924 19925 27.10 GDB/MI Thread Commands 19926 ============================ 19927 19928 The `-thread-info' Command 19929 -------------------------- 19930 19931 Synopsis 19932 ........ 19933 19934 -thread-info [ THREAD-ID ] 19935 19936 Reports information about either a specific thread, if the THREAD-ID 19937 parameter is present, or about all threads. When printing information 19938 about all threads, also reports the current thread. 19939 19940 GDB Command 19941 ........... 19942 19943 The `info thread' command prints the same information about all threads. 19944 19945 Example 19946 ....... 19947 19948 -thread-info 19949 ^done,threads=[ 19950 {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 19951 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, 19952 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 19953 frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], 19954 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}], 19955 current-thread-id="1" 19956 (gdb) 19957 19958 The `state' field may have the following values: 19959 19960 `stopped' 19961 The thread is stopped. Frame information is available for stopped 19962 threads. 19963 19964 `running' 19965 The thread is running. There's no frame information for running 19966 threads. 19967 19968 19969 The `-thread-list-ids' Command 19970 ------------------------------ 19971 19972 Synopsis 19973 ........ 19974 19975 -thread-list-ids 19976 19977 Produces a list of the currently known GDB thread ids. At the end 19978 of the list it also prints the total number of such threads. 19979 19980 This command is retained for historical reasons, the `-thread-info' 19981 command should be used instead. 19982 19983 GDB Command 19984 ........... 19985 19986 Part of `info threads' supplies the same information. 19987 19988 Example 19989 ....... 19990 19991 (gdb) 19992 -thread-list-ids 19993 ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, 19994 current-thread-id="1",number-of-threads="3" 19995 (gdb) 19996 19997 The `-thread-select' Command 19998 ---------------------------- 19999 20000 Synopsis 20001 ........ 20002 20003 -thread-select THREADNUM 20004 20005 Make THREADNUM the current thread. It prints the number of the new 20006 current thread, and the topmost frame for that thread. 20007 20008 This command is deprecated in favor of explicitly using the 20009 `--thread' option to each command. 20010 20011 GDB Command 20012 ........... 20013 20014 The corresponding GDB command is `thread'. 20015 20016 Example 20017 ....... 20018 20019 (gdb) 20020 -exec-next 20021 ^running 20022 (gdb) 20023 *stopped,reason="end-stepping-range",thread-id="2",line="187", 20024 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" 20025 (gdb) 20026 -thread-list-ids 20027 ^done, 20028 thread-ids={thread-id="3",thread-id="2",thread-id="1"}, 20029 number-of-threads="3" 20030 (gdb) 20031 -thread-select 3 20032 ^done,new-thread-id="3", 20033 frame={level="0",func="vprintf", 20034 args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, 20035 {name="arg",value="0x2"}],file="vprintf.c",line="31"} 20036 (gdb) 20037 20038 20039 File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Thread Commands, Up: GDB/MI 20040 20041 27.11 GDB/MI Program Execution 20042 ============================== 20043 20044 These are the asynchronous commands which generate the out-of-band 20045 record `*stopped'. Currently GDB only really executes asynchronously 20046 with remote targets and this interaction is mimicked in other cases. 20047 20048 The `-exec-continue' Command 20049 ---------------------------- 20050 20051 Synopsis 20052 ........ 20053 20054 -exec-continue [--reverse] [--all|--thread-group N] 20055 20056 Resumes the execution of the inferior program, which will continue 20057 to execute until it reaches a debugger stop event. If the `--reverse' 20058 option is specified, execution resumes in reverse until it reaches a 20059 stop event. Stop events may include 20060 * breakpoints or watchpoints 20061 20062 * signals or exceptions 20063 20064 * the end of the process (or its beginning under `--reverse') 20065 20066 * the end or beginning of a replay log if one is being used. 20067 In all-stop mode (*note All-Stop Mode::), may resume only one 20068 thread, or all threads, depending on the value of the 20069 `scheduler-locking' variable. If `--all' is specified, all threads 20070 will be resumed. The `--all' option is ignored in all-stop mode. If 20071 the `--thread-group' options is specified, then all threads in that 20072 thread group are resumed. 20073 20074 GDB Command 20075 ........... 20076 20077 The corresponding GDB corresponding is `continue'. 20078 20079 Example 20080 ....... 20081 20082 -exec-continue 20083 ^running 20084 (gdb) 20085 @Hello world 20086 *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ 20087 func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", 20088 line="13"} 20089 (gdb) 20090 20091 The `-exec-finish' Command 20092 -------------------------- 20093 20094 Synopsis 20095 ........ 20096 20097 -exec-finish [--reverse] 20098 20099 Resumes the execution of the inferior program until the current 20100 function is exited. Displays the results returned by the function. If 20101 the `--reverse' option is specified, resumes the reverse execution of 20102 the inferior program until the point where current function was called. 20103 20104 GDB Command 20105 ........... 20106 20107 The corresponding GDB command is `finish'. 20108 20109 Example 20110 ....... 20111 20112 Function returning `void'. 20113 20114 -exec-finish 20115 ^running 20116 (gdb) 20117 @hello from foo 20118 *stopped,reason="function-finished",frame={func="main",args=[], 20119 file="hello.c",fullname="/home/foo/bar/hello.c",line="7"} 20120 (gdb) 20121 20122 Function returning other than `void'. The name of the internal GDB 20123 variable storing the result is printed, together with the value itself. 20124 20125 -exec-finish 20126 ^running 20127 (gdb) 20128 *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", 20129 args=[{name="a",value="1"],{name="b",value="9"}}, 20130 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20131 gdb-result-var="$1",return-value="0" 20132 (gdb) 20133 20134 The `-exec-interrupt' Command 20135 ----------------------------- 20136 20137 Synopsis 20138 ........ 20139 20140 -exec-interrupt [--all|--thread-group N] 20141 20142 Interrupts the background execution of the target. Note how the 20143 token associated with the stop message is the one for the execution 20144 command that has been interrupted. The token for the interrupt itself 20145 only appears in the `^done' output. If the user is trying to interrupt 20146 a non-running program, an error message will be printed. 20147 20148 Note that when asynchronous execution is enabled, this command is 20149 asynchronous just like other execution commands. That is, first the 20150 `^done' response will be printed, and the target stop will be reported 20151 after that using the `*stopped' notification. 20152 20153 In non-stop mode, only the context thread is interrupted by default. 20154 All threads will be interrupted if the `--all' option is specified. If 20155 the `--thread-group' option is specified, all threads in that group 20156 will be interrupted. 20157 20158 GDB Command 20159 ........... 20160 20161 The corresponding GDB command is `interrupt'. 20162 20163 Example 20164 ....... 20165 20166 (gdb) 20167 111-exec-continue 20168 111^running 20169 20170 (gdb) 20171 222-exec-interrupt 20172 222^done 20173 (gdb) 20174 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", 20175 frame={addr="0x00010140",func="foo",args=[],file="try.c", 20176 fullname="/home/foo/bar/try.c",line="13"} 20177 (gdb) 20178 20179 (gdb) 20180 -exec-interrupt 20181 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." 20182 (gdb) 20183 20184 The `-exec-jump' Command 20185 ------------------------ 20186 20187 Synopsis 20188 ........ 20189 20190 -exec-jump LOCATION 20191 20192 Resumes execution of the inferior program at the location specified 20193 by parameter. *Note Specify Location::, for a description of the 20194 different forms of LOCATION. 20195 20196 GDB Command 20197 ........... 20198 20199 The corresponding GDB command is `jump'. 20200 20201 Example 20202 ....... 20203 20204 -exec-jump foo.c:10 20205 *running,thread-id="all" 20206 ^running 20207 20208 The `-exec-next' Command 20209 ------------------------ 20210 20211 Synopsis 20212 ........ 20213 20214 -exec-next [--reverse] 20215 20216 Resumes execution of the inferior program, stopping when the 20217 beginning of the next source line is reached. 20218 20219 If the `--reverse' option is specified, resumes reverse execution of 20220 the inferior program, stopping at the beginning of the previous source 20221 line. If you issue this command on the first line of a function, it 20222 will take you back to the caller of that function, to the source line 20223 where the function was called. 20224 20225 GDB Command 20226 ........... 20227 20228 The corresponding GDB command is `next'. 20229 20230 Example 20231 ....... 20232 20233 -exec-next 20234 ^running 20235 (gdb) 20236 *stopped,reason="end-stepping-range",line="8",file="hello.c" 20237 (gdb) 20238 20239 The `-exec-next-instruction' Command 20240 ------------------------------------ 20241 20242 Synopsis 20243 ........ 20244 20245 -exec-next-instruction [--reverse] 20246 20247 Executes one machine instruction. If the instruction is a function 20248 call, continues until the function returns. If the program stops at an 20249 instruction in the middle of a source line, the address will be printed 20250 as well. 20251 20252 If the `--reverse' option is specified, resumes reverse execution of 20253 the inferior program, stopping at the previous instruction. If the 20254 previously executed instruction was a return from another function, it 20255 will continue to execute in reverse until the call to that function 20256 (from the current stack frame) is reached. 20257 20258 GDB Command 20259 ........... 20260 20261 The corresponding GDB command is `nexti'. 20262 20263 Example 20264 ....... 20265 20266 (gdb) 20267 -exec-next-instruction 20268 ^running 20269 20270 (gdb) 20271 *stopped,reason="end-stepping-range", 20272 addr="0x000100d4",line="5",file="hello.c" 20273 (gdb) 20274 20275 The `-exec-return' Command 20276 -------------------------- 20277 20278 Synopsis 20279 ........ 20280 20281 -exec-return 20282 20283 Makes current function return immediately. Doesn't execute the 20284 inferior. Displays the new current frame. 20285 20286 GDB Command 20287 ........... 20288 20289 The corresponding GDB command is `return'. 20290 20291 Example 20292 ....... 20293 20294 (gdb) 20295 200-break-insert callee4 20296 200^done,bkpt={number="1",addr="0x00010734", 20297 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} 20298 (gdb) 20299 000-exec-run 20300 000^running 20301 (gdb) 20302 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 20303 frame={func="callee4",args=[], 20304 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 20305 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"} 20306 (gdb) 20307 205-break-delete 20308 205^done 20309 (gdb) 20310 111-exec-return 20311 111^done,frame={level="0",func="callee3", 20312 args=[{name="strarg", 20313 value="0x11940 \"A string argument.\""}], 20314 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 20315 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} 20316 (gdb) 20317 20318 The `-exec-run' Command 20319 ----------------------- 20320 20321 Synopsis 20322 ........ 20323 20324 -exec-run 20325 20326 Starts execution of the inferior from the beginning. The inferior 20327 executes until either a breakpoint is encountered or the program exits. 20328 In the latter case the output will include an exit code, if the 20329 program has exited exceptionally. 20330 20331 GDB Command 20332 ........... 20333 20334 The corresponding GDB command is `run'. 20335 20336 Examples 20337 ........ 20338 20339 (gdb) 20340 -break-insert main 20341 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} 20342 (gdb) 20343 -exec-run 20344 ^running 20345 (gdb) 20346 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 20347 frame={func="main",args=[],file="recursive2.c", 20348 fullname="/home/foo/bar/recursive2.c",line="4"} 20349 (gdb) 20350 20351 Program exited normally: 20352 20353 (gdb) 20354 -exec-run 20355 ^running 20356 (gdb) 20357 x = 55 20358 *stopped,reason="exited-normally" 20359 (gdb) 20360 20361 Program exited exceptionally: 20362 20363 (gdb) 20364 -exec-run 20365 ^running 20366 (gdb) 20367 x = 55 20368 *stopped,reason="exited",exit-code="01" 20369 (gdb) 20370 20371 Another way the program can terminate is if it receives a signal 20372 such as `SIGINT'. In this case, GDB/MI displays this: 20373 20374 (gdb) 20375 *stopped,reason="exited-signalled",signal-name="SIGINT", 20376 signal-meaning="Interrupt" 20377 20378 The `-exec-step' Command 20379 ------------------------ 20380 20381 Synopsis 20382 ........ 20383 20384 -exec-step [--reverse] 20385 20386 Resumes execution of the inferior program, stopping when the 20387 beginning of the next source line is reached, if the next source line 20388 is not a function call. If it is, stop at the first instruction of the 20389 called function. If the `--reverse' option is specified, resumes 20390 reverse execution of the inferior program, stopping at the beginning of 20391 the previously executed source line. 20392 20393 GDB Command 20394 ........... 20395 20396 The corresponding GDB command is `step'. 20397 20398 Example 20399 ....... 20400 20401 Stepping into a function: 20402 20403 -exec-step 20404 ^running 20405 (gdb) 20406 *stopped,reason="end-stepping-range", 20407 frame={func="foo",args=[{name="a",value="10"}, 20408 {name="b",value="0"}],file="recursive2.c", 20409 fullname="/home/foo/bar/recursive2.c",line="11"} 20410 (gdb) 20411 20412 Regular stepping: 20413 20414 -exec-step 20415 ^running 20416 (gdb) 20417 *stopped,reason="end-stepping-range",line="14",file="recursive2.c" 20418 (gdb) 20419 20420 The `-exec-step-instruction' Command 20421 ------------------------------------ 20422 20423 Synopsis 20424 ........ 20425 20426 -exec-step-instruction [--reverse] 20427 20428 Resumes the inferior which executes one machine instruction. If the 20429 `--reverse' option is specified, resumes reverse execution of the 20430 inferior program, stopping at the previously executed instruction. The 20431 output, once GDB has stopped, will vary depending on whether we have 20432 stopped in the middle of a source line or not. In the former case, the 20433 address at which the program stopped will be printed as well. 20434 20435 GDB Command 20436 ........... 20437 20438 The corresponding GDB command is `stepi'. 20439 20440 Example 20441 ....... 20442 20443 (gdb) 20444 -exec-step-instruction 20445 ^running 20446 20447 (gdb) 20448 *stopped,reason="end-stepping-range", 20449 frame={func="foo",args=[],file="try.c", 20450 fullname="/home/foo/bar/try.c",line="10"} 20451 (gdb) 20452 -exec-step-instruction 20453 ^running 20454 20455 (gdb) 20456 *stopped,reason="end-stepping-range", 20457 frame={addr="0x000100f4",func="foo",args=[],file="try.c", 20458 fullname="/home/foo/bar/try.c",line="10"} 20459 (gdb) 20460 20461 The `-exec-until' Command 20462 ------------------------- 20463 20464 Synopsis 20465 ........ 20466 20467 -exec-until [ LOCATION ] 20468 20469 Executes the inferior until the LOCATION specified in the argument 20470 is reached. If there is no argument, the inferior executes until a 20471 source line greater than the current one is reached. The reason for 20472 stopping in this case will be `location-reached'. 20473 20474 GDB Command 20475 ........... 20476 20477 The corresponding GDB command is `until'. 20478 20479 Example 20480 ....... 20481 20482 (gdb) 20483 -exec-until recursive2.c:6 20484 ^running 20485 (gdb) 20486 x = 55 20487 *stopped,reason="location-reached",frame={func="main",args=[], 20488 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"} 20489 (gdb) 20490 20491 20492 File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI 20493 20494 27.12 GDB/MI Stack Manipulation Commands 20495 ======================================== 20496 20497 The `-stack-info-frame' Command 20498 ------------------------------- 20499 20500 Synopsis 20501 ........ 20502 20503 -stack-info-frame 20504 20505 Get info on the selected frame. 20506 20507 GDB Command 20508 ........... 20509 20510 The corresponding GDB command is `info frame' or `frame' (without 20511 arguments). 20512 20513 Example 20514 ....... 20515 20516 (gdb) 20517 -stack-info-frame 20518 ^done,frame={level="1",addr="0x0001076c",func="callee3", 20519 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 20520 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"} 20521 (gdb) 20522 20523 The `-stack-info-depth' Command 20524 ------------------------------- 20525 20526 Synopsis 20527 ........ 20528 20529 -stack-info-depth [ MAX-DEPTH ] 20530 20531 Return the depth of the stack. If the integer argument MAX-DEPTH is 20532 specified, do not count beyond MAX-DEPTH frames. 20533 20534 GDB Command 20535 ........... 20536 20537 There's no equivalent GDB command. 20538 20539 Example 20540 ....... 20541 20542 For a stack with frame levels 0 through 11: 20543 20544 (gdb) 20545 -stack-info-depth 20546 ^done,depth="12" 20547 (gdb) 20548 -stack-info-depth 4 20549 ^done,depth="4" 20550 (gdb) 20551 -stack-info-depth 12 20552 ^done,depth="12" 20553 (gdb) 20554 -stack-info-depth 11 20555 ^done,depth="11" 20556 (gdb) 20557 -stack-info-depth 13 20558 ^done,depth="12" 20559 (gdb) 20560 20561 The `-stack-list-arguments' Command 20562 ----------------------------------- 20563 20564 Synopsis 20565 ........ 20566 20567 -stack-list-arguments PRINT-VALUES 20568 [ LOW-FRAME HIGH-FRAME ] 20569 20570 Display a list of the arguments for the frames between LOW-FRAME and 20571 HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, 20572 list the arguments for the whole call stack. If the two arguments are 20573 equal, show the single frame at the corresponding level. It is an 20574 error if LOW-FRAME is larger than the actual number of frames. On the 20575 other hand, HIGH-FRAME may be larger than the actual number of frames, 20576 in which case only existing frames will be returned. 20577 20578 If PRINT-VALUES is 0 or `--no-values', print only the names of the 20579 variables; if it is 1 or `--all-values', print also their values; and 20580 if it is 2 or `--simple-values', print the name, type and value for 20581 simple data types, and the name and type for arrays, structures and 20582 unions. 20583 20584 Use of this command to obtain arguments in a single frame is 20585 deprecated in favor of the `-stack-list-variables' command. 20586 20587 GDB Command 20588 ........... 20589 20590 GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args' 20591 command which partially overlaps with the functionality of 20592 `-stack-list-arguments'. 20593 20594 Example 20595 ....... 20596 20597 (gdb) 20598 -stack-list-frames 20599 ^done, 20600 stack=[ 20601 frame={level="0",addr="0x00010734",func="callee4", 20602 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 20603 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, 20604 frame={level="1",addr="0x0001076c",func="callee3", 20605 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 20606 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, 20607 frame={level="2",addr="0x0001078c",func="callee2", 20608 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 20609 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, 20610 frame={level="3",addr="0x000107b4",func="callee1", 20611 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 20612 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, 20613 frame={level="4",addr="0x000107e0",func="main", 20614 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 20615 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] 20616 (gdb) 20617 -stack-list-arguments 0 20618 ^done, 20619 stack-args=[ 20620 frame={level="0",args=[]}, 20621 frame={level="1",args=[name="strarg"]}, 20622 frame={level="2",args=[name="intarg",name="strarg"]}, 20623 frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, 20624 frame={level="4",args=[]}] 20625 (gdb) 20626 -stack-list-arguments 1 20627 ^done, 20628 stack-args=[ 20629 frame={level="0",args=[]}, 20630 frame={level="1", 20631 args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, 20632 frame={level="2",args=[ 20633 {name="intarg",value="2"}, 20634 {name="strarg",value="0x11940 \"A string argument.\""}]}, 20635 {frame={level="3",args=[ 20636 {name="intarg",value="2"}, 20637 {name="strarg",value="0x11940 \"A string argument.\""}, 20638 {name="fltarg",value="3.5"}]}, 20639 frame={level="4",args=[]}] 20640 (gdb) 20641 -stack-list-arguments 0 2 2 20642 ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] 20643 (gdb) 20644 -stack-list-arguments 1 2 2 20645 ^done,stack-args=[frame={level="2", 20646 args=[{name="intarg",value="2"}, 20647 {name="strarg",value="0x11940 \"A string argument.\""}]}] 20648 (gdb) 20649 20650 The `-stack-list-frames' Command 20651 -------------------------------- 20652 20653 Synopsis 20654 ........ 20655 20656 -stack-list-frames [ LOW-FRAME HIGH-FRAME ] 20657 20658 List the frames currently on the stack. For each frame it displays 20659 the following info: 20660 20661 `LEVEL' 20662 The frame number, 0 being the topmost frame, i.e., the innermost 20663 function. 20664 20665 `ADDR' 20666 The `$pc' value for that frame. 20667 20668 `FUNC' 20669 Function name. 20670 20671 `FILE' 20672 File name of the source file where the function lives. 20673 20674 `LINE' 20675 Line number corresponding to the `$pc'. 20676 20677 If invoked without arguments, this command prints a backtrace for the 20678 whole stack. If given two integer arguments, it shows the frames whose 20679 levels are between the two arguments (inclusive). If the two arguments 20680 are equal, it shows the single frame at the corresponding level. It is 20681 an error if LOW-FRAME is larger than the actual number of frames. On 20682 the other hand, HIGH-FRAME may be larger than the actual number of 20683 frames, in which case only existing frames will be returned. 20684 20685 GDB Command 20686 ........... 20687 20688 The corresponding GDB commands are `backtrace' and `where'. 20689 20690 Example 20691 ....... 20692 20693 Full stack backtrace: 20694 20695 (gdb) 20696 -stack-list-frames 20697 ^done,stack= 20698 [frame={level="0",addr="0x0001076c",func="foo", 20699 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"}, 20700 frame={level="1",addr="0x000107a4",func="foo", 20701 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20702 frame={level="2",addr="0x000107a4",func="foo", 20703 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20704 frame={level="3",addr="0x000107a4",func="foo", 20705 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20706 frame={level="4",addr="0x000107a4",func="foo", 20707 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20708 frame={level="5",addr="0x000107a4",func="foo", 20709 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20710 frame={level="6",addr="0x000107a4",func="foo", 20711 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20712 frame={level="7",addr="0x000107a4",func="foo", 20713 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20714 frame={level="8",addr="0x000107a4",func="foo", 20715 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20716 frame={level="9",addr="0x000107a4",func="foo", 20717 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20718 frame={level="10",addr="0x000107a4",func="foo", 20719 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20720 frame={level="11",addr="0x00010738",func="main", 20721 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}] 20722 (gdb) 20723 20724 Show frames between LOW_FRAME and HIGH_FRAME: 20725 20726 (gdb) 20727 -stack-list-frames 3 5 20728 ^done,stack= 20729 [frame={level="3",addr="0x000107a4",func="foo", 20730 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20731 frame={level="4",addr="0x000107a4",func="foo", 20732 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 20733 frame={level="5",addr="0x000107a4",func="foo", 20734 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] 20735 (gdb) 20736 20737 Show a single frame: 20738 20739 (gdb) 20740 -stack-list-frames 3 3 20741 ^done,stack= 20742 [frame={level="3",addr="0x000107a4",func="foo", 20743 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] 20744 (gdb) 20745 20746 The `-stack-list-locals' Command 20747 -------------------------------- 20748 20749 Synopsis 20750 ........ 20751 20752 -stack-list-locals PRINT-VALUES 20753 20754 Display the local variable names for the selected frame. If 20755 PRINT-VALUES is 0 or `--no-values', print only the names of the 20756 variables; if it is 1 or `--all-values', print also their values; and 20757 if it is 2 or `--simple-values', print the name, type and value for 20758 simple data types, and the name and type for arrays, structures and 20759 unions. In this last case, a frontend can immediately display the 20760 value of simple data types and create variable objects for other data 20761 types when the user wishes to explore their values in more detail. 20762 20763 This command is deprecated in favor of the `-stack-list-variables' 20764 command. 20765 20766 GDB Command 20767 ........... 20768 20769 `info locals' in GDB, `gdb_get_locals' in `gdbtk'. 20770 20771 Example 20772 ....... 20773 20774 (gdb) 20775 -stack-list-locals 0 20776 ^done,locals=[name="A",name="B",name="C"] 20777 (gdb) 20778 -stack-list-locals --all-values 20779 ^done,locals=[{name="A",value="1"},{name="B",value="2"}, 20780 {name="C",value="{1, 2, 3}"}] 20781 -stack-list-locals --simple-values 20782 ^done,locals=[{name="A",type="int",value="1"}, 20783 {name="B",type="int",value="2"},{name="C",type="int [3]"}] 20784 (gdb) 20785 20786 The `-stack-list-variables' Command 20787 ----------------------------------- 20788 20789 Synopsis 20790 ........ 20791 20792 -stack-list-variables PRINT-VALUES 20793 20794 Display the names of local variables and function arguments for the 20795 selected frame. If PRINT-VALUES is 0 or `--no-values', print only the 20796 names of the variables; if it is 1 or `--all-values', print also their 20797 values; and if it is 2 or `--simple-values', print the name, type and 20798 value for simple data types, and the name and type for arrays, 20799 structures and unions. 20800 20801 Example 20802 ....... 20803 20804 (gdb) 20805 -stack-list-variables --thread 1 --frame 0 --all-values 20806 ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] 20807 (gdb) 20808 20809 The `-stack-select-frame' Command 20810 --------------------------------- 20811 20812 Synopsis 20813 ........ 20814 20815 -stack-select-frame FRAMENUM 20816 20817 Change the selected frame. Select a different frame FRAMENUM on the 20818 stack. 20819 20820 This command in deprecated in favor of passing the `--frame' option 20821 to every command. 20822 20823 GDB Command 20824 ........... 20825 20826 The corresponding GDB commands are `frame', `up', `down', 20827 `select-frame', `up-silent', and `down-silent'. 20828 20829 Example 20830 ....... 20831 20832 (gdb) 20833 -stack-select-frame 2 20834 ^done 20835 (gdb) 20836 20837 20838 File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI 20839 20840 27.13 GDB/MI Variable Objects 20841 ============================= 20842 20843 Introduction to Variable Objects 20844 -------------------------------- 20845 20846 Variable objects are "object-oriented" MI interface for examining and 20847 changing values of expressions. Unlike some other MI interfaces that 20848 work with expressions, variable objects are specifically designed for 20849 simple and efficient presentation in the frontend. A variable object 20850 is identified by string name. When a variable object is created, the 20851 frontend specifies the expression for that variable object. The 20852 expression can be a simple variable, or it can be an arbitrary complex 20853 expression, and can even involve CPU registers. After creating a 20854 variable object, the frontend can invoke other variable object 20855 operations--for example to obtain or change the value of a variable 20856 object, or to change display format. 20857 20858 Variable objects have hierarchical tree structure. Any variable 20859 object that corresponds to a composite type, such as structure in C, has 20860 a number of child variable objects, for example corresponding to each 20861 element of a structure. A child variable object can itself have 20862 children, recursively. Recursion ends when we reach leaf variable 20863 objects, which always have built-in types. Child variable objects are 20864 created only by explicit request, so if a frontend is not interested in 20865 the children of a particular variable object, no child will be created. 20866 20867 For a leaf variable object it is possible to obtain its value as a 20868 string, or set the value from a string. String value can be also 20869 obtained for a non-leaf variable object, but it's generally a string 20870 that only indicates the type of the object, and does not list its 20871 contents. Assignment to a non-leaf variable object is not allowed. 20872 20873 A frontend does not need to read the values of all variable objects 20874 each time the program stops. Instead, MI provides an update command 20875 that lists all variable objects whose values has changed since the last 20876 update operation. This considerably reduces the amount of data that 20877 must be transferred to the frontend. As noted above, children variable 20878 objects are created on demand, and only leaf variable objects have a 20879 real value. As result, gdb will read target memory only for leaf 20880 variables that frontend has created. 20881 20882 The automatic update is not always desirable. For example, a 20883 frontend might want to keep a value of some expression for future 20884 reference, and never update it. For another example, fetching memory 20885 is relatively slow for embedded targets, so a frontend might want to 20886 disable automatic update for the variables that are either not visible 20887 on the screen, or "closed". This is possible using so called "frozen 20888 variable objects". Such variable objects are never implicitly updated. 20889 20890 Variable objects can be either "fixed" or "floating". For the fixed 20891 variable object, the expression is parsed when the variable object is 20892 created, including associating identifiers to specific variables. The 20893 meaning of expression never changes. For a floating variable object 20894 the values of variables whose names appear in the expressions are 20895 re-evaluated every time in the context of the current frame. Consider 20896 this example: 20897 20898 void do_work(...) 20899 { 20900 struct work_state state; 20901 20902 if (...) 20903 do_work(...); 20904 } 20905 20906 If a fixed variable object for the `state' variable is created in 20907 this function, and we enter the recursive call, the the variable object 20908 will report the value of `state' in the top-level `do_work' invocation. 20909 On the other hand, a floating variable object will report the value of 20910 `state' in the current frame. 20911 20912 If an expression specified when creating a fixed variable object 20913 refers to a local variable, the variable object becomes bound to the 20914 thread and frame in which the variable object is created. When such 20915 variable object is updated, GDB makes sure that the thread/frame 20916 combination the variable object is bound to still exists, and 20917 re-evaluates the variable object in context of that thread/frame. 20918 20919 The following is the complete set of GDB/MI operations defined to 20920 access this functionality: 20921 20922 *Operation* *Description* 20923 `-enable-pretty-printing' enable Python-based pretty-printing 20924 `-var-create' create a variable object 20925 `-var-delete' delete the variable object and/or its 20926 children 20927 `-var-set-format' set the display format of this variable 20928 `-var-show-format' show the display format of this variable 20929 `-var-info-num-children' tells how many children this object has 20930 `-var-list-children' return a list of the object's children 20931 `-var-info-type' show the type of this variable object 20932 `-var-info-expression' print parent-relative expression that this 20933 variable object represents 20934 `-var-info-path-expression' print full expression that this variable 20935 object represents 20936 `-var-show-attributes' is this variable editable? does it exist 20937 here? 20938 `-var-evaluate-expression' get the value of this variable 20939 `-var-assign' set the value of this variable 20940 `-var-update' update the variable and its children 20941 `-var-set-frozen' set frozeness attribute 20942 `-var-set-update-range' set range of children to display on update 20943 20944 In the next subsection we describe each operation in detail and 20945 suggest how it can be used. 20946 20947 Description And Use of Operations on Variable Objects 20948 ----------------------------------------------------- 20949 20950 The `-enable-pretty-printing' Command 20951 ------------------------------------- 20952 20953 -enable-pretty-printing 20954 20955 GDB allows Python-based visualizers to affect the output of the MI 20956 variable object commands. However, because there was no way to 20957 implement this in a fully backward-compatible way, a front end must 20958 request that this functionality be enabled. 20959 20960 Once enabled, this feature cannot be disabled. 20961 20962 Note that if Python support has not been compiled into GDB, this 20963 command will still succeed (and do nothing). 20964 20965 This feature is currently (as of GDB 7.0) experimental, and may work 20966 differently in future versions of GDB. 20967 20968 The `-var-create' Command 20969 ------------------------- 20970 20971 Synopsis 20972 ........ 20973 20974 -var-create {NAME | "-"} 20975 {FRAME-ADDR | "*" | "@"} EXPRESSION 20976 20977 This operation creates a variable object, which allows the 20978 monitoring of a variable, the result of an expression, a memory cell or 20979 a CPU register. 20980 20981 The NAME parameter is the string by which the object can be 20982 referenced. It must be unique. If `-' is specified, the varobj system 20983 will generate a string "varNNNNNN" automatically. It will be unique 20984 provided that one does not specify NAME of that format. The command 20985 fails if a duplicate name is found. 20986 20987 The frame under which the expression should be evaluated can be 20988 specified by FRAME-ADDR. A `*' indicates that the current frame should 20989 be used. A `@' indicates that a floating variable object must be 20990 created. 20991 20992 EXPRESSION is any expression valid on the current language set (must 20993 not begin with a `*'), or one of the following: 20994 20995 * `*ADDR', where ADDR is the address of a memory cell 20996 20997 * `*ADDR-ADDR' -- a memory address range (TBD) 20998 20999 * `$REGNAME' -- a CPU register name 21000 21001 A varobj's contents may be provided by a Python-based 21002 pretty-printer. In this case the varobj is known as a "dynamic 21003 varobj". Dynamic varobjs have slightly different semantics in some 21004 cases. If the `-enable-pretty-printing' command is not sent, then GDB 21005 will never create a dynamic varobj. This ensures backward 21006 compatibility for existing clients. 21007 21008 Result 21009 ...... 21010 21011 This operation returns attributes of the newly-created varobj. These 21012 are: 21013 21014 `name' 21015 The name of the varobj. 21016 21017 `numchild' 21018 The number of children of the varobj. This number is not 21019 necessarily reliable for a dynamic varobj. Instead, you must 21020 examine the `has_more' attribute. 21021 21022 `value' 21023 The varobj's scalar value. For a varobj whose type is some sort of 21024 aggregate (e.g., a `struct'), or for a dynamic varobj, this value 21025 will not be interesting. 21026 21027 `type' 21028 The varobj's type. This is a string representation of the type, as 21029 would be printed by the GDB CLI. 21030 21031 `thread-id' 21032 If a variable object is bound to a specific thread, then this is 21033 the thread's identifier. 21034 21035 `has_more' 21036 For a dynamic varobj, this indicates whether there appear to be any 21037 children available. For a non-dynamic varobj, this will be 0. 21038 21039 `dynamic' 21040 This attribute will be present and have the value `1' if the 21041 varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 21042 then this attribute will not be present. 21043 21044 `displayhint' 21045 A dynamic varobj can supply a display hint to the front end. The 21046 value comes directly from the Python pretty-printer object's 21047 `display_hint' method. *Note Pretty Printing::. 21048 21049 Typical output will look like this: 21050 21051 name="NAME",numchild="N",type="TYPE",thread-id="M", 21052 has_more="HAS_MORE" 21053 21054 The `-var-delete' Command 21055 ------------------------- 21056 21057 Synopsis 21058 ........ 21059 21060 -var-delete [ -c ] NAME 21061 21062 Deletes a previously created variable object and all of its children. 21063 With the `-c' option, just deletes the children. 21064 21065 Returns an error if the object NAME is not found. 21066 21067 The `-var-set-format' Command 21068 ----------------------------- 21069 21070 Synopsis 21071 ........ 21072 21073 -var-set-format NAME FORMAT-SPEC 21074 21075 Sets the output format for the value of the object NAME to be 21076 FORMAT-SPEC. 21077 21078 The syntax for the FORMAT-SPEC is as follows: 21079 21080 FORMAT-SPEC ==> 21081 {binary | decimal | hexadecimal | octal | natural} 21082 21083 The natural format is the default format choosen automatically based 21084 on the variable type (like decimal for an `int', hex for pointers, 21085 etc.). 21086 21087 For a variable with children, the format is set only on the variable 21088 itself, and the children are not affected. 21089 21090 The `-var-show-format' Command 21091 ------------------------------ 21092 21093 Synopsis 21094 ........ 21095 21096 -var-show-format NAME 21097 21098 Returns the format used to display the value of the object NAME. 21099 21100 FORMAT ==> 21101 FORMAT-SPEC 21102 21103 The `-var-info-num-children' Command 21104 ------------------------------------ 21105 21106 Synopsis 21107 ........ 21108 21109 -var-info-num-children NAME 21110 21111 Returns the number of children of a variable object NAME: 21112 21113 numchild=N 21114 21115 Note that this number is not completely reliable for a dynamic 21116 varobj. It will return the current number of children, but more 21117 children may be available. 21118 21119 The `-var-list-children' Command 21120 -------------------------------- 21121 21122 Synopsis 21123 ........ 21124 21125 -var-list-children [PRINT-VALUES] NAME [FROM TO] 21126 21127 Return a list of the children of the specified variable object and 21128 create variable objects for them, if they do not already exist. With a 21129 single argument or if PRINT-VALUES has a value for of 0 or 21130 `--no-values', print only the names of the variables; if PRINT-VALUES 21131 is 1 or `--all-values', also print their values; and if it is 2 or 21132 `--simple-values' print the name and value for simple data types and 21133 just the name for arrays, structures and unions. 21134 21135 FROM and TO, if specified, indicate the range of children to report. 21136 If FROM or TO is less than zero, the range is reset and all children 21137 will be reported. Otherwise, children starting at FROM (zero-based) 21138 and up to and excluding TO will be reported. 21139 21140 If a child range is requested, it will only affect the current call 21141 to `-var-list-children', but not future calls to `-var-update'. For 21142 this, you must instead use `-var-set-update-range'. The intent of this 21143 approach is to enable a front end to implement any update approach it 21144 likes; for example, scrolling a view may cause the front end to request 21145 more children with `-var-list-children', and then the front end could 21146 call `-var-set-update-range' with a different range to ensure that 21147 future updates are restricted to just the visible items. 21148 21149 For each child the following results are returned: 21150 21151 NAME 21152 Name of the variable object created for this child. 21153 21154 EXP 21155 The expression to be shown to the user by the front end to 21156 designate this child. For example this may be the name of a 21157 structure member. 21158 21159 For a dynamic varobj, this value cannot be used to form an 21160 expression. There is no way to do this at all with a dynamic 21161 varobj. 21162 21163 For C/C++ structures there are several pseudo children returned to 21164 designate access qualifiers. For these pseudo children EXP is 21165 `public', `private', or `protected'. In this case the type and 21166 value are not present. 21167 21168 A dynamic varobj will not report the access qualifying 21169 pseudo-children, regardless of the language. This information is 21170 not available at all with a dynamic varobj. 21171 21172 NUMCHILD 21173 Number of children this child has. For a dynamic varobj, this 21174 will be 0. 21175 21176 TYPE 21177 The type of the child. 21178 21179 VALUE 21180 If values were requested, this is the value. 21181 21182 THREAD-ID 21183 If this variable object is associated with a thread, this is the 21184 thread id. Otherwise this result is not present. 21185 21186 FROZEN 21187 If the variable object is frozen, this variable will be present 21188 with a value of 1. 21189 21190 The result may have its own attributes: 21191 21192 `displayhint' 21193 A dynamic varobj can supply a display hint to the front end. The 21194 value comes directly from the Python pretty-printer object's 21195 `display_hint' method. *Note Pretty Printing::. 21196 21197 `has_more' 21198 This is an integer attribute which is nonzero if there are children 21199 remaining after the end of the selected range. 21200 21201 Example 21202 ....... 21203 21204 (gdb) 21205 -var-list-children n 21206 ^done,numchild=N,children=[child={name=NAME,exp=EXP, 21207 numchild=N,type=TYPE},(repeats N times)] 21208 (gdb) 21209 -var-list-children --all-values n 21210 ^done,numchild=N,children=[child={name=NAME,exp=EXP, 21211 numchild=N,value=VALUE,type=TYPE},(repeats N times)] 21212 21213 The `-var-info-type' Command 21214 ---------------------------- 21215 21216 Synopsis 21217 ........ 21218 21219 -var-info-type NAME 21220 21221 Returns the type of the specified variable NAME. The type is 21222 returned as a string in the same format as it is output by the GDB CLI: 21223 21224 type=TYPENAME 21225 21226 The `-var-info-expression' Command 21227 ---------------------------------- 21228 21229 Synopsis 21230 ........ 21231 21232 -var-info-expression NAME 21233 21234 Returns a string that is suitable for presenting this variable 21235 object in user interface. The string is generally not valid expression 21236 in the current language, and cannot be evaluated. 21237 21238 For example, if `a' is an array, and variable object `A' was created 21239 for `a', then we'll get this output: 21240 21241 (gdb) -var-info-expression A.1 21242 ^done,lang="C",exp="1" 21243 21244 Here, the values of `lang' can be `{"C" | "C++" | "Java"}'. 21245 21246 Note that the output of the `-var-list-children' command also 21247 includes those expressions, so the `-var-info-expression' command is of 21248 limited use. 21249 21250 The `-var-info-path-expression' Command 21251 --------------------------------------- 21252 21253 Synopsis 21254 ........ 21255 21256 -var-info-path-expression NAME 21257 21258 Returns an expression that can be evaluated in the current context 21259 and will yield the same value that a variable object has. Compare this 21260 with the `-var-info-expression' command, which result can be used only 21261 for UI presentation. Typical use of the `-var-info-path-expression' 21262 command is creating a watchpoint from a variable object. 21263 21264 This command is currently not valid for children of a dynamic varobj, 21265 and will give an error when invoked on one. 21266 21267 For example, suppose `C' is a C++ class, derived from class `Base', 21268 and that the `Base' class has a member called `m_size'. Assume a 21269 variable `c' is has the type of `C' and a variable object `C' was 21270 created for variable `c'. Then, we'll get this output: 21271 (gdb) -var-info-path-expression C.Base.public.m_size 21272 ^done,path_expr=((Base)c).m_size) 21273 21274 The `-var-show-attributes' Command 21275 ---------------------------------- 21276 21277 Synopsis 21278 ........ 21279 21280 -var-show-attributes NAME 21281 21282 List attributes of the specified variable object NAME: 21283 21284 status=ATTR [ ( ,ATTR )* ] 21285 21286 where ATTR is `{ { editable | noneditable } | TBD }'. 21287 21288 The `-var-evaluate-expression' Command 21289 -------------------------------------- 21290 21291 Synopsis 21292 ........ 21293 21294 -var-evaluate-expression [-f FORMAT-SPEC] NAME 21295 21296 Evaluates the expression that is represented by the specified 21297 variable object and returns its value as a string. The format of the 21298 string can be specified with the `-f' option. The possible values of 21299 this option are the same as for `-var-set-format' (*note 21300 -var-set-format::). If the `-f' option is not specified, the current 21301 display format will be used. The current display format can be changed 21302 using the `-var-set-format' command. 21303 21304 value=VALUE 21305 21306 Note that one must invoke `-var-list-children' for a variable before 21307 the value of a child variable can be evaluated. 21308 21309 The `-var-assign' Command 21310 ------------------------- 21311 21312 Synopsis 21313 ........ 21314 21315 -var-assign NAME EXPRESSION 21316 21317 Assigns the value of EXPRESSION to the variable object specified by 21318 NAME. The object must be `editable'. If the variable's value is 21319 altered by the assign, the variable will show up in any subsequent 21320 `-var-update' list. 21321 21322 Example 21323 ....... 21324 21325 (gdb) 21326 -var-assign var1 3 21327 ^done,value="3" 21328 (gdb) 21329 -var-update * 21330 ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] 21331 (gdb) 21332 21333 The `-var-update' Command 21334 ------------------------- 21335 21336 Synopsis 21337 ........ 21338 21339 -var-update [PRINT-VALUES] {NAME | "*"} 21340 21341 Reevaluate the expressions corresponding to the variable object NAME 21342 and all its direct and indirect children, and return the list of 21343 variable objects whose values have changed; NAME must be a root 21344 variable object. Here, "changed" means that the result of 21345 `-var-evaluate-expression' before and after the `-var-update' is 21346 different. If `*' is used as the variable object names, all existing 21347 variable objects are updated, except for frozen ones (*note 21348 -var-set-frozen::). The option PRINT-VALUES determines whether both 21349 names and values, or just names are printed. The possible values of 21350 this option are the same as for `-var-list-children' (*note 21351 -var-list-children::). It is recommended to use the `--all-values' 21352 option, to reduce the number of MI commands needed on each program stop. 21353 21354 With the `*' parameter, if a variable object is bound to a currently 21355 running thread, it will not be updated, without any diagnostic. 21356 21357 If `-var-set-update-range' was previously used on a varobj, then 21358 only the selected range of children will be reported. 21359 21360 `-var-update' reports all the changed varobjs in a tuple named 21361 `changelist'. 21362 21363 Each item in the change list is itself a tuple holding: 21364 21365 `name' 21366 The name of the varobj. 21367 21368 `value' 21369 If values were requested for this update, then this field will be 21370 present and will hold the value of the varobj. 21371 21372 `in_scope' 21373 This field is a string which may take one of three values: 21374 21375 `"true"' 21376 The variable object's current value is valid. 21377 21378 `"false"' 21379 The variable object does not currently hold a valid value but 21380 it may hold one in the future if its associated expression 21381 comes back into scope. 21382 21383 `"invalid"' 21384 The variable object no longer holds a valid value. This can 21385 occur when the executable file being debugged has changed, 21386 either through recompilation or by using the GDB `file' 21387 command. The front end should normally choose to delete 21388 these variable objects. 21389 21390 In the future new values may be added to this list so the front 21391 should be prepared for this possibility. *Note GDB/MI Development 21392 and Front Ends: GDB/MI Development and Front Ends. 21393 21394 `type_changed' 21395 This is only present if the varobj is still valid. If the type 21396 changed, then this will be the string `true'; otherwise it will be 21397 `false'. 21398 21399 `new_type' 21400 If the varobj's type changed, then this field will be present and 21401 will hold the new type. 21402 21403 `new_num_children' 21404 For a dynamic varobj, if the number of children changed, or if the 21405 type changed, this will be the new number of children. 21406 21407 The `numchild' field in other varobj responses is generally not 21408 valid for a dynamic varobj - it will show the number of children 21409 that GDB knows about, but because dynamic varobjs lazily 21410 instantiate their children, this will not reflect the number of 21411 children which may be available. 21412 21413 The `new_num_children' attribute only reports changes to the 21414 number of children known by GDB. This is the only way to detect 21415 whether an update has removed children (which necessarily can only 21416 happen at the end of the update range). 21417 21418 `displayhint' 21419 The display hint, if any. 21420 21421 `has_more' 21422 This is an integer value, which will be 1 if there are more 21423 children available outside the varobj's update range. 21424 21425 `dynamic' 21426 This attribute will be present and have the value `1' if the 21427 varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 21428 then this attribute will not be present. 21429 21430 `new_children' 21431 If new children were added to a dynamic varobj within the selected 21432 update range (as set by `-var-set-update-range'), then they will 21433 be listed in this attribute. 21434 21435 Example 21436 ....... 21437 21438 (gdb) 21439 -var-assign var1 3 21440 ^done,value="3" 21441 (gdb) 21442 -var-update --all-values var1 21443 ^done,changelist=[{name="var1",value="3",in_scope="true", 21444 type_changed="false"}] 21445 (gdb) 21446 21447 The `-var-set-frozen' Command 21448 ----------------------------- 21449 21450 Synopsis 21451 ........ 21452 21453 -var-set-frozen NAME FLAG 21454 21455 Set the frozenness flag on the variable object NAME. The FLAG 21456 parameter should be either `1' to make the variable frozen or `0' to 21457 make it unfrozen. If a variable object is frozen, then neither itself, 21458 nor any of its children, are implicitly updated by `-var-update' of a 21459 parent variable or by `-var-update *'. Only `-var-update' of the 21460 variable itself will update its value and values of its children. 21461 After a variable object is unfrozen, it is implicitly updated by all 21462 subsequent `-var-update' operations. Unfreezing a variable does not 21463 update it, only subsequent `-var-update' does. 21464 21465 Example 21466 ....... 21467 21468 (gdb) 21469 -var-set-frozen V 1 21470 ^done 21471 (gdb) 21472 21473 The `-var-set-update-range' command 21474 ----------------------------------- 21475 21476 Synopsis 21477 ........ 21478 21479 -var-set-update-range NAME FROM TO 21480 21481 Set the range of children to be returned by future invocations of 21482 `-var-update'. 21483 21484 FROM and TO indicate the range of children to report. If FROM or TO 21485 is less than zero, the range is reset and all children will be 21486 reported. Otherwise, children starting at FROM (zero-based) and up to 21487 and excluding TO will be reported. 21488 21489 Example 21490 ....... 21491 21492 (gdb) 21493 -var-set-update-range V 1 2 21494 ^done 21495 21496 The `-var-set-visualizer' command 21497 --------------------------------- 21498 21499 Synopsis 21500 ........ 21501 21502 -var-set-visualizer NAME VISUALIZER 21503 21504 Set a visualizer for the variable object NAME. 21505 21506 VISUALIZER is the visualizer to use. The special value `None' means 21507 to disable any visualizer in use. 21508 21509 If not `None', VISUALIZER must be a Python expression. This 21510 expression must evaluate to a callable object which accepts a single 21511 argument. GDB will call this object with the value of the varobj NAME 21512 as an argument (this is done so that the same Python pretty-printing 21513 code can be used for both the CLI and MI). When called, this object 21514 must return an object which conforms to the pretty-printing interface 21515 (*note Pretty Printing::). 21516 21517 The pre-defined function `gdb.default_visualizer' may be used to 21518 select a visualizer by following the built-in process (*note Selecting 21519 Pretty-Printers::). This is done automatically when a varobj is 21520 created, and so ordinarily is not needed. 21521 21522 This feature is only available if Python support is enabled. The MI 21523 command `-list-features' (*note GDB/MI Miscellaneous Commands::) can be 21524 used to check this. 21525 21526 Example 21527 ....... 21528 21529 Resetting the visualizer: 21530 21531 (gdb) 21532 -var-set-visualizer V None 21533 ^done 21534 21535 Reselecting the default (type-based) visualizer: 21536 21537 (gdb) 21538 -var-set-visualizer V gdb.default_visualizer 21539 ^done 21540 21541 Suppose `SomeClass' is a visualizer class. A lambda expression can 21542 be used to instantiate this class for a varobj: 21543 21544 (gdb) 21545 -var-set-visualizer V "lambda val: SomeClass()" 21546 ^done 21547 21548 21549 File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI 21550 21551 27.14 GDB/MI Data Manipulation 21552 ============================== 21553 21554 This section describes the GDB/MI commands that manipulate data: 21555 examine memory and registers, evaluate expressions, etc. 21556 21557 The `-data-disassemble' Command 21558 ------------------------------- 21559 21560 Synopsis 21561 ........ 21562 21563 -data-disassemble 21564 [ -s START-ADDR -e END-ADDR ] 21565 | [ -f FILENAME -l LINENUM [ -n LINES ] ] 21566 -- MODE 21567 21568 Where: 21569 21570 `START-ADDR' 21571 is the beginning address (or `$pc') 21572 21573 `END-ADDR' 21574 is the end address 21575 21576 `FILENAME' 21577 is the name of the file to disassemble 21578 21579 `LINENUM' 21580 is the line number to disassemble around 21581 21582 `LINES' 21583 is the number of disassembly lines to be produced. If it is -1, 21584 the whole function will be disassembled, in case no END-ADDR is 21585 specified. If END-ADDR is specified as a non-zero value, and 21586 LINES is lower than the number of disassembly lines between 21587 START-ADDR and END-ADDR, only LINES lines are displayed; if LINES 21588 is higher than the number of lines between START-ADDR and 21589 END-ADDR, only the lines up to END-ADDR are displayed. 21590 21591 `MODE' 21592 is either 0 (meaning only disassembly) or 1 (meaning mixed source 21593 and disassembly). 21594 21595 Result 21596 ...... 21597 21598 The output for each instruction is composed of four fields: 21599 21600 * Address 21601 21602 * Func-name 21603 21604 * Offset 21605 21606 * Instruction 21607 21608 Note that whatever included in the instruction field, is not 21609 manipulated directly by GDB/MI, i.e., it is not possible to adjust its 21610 format. 21611 21612 GDB Command 21613 ........... 21614 21615 There's no direct mapping from this command to the CLI. 21616 21617 Example 21618 ....... 21619 21620 Disassemble from the current value of `$pc' to `$pc + 20': 21621 21622 (gdb) 21623 -data-disassemble -s $pc -e "$pc + 20" -- 0 21624 ^done, 21625 asm_insns=[ 21626 {address="0x000107c0",func-name="main",offset="4", 21627 inst="mov 2, %o0"}, 21628 {address="0x000107c4",func-name="main",offset="8", 21629 inst="sethi %hi(0x11800), %o2"}, 21630 {address="0x000107c8",func-name="main",offset="12", 21631 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, 21632 {address="0x000107cc",func-name="main",offset="16", 21633 inst="sethi %hi(0x11800), %o2"}, 21634 {address="0x000107d0",func-name="main",offset="20", 21635 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] 21636 (gdb) 21637 21638 Disassemble the whole `main' function. Line 32 is part of `main'. 21639 21640 -data-disassemble -f basics.c -l 32 -- 0 21641 ^done,asm_insns=[ 21642 {address="0x000107bc",func-name="main",offset="0", 21643 inst="save %sp, -112, %sp"}, 21644 {address="0x000107c0",func-name="main",offset="4", 21645 inst="mov 2, %o0"}, 21646 {address="0x000107c4",func-name="main",offset="8", 21647 inst="sethi %hi(0x11800), %o2"}, 21648 [...] 21649 {address="0x0001081c",func-name="main",offset="96",inst="ret "}, 21650 {address="0x00010820",func-name="main",offset="100",inst="restore "}] 21651 (gdb) 21652 21653 Disassemble 3 instructions from the start of `main': 21654 21655 (gdb) 21656 -data-disassemble -f basics.c -l 32 -n 3 -- 0 21657 ^done,asm_insns=[ 21658 {address="0x000107bc",func-name="main",offset="0", 21659 inst="save %sp, -112, %sp"}, 21660 {address="0x000107c0",func-name="main",offset="4", 21661 inst="mov 2, %o0"}, 21662 {address="0x000107c4",func-name="main",offset="8", 21663 inst="sethi %hi(0x11800), %o2"}] 21664 (gdb) 21665 21666 Disassemble 3 instructions from the start of `main' in mixed mode: 21667 21668 (gdb) 21669 -data-disassemble -f basics.c -l 32 -n 3 -- 1 21670 ^done,asm_insns=[ 21671 src_and_asm_line={line="31", 21672 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 21673 testsuite/gdb.mi/basics.c",line_asm_insn=[ 21674 {address="0x000107bc",func-name="main",offset="0", 21675 inst="save %sp, -112, %sp"}]}, 21676 src_and_asm_line={line="32", 21677 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 21678 testsuite/gdb.mi/basics.c",line_asm_insn=[ 21679 {address="0x000107c0",func-name="main",offset="4", 21680 inst="mov 2, %o0"}, 21681 {address="0x000107c4",func-name="main",offset="8", 21682 inst="sethi %hi(0x11800), %o2"}]}] 21683 (gdb) 21684 21685 The `-data-evaluate-expression' Command 21686 --------------------------------------- 21687 21688 Synopsis 21689 ........ 21690 21691 -data-evaluate-expression EXPR 21692 21693 Evaluate EXPR as an expression. The expression could contain an 21694 inferior function call. The function call will execute synchronously. 21695 If the expression contains spaces, it must be enclosed in double quotes. 21696 21697 GDB Command 21698 ........... 21699 21700 The corresponding GDB commands are `print', `output', and `call'. In 21701 `gdbtk' only, there's a corresponding `gdb_eval' command. 21702 21703 Example 21704 ....... 21705 21706 In the following example, the numbers that precede the commands are the 21707 "tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command 21708 Syntax. Notice how GDB/MI returns the same tokens in its output. 21709 21710 211-data-evaluate-expression A 21711 211^done,value="1" 21712 (gdb) 21713 311-data-evaluate-expression &A 21714 311^done,value="0xefffeb7c" 21715 (gdb) 21716 411-data-evaluate-expression A+3 21717 411^done,value="4" 21718 (gdb) 21719 511-data-evaluate-expression "A + 3" 21720 511^done,value="4" 21721 (gdb) 21722 21723 The `-data-list-changed-registers' Command 21724 ------------------------------------------ 21725 21726 Synopsis 21727 ........ 21728 21729 -data-list-changed-registers 21730 21731 Display a list of the registers that have changed. 21732 21733 GDB Command 21734 ........... 21735 21736 GDB doesn't have a direct analog for this command; `gdbtk' has the 21737 corresponding command `gdb_changed_register_list'. 21738 21739 Example 21740 ....... 21741 21742 On a PPC MBX board: 21743 21744 (gdb) 21745 -exec-continue 21746 ^running 21747 21748 (gdb) 21749 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={ 21750 func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", 21751 line="5"} 21752 (gdb) 21753 -data-list-changed-registers 21754 ^done,changed-registers=["0","1","2","4","5","6","7","8","9", 21755 "10","11","13","14","15","16","17","18","19","20","21","22","23", 21756 "24","25","26","27","28","30","31","64","65","66","67","69"] 21757 (gdb) 21758 21759 The `-data-list-register-names' Command 21760 --------------------------------------- 21761 21762 Synopsis 21763 ........ 21764 21765 -data-list-register-names [ ( REGNO )+ ] 21766 21767 Show a list of register names for the current target. If no 21768 arguments are given, it shows a list of the names of all the registers. 21769 If integer numbers are given as arguments, it will print a list of the 21770 names of the registers corresponding to the arguments. To ensure 21771 consistency between a register name and its number, the output list may 21772 include empty register names. 21773 21774 GDB Command 21775 ........... 21776 21777 GDB does not have a command which corresponds to 21778 `-data-list-register-names'. In `gdbtk' there is a corresponding 21779 command `gdb_regnames'. 21780 21781 Example 21782 ....... 21783 21784 For the PPC MBX board: 21785 (gdb) 21786 -data-list-register-names 21787 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", 21788 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", 21789 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", 21790 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", 21791 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", 21792 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", 21793 "", "pc","ps","cr","lr","ctr","xer"] 21794 (gdb) 21795 -data-list-register-names 1 2 3 21796 ^done,register-names=["r1","r2","r3"] 21797 (gdb) 21798 21799 The `-data-list-register-values' Command 21800 ---------------------------------------- 21801 21802 Synopsis 21803 ........ 21804 21805 -data-list-register-values FMT [ ( REGNO )*] 21806 21807 Display the registers' contents. FMT is the format according to 21808 which the registers' contents are to be returned, followed by an 21809 optional list of numbers specifying the registers to display. A 21810 missing list of numbers indicates that the contents of all the 21811 registers must be returned. 21812 21813 Allowed formats for FMT are: 21814 21815 `x' 21816 Hexadecimal 21817 21818 `o' 21819 Octal 21820 21821 `t' 21822 Binary 21823 21824 `d' 21825 Decimal 21826 21827 `r' 21828 Raw 21829 21830 `N' 21831 Natural 21832 21833 GDB Command 21834 ........... 21835 21836 The corresponding GDB commands are `info reg', `info all-reg', and (in 21837 `gdbtk') `gdb_fetch_registers'. 21838 21839 Example 21840 ....... 21841 21842 For a PPC MBX board (note: line breaks are for readability only, they 21843 don't appear in the actual output): 21844 21845 (gdb) 21846 -data-list-register-values r 64 65 21847 ^done,register-values=[{number="64",value="0xfe00a300"}, 21848 {number="65",value="0x00029002"}] 21849 (gdb) 21850 -data-list-register-values x 21851 ^done,register-values=[{number="0",value="0xfe0043c8"}, 21852 {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, 21853 {number="3",value="0x0"},{number="4",value="0xa"}, 21854 {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, 21855 {number="7",value="0xfe011e98"},{number="8",value="0x2"}, 21856 {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, 21857 {number="11",value="0x1"},{number="12",value="0x0"}, 21858 {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, 21859 {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, 21860 {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, 21861 {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, 21862 {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, 21863 {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, 21864 {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, 21865 {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, 21866 {number="29",value="0x0"},{number="30",value="0xfe010000"}, 21867 {number="31",value="0x0"},{number="32",value="0x0"}, 21868 {number="33",value="0x0"},{number="34",value="0x0"}, 21869 {number="35",value="0x0"},{number="36",value="0x0"}, 21870 {number="37",value="0x0"},{number="38",value="0x0"}, 21871 {number="39",value="0x0"},{number="40",value="0x0"}, 21872 {number="41",value="0x0"},{number="42",value="0x0"}, 21873 {number="43",value="0x0"},{number="44",value="0x0"}, 21874 {number="45",value="0x0"},{number="46",value="0x0"}, 21875 {number="47",value="0x0"},{number="48",value="0x0"}, 21876 {number="49",value="0x0"},{number="50",value="0x0"}, 21877 {number="51",value="0x0"},{number="52",value="0x0"}, 21878 {number="53",value="0x0"},{number="54",value="0x0"}, 21879 {number="55",value="0x0"},{number="56",value="0x0"}, 21880 {number="57",value="0x0"},{number="58",value="0x0"}, 21881 {number="59",value="0x0"},{number="60",value="0x0"}, 21882 {number="61",value="0x0"},{number="62",value="0x0"}, 21883 {number="63",value="0x0"},{number="64",value="0xfe00a300"}, 21884 {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, 21885 {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, 21886 {number="69",value="0x20002b03"}] 21887 (gdb) 21888 21889 The `-data-read-memory' Command 21890 ------------------------------- 21891 21892 Synopsis 21893 ........ 21894 21895 -data-read-memory [ -o BYTE-OFFSET ] 21896 ADDRESS WORD-FORMAT WORD-SIZE 21897 NR-ROWS NR-COLS [ ASCHAR ] 21898 21899 where: 21900 21901 `ADDRESS' 21902 An expression specifying the address of the first memory word to be 21903 read. Complex expressions containing embedded white space should 21904 be quoted using the C convention. 21905 21906 `WORD-FORMAT' 21907 The format to be used to print the memory words. The notation is 21908 the same as for GDB's `print' command (*note Output Formats: 21909 Output Formats.). 21910 21911 `WORD-SIZE' 21912 The size of each memory word in bytes. 21913 21914 `NR-ROWS' 21915 The number of rows in the output table. 21916 21917 `NR-COLS' 21918 The number of columns in the output table. 21919 21920 `ASCHAR' 21921 If present, indicates that each row should include an ASCII dump. 21922 The value of ASCHAR is used as a padding character when a byte is 21923 not a member of the printable ASCII character set (printable ASCII 21924 characters are those whose code is between 32 and 126, 21925 inclusively). 21926 21927 `BYTE-OFFSET' 21928 An offset to add to the ADDRESS before fetching memory. 21929 21930 This command displays memory contents as a table of NR-ROWS by 21931 NR-COLS words, each word being WORD-SIZE bytes. In total, `NR-ROWS * 21932 NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes'). 21933 Should less than the requested number of bytes be returned by the 21934 target, the missing words are identified using `N/A'. The number of 21935 bytes read from the target is returned in `nr-bytes' and the starting 21936 address used to read memory in `addr'. 21937 21938 The address of the next/previous row or page is available in 21939 `next-row' and `prev-row', `next-page' and `prev-page'. 21940 21941 GDB Command 21942 ........... 21943 21944 The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory 21945 read command. 21946 21947 Example 21948 ....... 21949 21950 Read six bytes of memory starting at `bytes+6' but then offset by `-6' 21951 bytes. Format as three rows of two columns. One byte per word. 21952 Display each word in hex. 21953 21954 (gdb) 21955 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 21956 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", 21957 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", 21958 prev-page="0x0000138a",memory=[ 21959 {addr="0x00001390",data=["0x00","0x01"]}, 21960 {addr="0x00001392",data=["0x02","0x03"]}, 21961 {addr="0x00001394",data=["0x04","0x05"]}] 21962 (gdb) 21963 21964 Read two bytes of memory starting at address `shorts + 64' and 21965 display as a single word formatted in decimal. 21966 21967 (gdb) 21968 5-data-read-memory shorts+64 d 2 1 1 21969 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", 21970 next-row="0x00001512",prev-row="0x0000150e", 21971 next-page="0x00001512",prev-page="0x0000150e",memory=[ 21972 {addr="0x00001510",data=["128"]}] 21973 (gdb) 21974 21975 Read thirty two bytes of memory starting at `bytes+16' and format as 21976 eight rows of four columns. Include a string encoding with `x' used as 21977 the non-printable character. 21978 21979 (gdb) 21980 4-data-read-memory bytes+16 x 1 8 4 x 21981 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", 21982 next-row="0x000013c0",prev-row="0x0000139c", 21983 next-page="0x000013c0",prev-page="0x00001380",memory=[ 21984 {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, 21985 {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, 21986 {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, 21987 {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, 21988 {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, 21989 {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, 21990 {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, 21991 {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] 21992 (gdb) 21993 21994 21995 File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI 21996 21997 27.15 GDB/MI Tracepoint Commands 21998 ================================ 21999 22000 The tracepoint commands are not yet implemented. 22001 22002 22003 File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI 22004 22005 27.16 GDB/MI Symbol Query Commands 22006 ================================== 22007 22008 The `-symbol-list-lines' Command 22009 -------------------------------- 22010 22011 Synopsis 22012 ........ 22013 22014 -symbol-list-lines FILENAME 22015 22016 Print the list of lines that contain code and their associated 22017 program addresses for the given source filename. The entries are 22018 sorted in ascending PC order. 22019 22020 GDB Command 22021 ........... 22022 22023 There is no corresponding GDB command. 22024 22025 Example 22026 ....... 22027 22028 (gdb) 22029 -symbol-list-lines basics.c 22030 ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] 22031 (gdb) 22032 22033 22034 File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI 22035 22036 27.17 GDB/MI File Commands 22037 ========================== 22038 22039 This section describes the GDB/MI commands to specify executable file 22040 names and to read in and obtain symbol table information. 22041 22042 The `-file-exec-and-symbols' Command 22043 ------------------------------------ 22044 22045 Synopsis 22046 ........ 22047 22048 -file-exec-and-symbols FILE 22049 22050 Specify the executable file to be debugged. This file is the one 22051 from which the symbol table is also read. If no file is specified, the 22052 command clears the executable and symbol information. If breakpoints 22053 are set when using this command with no arguments, GDB will produce 22054 error messages. Otherwise, no output is produced, except a completion 22055 notification. 22056 22057 GDB Command 22058 ........... 22059 22060 The corresponding GDB command is `file'. 22061 22062 Example 22063 ....... 22064 22065 (gdb) 22066 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 22067 ^done 22068 (gdb) 22069 22070 The `-file-exec-file' Command 22071 ----------------------------- 22072 22073 Synopsis 22074 ........ 22075 22076 -file-exec-file FILE 22077 22078 Specify the executable file to be debugged. Unlike 22079 `-file-exec-and-symbols', the symbol table is _not_ read from this 22080 file. If used without argument, GDB clears the information about the 22081 executable file. No output is produced, except a completion 22082 notification. 22083 22084 GDB Command 22085 ........... 22086 22087 The corresponding GDB command is `exec-file'. 22088 22089 Example 22090 ....... 22091 22092 (gdb) 22093 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 22094 ^done 22095 (gdb) 22096 22097 The `-file-list-exec-source-file' Command 22098 ----------------------------------------- 22099 22100 Synopsis 22101 ........ 22102 22103 -file-list-exec-source-file 22104 22105 List the line number, the current source file, and the absolute path 22106 to the current source file for the current executable. The macro 22107 information field has a value of `1' or `0' depending on whether or not 22108 the file includes preprocessor macro information. 22109 22110 GDB Command 22111 ........... 22112 22113 The GDB equivalent is `info source' 22114 22115 Example 22116 ....... 22117 22118 (gdb) 22119 123-file-list-exec-source-file 22120 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" 22121 (gdb) 22122 22123 The `-file-list-exec-source-files' Command 22124 ------------------------------------------ 22125 22126 Synopsis 22127 ........ 22128 22129 -file-list-exec-source-files 22130 22131 List the source files for the current executable. 22132 22133 It will always output the filename, but only when GDB can find the 22134 absolute file name of a source file, will it output the fullname. 22135 22136 GDB Command 22137 ........... 22138 22139 The GDB equivalent is `info sources'. `gdbtk' has an analogous command 22140 `gdb_listfiles'. 22141 22142 Example 22143 ....... 22144 22145 (gdb) 22146 -file-list-exec-source-files 22147 ^done,files=[ 22148 {file=foo.c,fullname=/home/foo.c}, 22149 {file=/home/bar.c,fullname=/home/bar.c}, 22150 {file=gdb_could_not_find_fullpath.c}] 22151 (gdb) 22152 22153 The `-file-symbol-file' Command 22154 ------------------------------- 22155 22156 Synopsis 22157 ........ 22158 22159 -file-symbol-file FILE 22160 22161 Read symbol table info from the specified FILE argument. When used 22162 without arguments, clears GDB's symbol table info. No output is 22163 produced, except for a completion notification. 22164 22165 GDB Command 22166 ........... 22167 22168 The corresponding GDB command is `symbol-file'. 22169 22170 Example 22171 ....... 22172 22173 (gdb) 22174 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 22175 ^done 22176 (gdb) 22177 22178 22179 File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI 22180 22181 27.18 GDB/MI Target Manipulation Commands 22182 ========================================= 22183 22184 The `-target-attach' Command 22185 ---------------------------- 22186 22187 Synopsis 22188 ........ 22189 22190 -target-attach PID | GID | FILE 22191 22192 Attach to a process PID or a file FILE outside of GDB, or a thread 22193 group GID. If attaching to a thread group, the id previously returned 22194 by `-list-thread-groups --available' must be used. 22195 22196 GDB Command 22197 ........... 22198 22199 The corresponding GDB command is `attach'. 22200 22201 Example 22202 ....... 22203 22204 (gdb) 22205 -target-attach 34 22206 =thread-created,id="1" 22207 *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]} 22208 ^done 22209 (gdb) 22210 22211 The `-target-detach' Command 22212 ---------------------------- 22213 22214 Synopsis 22215 ........ 22216 22217 -target-detach [ PID | GID ] 22218 22219 Detach from the remote target which normally resumes its execution. 22220 If either PID or GID is specified, detaches from either the specified 22221 process, or specified thread group. There's no output. 22222 22223 GDB Command 22224 ........... 22225 22226 The corresponding GDB command is `detach'. 22227 22228 Example 22229 ....... 22230 22231 (gdb) 22232 -target-detach 22233 ^done 22234 (gdb) 22235 22236 The `-target-disconnect' Command 22237 -------------------------------- 22238 22239 Synopsis 22240 ........ 22241 22242 -target-disconnect 22243 22244 Disconnect from the remote target. There's no output and the target 22245 is generally not resumed. 22246 22247 GDB Command 22248 ........... 22249 22250 The corresponding GDB command is `disconnect'. 22251 22252 Example 22253 ....... 22254 22255 (gdb) 22256 -target-disconnect 22257 ^done 22258 (gdb) 22259 22260 The `-target-download' Command 22261 ------------------------------ 22262 22263 Synopsis 22264 ........ 22265 22266 -target-download 22267 22268 Loads the executable onto the remote target. It prints out an 22269 update message every half second, which includes the fields: 22270 22271 `section' 22272 The name of the section. 22273 22274 `section-sent' 22275 The size of what has been sent so far for that section. 22276 22277 `section-size' 22278 The size of the section. 22279 22280 `total-sent' 22281 The total size of what was sent so far (the current and the 22282 previous sections). 22283 22284 `total-size' 22285 The size of the overall executable to download. 22286 22287 Each message is sent as status record (*note GDB/MI Output Syntax: 22288 GDB/MI Output Syntax.). 22289 22290 In addition, it prints the name and size of the sections, as they are 22291 downloaded. These messages include the following fields: 22292 22293 `section' 22294 The name of the section. 22295 22296 `section-size' 22297 The size of the section. 22298 22299 `total-size' 22300 The size of the overall executable to download. 22301 22302 At the end, a summary is printed. 22303 22304 GDB Command 22305 ........... 22306 22307 The corresponding GDB command is `load'. 22308 22309 Example 22310 ....... 22311 22312 Note: each status message appears on a single line. Here the messages 22313 have been broken down so that they can fit onto a page. 22314 22315 (gdb) 22316 -target-download 22317 +download,{section=".text",section-size="6668",total-size="9880"} 22318 +download,{section=".text",section-sent="512",section-size="6668", 22319 total-sent="512",total-size="9880"} 22320 +download,{section=".text",section-sent="1024",section-size="6668", 22321 total-sent="1024",total-size="9880"} 22322 +download,{section=".text",section-sent="1536",section-size="6668", 22323 total-sent="1536",total-size="9880"} 22324 +download,{section=".text",section-sent="2048",section-size="6668", 22325 total-sent="2048",total-size="9880"} 22326 +download,{section=".text",section-sent="2560",section-size="6668", 22327 total-sent="2560",total-size="9880"} 22328 +download,{section=".text",section-sent="3072",section-size="6668", 22329 total-sent="3072",total-size="9880"} 22330 +download,{section=".text",section-sent="3584",section-size="6668", 22331 total-sent="3584",total-size="9880"} 22332 +download,{section=".text",section-sent="4096",section-size="6668", 22333 total-sent="4096",total-size="9880"} 22334 +download,{section=".text",section-sent="4608",section-size="6668", 22335 total-sent="4608",total-size="9880"} 22336 +download,{section=".text",section-sent="5120",section-size="6668", 22337 total-sent="5120",total-size="9880"} 22338 +download,{section=".text",section-sent="5632",section-size="6668", 22339 total-sent="5632",total-size="9880"} 22340 +download,{section=".text",section-sent="6144",section-size="6668", 22341 total-sent="6144",total-size="9880"} 22342 +download,{section=".text",section-sent="6656",section-size="6668", 22343 total-sent="6656",total-size="9880"} 22344 +download,{section=".init",section-size="28",total-size="9880"} 22345 +download,{section=".fini",section-size="28",total-size="9880"} 22346 +download,{section=".data",section-size="3156",total-size="9880"} 22347 +download,{section=".data",section-sent="512",section-size="3156", 22348 total-sent="7236",total-size="9880"} 22349 +download,{section=".data",section-sent="1024",section-size="3156", 22350 total-sent="7748",total-size="9880"} 22351 +download,{section=".data",section-sent="1536",section-size="3156", 22352 total-sent="8260",total-size="9880"} 22353 +download,{section=".data",section-sent="2048",section-size="3156", 22354 total-sent="8772",total-size="9880"} 22355 +download,{section=".data",section-sent="2560",section-size="3156", 22356 total-sent="9284",total-size="9880"} 22357 +download,{section=".data",section-sent="3072",section-size="3156", 22358 total-sent="9796",total-size="9880"} 22359 ^done,address="0x10004",load-size="9880",transfer-rate="6586", 22360 write-rate="429" 22361 (gdb) 22362 22363 GDB Command 22364 ........... 22365 22366 No equivalent. 22367 22368 Example 22369 ....... 22370 22371 N.A. 22372 22373 The `-target-select' Command 22374 ---------------------------- 22375 22376 Synopsis 22377 ........ 22378 22379 -target-select TYPE PARAMETERS ... 22380 22381 Connect GDB to the remote target. This command takes two args: 22382 22383 `TYPE' 22384 The type of target, for instance `remote', etc. 22385 22386 `PARAMETERS' 22387 Device names, host names and the like. *Note Commands for 22388 Managing Targets: Target Commands, for more details. 22389 22390 The output is a connection notification, followed by the address at 22391 which the target program is, in the following form: 22392 22393 ^connected,addr="ADDRESS",func="FUNCTION NAME", 22394 args=[ARG LIST] 22395 22396 GDB Command 22397 ........... 22398 22399 The corresponding GDB command is `target'. 22400 22401 Example 22402 ....... 22403 22404 (gdb) 22405 -target-select remote /dev/ttya 22406 ^connected,addr="0xfe00a300",func="??",args=[] 22407 (gdb) 22408 22409 22410 File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI 22411 22412 27.19 GDB/MI File Transfer Commands 22413 =================================== 22414 22415 The `-target-file-put' Command 22416 ------------------------------ 22417 22418 Synopsis 22419 ........ 22420 22421 -target-file-put HOSTFILE TARGETFILE 22422 22423 Copy file HOSTFILE from the host system (the machine running GDB) to 22424 TARGETFILE on the target system. 22425 22426 GDB Command 22427 ........... 22428 22429 The corresponding GDB command is `remote put'. 22430 22431 Example 22432 ....... 22433 22434 (gdb) 22435 -target-file-put localfile remotefile 22436 ^done 22437 (gdb) 22438 22439 The `-target-file-get' Command 22440 ------------------------------ 22441 22442 Synopsis 22443 ........ 22444 22445 -target-file-get TARGETFILE HOSTFILE 22446 22447 Copy file TARGETFILE from the target system to HOSTFILE on the host 22448 system. 22449 22450 GDB Command 22451 ........... 22452 22453 The corresponding GDB command is `remote get'. 22454 22455 Example 22456 ....... 22457 22458 (gdb) 22459 -target-file-get remotefile localfile 22460 ^done 22461 (gdb) 22462 22463 The `-target-file-delete' Command 22464 --------------------------------- 22465 22466 Synopsis 22467 ........ 22468 22469 -target-file-delete TARGETFILE 22470 22471 Delete TARGETFILE from the target system. 22472 22473 GDB Command 22474 ........... 22475 22476 The corresponding GDB command is `remote delete'. 22477 22478 Example 22479 ....... 22480 22481 (gdb) 22482 -target-file-delete remotefile 22483 ^done 22484 (gdb) 22485 22486 22487 File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI 22488 22489 27.20 Miscellaneous GDB/MI Commands 22490 =================================== 22491 22492 The `-gdb-exit' Command 22493 ----------------------- 22494 22495 Synopsis 22496 ........ 22497 22498 -gdb-exit 22499 22500 Exit GDB immediately. 22501 22502 GDB Command 22503 ........... 22504 22505 Approximately corresponds to `quit'. 22506 22507 Example 22508 ....... 22509 22510 (gdb) 22511 -gdb-exit 22512 ^exit 22513 22514 The `-gdb-set' Command 22515 ---------------------- 22516 22517 Synopsis 22518 ........ 22519 22520 -gdb-set 22521 22522 Set an internal GDB variable. 22523 22524 GDB Command 22525 ........... 22526 22527 The corresponding GDB command is `set'. 22528 22529 Example 22530 ....... 22531 22532 (gdb) 22533 -gdb-set $foo=3 22534 ^done 22535 (gdb) 22536 22537 The `-gdb-show' Command 22538 ----------------------- 22539 22540 Synopsis 22541 ........ 22542 22543 -gdb-show 22544 22545 Show the current value of a GDB variable. 22546 22547 GDB Command 22548 ........... 22549 22550 The corresponding GDB command is `show'. 22551 22552 Example 22553 ....... 22554 22555 (gdb) 22556 -gdb-show annotate 22557 ^done,value="0" 22558 (gdb) 22559 22560 The `-gdb-version' Command 22561 -------------------------- 22562 22563 Synopsis 22564 ........ 22565 22566 -gdb-version 22567 22568 Show version information for GDB. Used mostly in testing. 22569 22570 GDB Command 22571 ........... 22572 22573 The GDB equivalent is `show version'. GDB by default shows this 22574 information when you start an interactive session. 22575 22576 Example 22577 ....... 22578 22579 (gdb) 22580 -gdb-version 22581 ~GNU gdb 5.2.1 22582 ~Copyright 2000 Free Software Foundation, Inc. 22583 ~GDB is free software, covered by the GNU General Public License, and 22584 ~you are welcome to change it and/or distribute copies of it under 22585 ~ certain conditions. 22586 ~Type "show copying" to see the conditions. 22587 ~There is absolutely no warranty for GDB. Type "show warranty" for 22588 ~ details. 22589 ~This GDB was configured as 22590 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". 22591 ^done 22592 (gdb) 22593 22594 The `-list-features' Command 22595 ---------------------------- 22596 22597 Returns a list of particular features of the MI protocol that this 22598 version of gdb implements. A feature can be a command, or a new field 22599 in an output of some command, or even an important bugfix. While a 22600 frontend can sometimes detect presence of a feature at runtime, it is 22601 easier to perform detection at debugger startup. 22602 22603 The command returns a list of strings, with each string naming an 22604 available feature. Each returned string is just a name, it does not 22605 have any internal structure. The list of possible feature names is 22606 given below. 22607 22608 Example output: 22609 22610 (gdb) -list-features 22611 ^done,result=["feature1","feature2"] 22612 22613 The current list of features is: 22614 22615 `frozen-varobjs' 22616 Indicates presence of the `-var-set-frozen' command, as well as 22617 possible presense of the `frozen' field in the output of 22618 `-varobj-create'. 22619 22620 `pending-breakpoints' 22621 Indicates presence of the `-f' option to the `-break-insert' 22622 command. 22623 22624 `python' 22625 Indicates presence of Python scripting support, Python-based 22626 pretty-printing commands, and possible presence of the 22627 `display_hint' field in the output of `-var-list-children' 22628 22629 `thread-info' 22630 Indicates presence of the `-thread-info' command. 22631 22632 22633 The `-list-target-features' Command 22634 ----------------------------------- 22635 22636 Returns a list of particular features that are supported by the target. 22637 Those features affect the permitted MI commands, but unlike the 22638 features reported by the `-list-features' command, the features depend 22639 on which target GDB is using at the moment. Whenever a target can 22640 change, due to commands such as `-target-select', `-target-attach' or 22641 `-exec-run', the list of target features may change, and the frontend 22642 should obtain it again. Example output: 22643 22644 (gdb) -list-features 22645 ^done,result=["async"] 22646 22647 The current list of features is: 22648 22649 `async' 22650 Indicates that the target is capable of asynchronous command 22651 execution, which means that GDB will accept further commands while 22652 the target is running. 22653 22654 22655 The `-list-thread-groups' Command 22656 --------------------------------- 22657 22658 Synopsis 22659 -------- 22660 22661 -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ] 22662 22663 Lists thread groups (*note Thread groups::). When a single thread 22664 group is passed as the argument, lists the children of that group. 22665 When several thread group are passed, lists information about those 22666 thread groups. Without any parameters, lists information about all 22667 top-level thread groups. 22668 22669 Normally, thread groups that are being debugged are reported. With 22670 the `--available' option, GDB reports thread groups available on the 22671 target. 22672 22673 The output of this command may have either a `threads' result or a 22674 `groups' result. The `thread' result has a list of tuples as value, 22675 with each tuple describing a thread (*note GDB/MI Thread 22676 Information::). The `groups' result has a list of tuples as value, 22677 each tuple describing a thread group. If top-level groups are 22678 requested (that is, no parameter is passed), or when several groups are 22679 passed, the output always has a `groups' result. The format of the 22680 `group' result is described below. 22681 22682 To reduce the number of roundtrips it's possible to list thread 22683 groups together with their children, by passing the `--recurse' option 22684 and the recursion depth. Presently, only recursion depth of 1 is 22685 permitted. If this option is present, then every reported thread group 22686 will also include its children, either as `group' or `threads' field. 22687 22688 In general, any combination of option and parameters is permitted, 22689 with the following caveats: 22690 22691 * When a single thread group is passed, the output will typically be 22692 the `threads' result. Because threads may not contain anything, 22693 the `recurse' option will be ignored. 22694 22695 * When the `--available' option is passed, limited information may 22696 be available. In particular, the list of threads of a process 22697 might be inaccessible. Further, specifying specific thread groups 22698 might not give any performance advantage over listing all thread 22699 groups. The frontend should assume that `-list-thread-groups 22700 --available' is always an expensive operation and cache the 22701 results. 22702 22703 22704 The `groups' result is a list of tuples, where each tuple may have 22705 the following fields: 22706 22707 `id' 22708 Identifier of the thread group. This field is always present. 22709 22710 `type' 22711 The type of the thread group. At present, only `process' is a 22712 valid type. 22713 22714 `pid' 22715 The target-specific process identifier. This field is only present 22716 for thread groups of type `process'. 22717 22718 `num_children' 22719 The number of children this thread group has. This field may be 22720 absent for an available thread group. 22721 22722 `threads' 22723 This field has a list of tuples as value, each tuple describing a 22724 thread. It may be present if the `--recurse' option is specified, 22725 and it's actually possible to obtain the threads. 22726 22727 `cores' 22728 This field is a list of integers, each identifying a core that one 22729 thread of the group is running on. This field may be absent if 22730 such information is not available. 22731 22732 22733 Example 22734 ------- 22735 22736 gdb 22737 -list-thread-groups 22738 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}] 22739 -list-thread-groups 17 22740 ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 22741 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, 22742 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 22743 frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], 22744 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]] 22745 -list-thread-groups --available 22746 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}] 22747 -list-thread-groups --available --recurse 1 22748 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 22749 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, 22750 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..] 22751 -list-thread-groups --available --recurse 1 17 18 22752 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 22753 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, 22754 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...] 22755 22756 The `-interpreter-exec' Command 22757 ------------------------------- 22758 22759 Synopsis 22760 -------- 22761 22762 -interpreter-exec INTERPRETER COMMAND 22763 22764 Execute the specified COMMAND in the given INTERPRETER. 22765 22766 GDB Command 22767 ----------- 22768 22769 The corresponding GDB command is `interpreter-exec'. 22770 22771 Example 22772 ------- 22773 22774 (gdb) 22775 -interpreter-exec console "break main" 22776 &"During symbol reading, couldn't parse type; debugger out of date?.\n" 22777 &"During symbol reading, bad structure-type format.\n" 22778 ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" 22779 ^done 22780 (gdb) 22781 22782 The `-inferior-tty-set' Command 22783 ------------------------------- 22784 22785 Synopsis 22786 -------- 22787 22788 -inferior-tty-set /dev/pts/1 22789 22790 Set terminal for future runs of the program being debugged. 22791 22792 GDB Command 22793 ----------- 22794 22795 The corresponding GDB command is `set inferior-tty' /dev/pts/1. 22796 22797 Example 22798 ------- 22799 22800 (gdb) 22801 -inferior-tty-set /dev/pts/1 22802 ^done 22803 (gdb) 22804 22805 The `-inferior-tty-show' Command 22806 -------------------------------- 22807 22808 Synopsis 22809 -------- 22810 22811 -inferior-tty-show 22812 22813 Show terminal for future runs of program being debugged. 22814 22815 GDB Command 22816 ----------- 22817 22818 The corresponding GDB command is `show inferior-tty'. 22819 22820 Example 22821 ------- 22822 22823 (gdb) 22824 -inferior-tty-set /dev/pts/1 22825 ^done 22826 (gdb) 22827 -inferior-tty-show 22828 ^done,inferior_tty_terminal="/dev/pts/1" 22829 (gdb) 22830 22831 The `-enable-timings' Command 22832 ----------------------------- 22833 22834 Synopsis 22835 -------- 22836 22837 -enable-timings [yes | no] 22838 22839 Toggle the printing of the wallclock, user and system times for an MI 22840 command as a field in its output. This command is to help frontend 22841 developers optimize the performance of their code. No argument is 22842 equivalent to `yes'. 22843 22844 GDB Command 22845 ----------- 22846 22847 No equivalent. 22848 22849 Example 22850 ------- 22851 22852 (gdb) 22853 -enable-timings 22854 ^done 22855 (gdb) 22856 -break-insert main 22857 ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 22858 addr="0x080484ed",func="main",file="myprog.c", 22859 fullname="/home/nickrob/myprog.c",line="73",times="0"}, 22860 time={wallclock="0.05185",user="0.00800",system="0.00000"} 22861 (gdb) 22862 -enable-timings no 22863 ^done 22864 (gdb) 22865 -exec-run 22866 ^running 22867 (gdb) 22868 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 22869 frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"}, 22870 {name="argv",value="0xbfb60364"}],file="myprog.c", 22871 fullname="/home/nickrob/myprog.c",line="73"} 22872 (gdb) 22873 22874 22875 File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top 22876 22877 28 GDB Annotations 22878 ****************** 22879 22880 This chapter describes annotations in GDB. Annotations were designed 22881 to interface GDB to graphical user interfaces or other similar programs 22882 which want to interact with GDB at a relatively high level. 22883 22884 The annotation mechanism has largely been superseded by GDB/MI 22885 (*note GDB/MI::). 22886 22887 * Menu: 22888 22889 * Annotations Overview:: What annotations are; the general syntax. 22890 * Server Prefix:: Issuing a command without affecting user state. 22891 * Prompting:: Annotations marking GDB's need for input. 22892 * Errors:: Annotations for error messages. 22893 * Invalidation:: Some annotations describe things now invalid. 22894 * Annotations for Running:: 22895 Whether the program is running, how it stopped, etc. 22896 * Source Annotations:: Annotations describing source code. 22897 22898 22899 File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations 22900 22901 28.1 What is an Annotation? 22902 =========================== 22903 22904 Annotations start with a newline character, two `control-z' characters, 22905 and the name of the annotation. If there is no additional information 22906 associated with this annotation, the name of the annotation is followed 22907 immediately by a newline. If there is additional information, the name 22908 of the annotation is followed by a space, the additional information, 22909 and a newline. The additional information cannot contain newline 22910 characters. 22911 22912 Any output not beginning with a newline and two `control-z' 22913 characters denotes literal output from GDB. Currently there is no need 22914 for GDB to output a newline followed by two `control-z' characters, but 22915 if there was such a need, the annotations could be extended with an 22916 `escape' annotation which means those three characters as output. 22917 22918 The annotation LEVEL, which is specified using the `--annotate' 22919 command line option (*note Mode Options::), controls how much 22920 information GDB prints together with its prompt, values of expressions, 22921 source lines, and other types of output. Level 0 is for no 22922 annotations, level 1 is for use when GDB is run as a subprocess of GNU 22923 Emacs, level 3 is the maximum annotation suitable for programs that 22924 control GDB, and level 2 annotations have been made obsolete (*note 22925 Limitations of the Annotation Interface: (annotate)Limitations.). 22926 22927 `set annotate LEVEL' 22928 The GDB command `set annotate' sets the level of annotations to 22929 the specified LEVEL. 22930 22931 `show annotate' 22932 Show the current annotation level. 22933 22934 This chapter describes level 3 annotations. 22935 22936 A simple example of starting up GDB with annotations is: 22937 22938 $ gdb --annotate=3 22939 GNU gdb 6.0 22940 Copyright 2003 Free Software Foundation, Inc. 22941 GDB is free software, covered by the GNU General Public License, 22942 and you are welcome to change it and/or distribute copies of it 22943 under certain conditions. 22944 Type "show copying" to see the conditions. 22945 There is absolutely no warranty for GDB. Type "show warranty" 22946 for details. 22947 This GDB was configured as "i386-pc-linux-gnu" 22948 22949 ^Z^Zpre-prompt 22950 (gdb) 22951 ^Z^Zprompt 22952 quit 22953 22954 ^Z^Zpost-prompt 22955 $ 22956 22957 Here `quit' is input to GDB; the rest is output from GDB. The three 22958 lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are 22959 annotations; the rest is output from GDB. 22960 22961 22962 File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations 22963 22964 28.2 The Server Prefix 22965 ====================== 22966 22967 If you prefix a command with `server ' then it will not affect the 22968 command history, nor will it affect GDB's notion of which command to 22969 repeat if <RET> is pressed on a line by itself. This means that 22970 commands can be run behind a user's back by a front-end in a 22971 transparent manner. 22972 22973 The `server ' prefix does not affect the recording of values into 22974 the value history; to print a value without recording it into the value 22975 history, use the `output' command instead of the `print' command. 22976 22977 Using this prefix also disables confirmation requests (*note 22978 confirmation requests::). 22979 22980 22981 File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations 22982 22983 28.3 Annotation for GDB Input 22984 ============================= 22985 22986 When GDB prompts for input, it annotates this fact so it is possible to 22987 know when to send output, when the output from a given command is over, 22988 etc. 22989 22990 Different kinds of input each have a different "input type". Each 22991 input type has three annotations: a `pre-' annotation, which denotes 22992 the beginning of any prompt which is being output, a plain annotation, 22993 which denotes the end of the prompt, and then a `post-' annotation 22994 which denotes the end of any echo which may (or may not) be associated 22995 with the input. For example, the `prompt' input type features the 22996 following annotations: 22997 22998 ^Z^Zpre-prompt 22999 ^Z^Zprompt 23000 ^Z^Zpost-prompt 23001 23002 The input types are 23003 23004 `prompt' 23005 When GDB is prompting for a command (the main GDB prompt). 23006 23007 `commands' 23008 When GDB prompts for a set of commands, like in the `commands' 23009 command. The annotations are repeated for each command which is 23010 input. 23011 23012 `overload-choice' 23013 When GDB wants the user to select between various overloaded 23014 functions. 23015 23016 `query' 23017 When GDB wants the user to confirm a potentially dangerous 23018 operation. 23019 23020 `prompt-for-continue' 23021 When GDB is asking the user to press return to continue. Note: 23022 Don't expect this to work well; instead use `set height 0' to 23023 disable prompting. This is because the counting of lines is buggy 23024 in the presence of annotations. 23025 23026 23027 File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations 23028 23029 28.4 Errors 23030 =========== 23031 23032 ^Z^Zquit 23033 23034 This annotation occurs right before GDB responds to an interrupt. 23035 23036 ^Z^Zerror 23037 23038 This annotation occurs right before GDB responds to an error. 23039 23040 Quit and error annotations indicate that any annotations which GDB 23041 was in the middle of may end abruptly. For example, if a 23042 `value-history-begin' annotation is followed by a `error', one cannot 23043 expect to receive the matching `value-history-end'. One cannot expect 23044 not to receive it either, however; an error annotation does not 23045 necessarily mean that GDB is immediately returning all the way to the 23046 top level. 23047 23048 A quit or error annotation may be preceded by 23049 23050 ^Z^Zerror-begin 23051 23052 Any output between that and the quit or error annotation is the error 23053 message. 23054 23055 Warning messages are not yet annotated. 23056 23057 23058 File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations 23059 23060 28.5 Invalidation Notices 23061 ========================= 23062 23063 The following annotations say that certain pieces of state may have 23064 changed. 23065 23066 `^Z^Zframes-invalid' 23067 The frames (for example, output from the `backtrace' command) may 23068 have changed. 23069 23070 `^Z^Zbreakpoints-invalid' 23071 The breakpoints may have changed. For example, the user just 23072 added or deleted a breakpoint. 23073 23074 23075 File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations 23076 23077 28.6 Running the Program 23078 ======================== 23079 23080 When the program starts executing due to a GDB command such as `step' 23081 or `continue', 23082 23083 ^Z^Zstarting 23084 23085 is output. When the program stops, 23086 23087 ^Z^Zstopped 23088 23089 is output. Before the `stopped' annotation, a variety of 23090 annotations describe how the program stopped. 23091 23092 `^Z^Zexited EXIT-STATUS' 23093 The program exited, and EXIT-STATUS is the exit status (zero for 23094 successful exit, otherwise nonzero). 23095 23096 `^Z^Zsignalled' 23097 The program exited with a signal. After the `^Z^Zsignalled', the 23098 annotation continues: 23099 23100 INTRO-TEXT 23101 ^Z^Zsignal-name 23102 NAME 23103 ^Z^Zsignal-name-end 23104 MIDDLE-TEXT 23105 ^Z^Zsignal-string 23106 STRING 23107 ^Z^Zsignal-string-end 23108 END-TEXT 23109 23110 where NAME is the name of the signal, such as `SIGILL' or 23111 `SIGSEGV', and STRING is the explanation of the signal, such as 23112 `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT, 23113 MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no 23114 particular format. 23115 23116 `^Z^Zsignal' 23117 The syntax of this annotation is just like `signalled', but GDB is 23118 just saying that the program received the signal, not that it was 23119 terminated with it. 23120 23121 `^Z^Zbreakpoint NUMBER' 23122 The program hit breakpoint number NUMBER. 23123 23124 `^Z^Zwatchpoint NUMBER' 23125 The program hit watchpoint number NUMBER. 23126 23127 23128 File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations 23129 23130 28.7 Displaying Source 23131 ====================== 23132 23133 The following annotation is used instead of displaying source code: 23134 23135 ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR 23136 23137 where FILENAME is an absolute file name indicating which source 23138 file, LINE is the line number within that file (where 1 is the first 23139 line in the file), CHARACTER is the character position within the file 23140 (where 0 is the first character in the file) (for most debug formats 23141 this will necessarily point to the beginning of a line), MIDDLE is 23142 `middle' if ADDR is in the middle of the line, or `beg' if ADDR is at 23143 the beginning of the line, and ADDR is the address in the target 23144 program associated with the source which is being displayed. ADDR is 23145 in the form `0x' followed by one or more lowercase hex digits (note 23146 that this does not depend on the language). 23147 23148 23149 File: gdb.info, Node: JIT Interface, Next: GDB Bugs, Prev: Annotations, Up: Top 23150 23151 29 JIT Compilation Interface 23152 **************************** 23153 23154 This chapter documents GDB's "just-in-time" (JIT) compilation 23155 interface. A JIT compiler is a program or library that generates native 23156 executable code at runtime and executes it, usually in order to achieve 23157 good performance while maintaining platform independence. 23158 23159 Programs that use JIT compilation are normally difficult to debug 23160 because portions of their code are generated at runtime, instead of 23161 being loaded from object files, which is where GDB normally finds the 23162 program's symbols and debug information. In order to debug programs 23163 that use JIT compilation, GDB has an interface that allows the program 23164 to register in-memory symbol files with GDB at runtime. 23165 23166 If you are using GDB to debug a program that uses this interface, 23167 then it should work transparently so long as you have not stripped the 23168 binary. If you are developing a JIT compiler, then the interface is 23169 documented in the rest of this chapter. At this time, the only known 23170 client of this interface is the LLVM JIT. 23171 23172 Broadly speaking, the JIT interface mirrors the dynamic loader 23173 interface. The JIT compiler communicates with GDB by writing data into 23174 a global variable and calling a fuction at a well-known symbol. When 23175 GDB attaches, it reads a linked list of symbol files from the global 23176 variable to find existing code, and puts a breakpoint in the function 23177 so that it can find out about additional code. 23178 23179 * Menu: 23180 23181 * Declarations:: Relevant C struct declarations 23182 * Registering Code:: Steps to register code 23183 * Unregistering Code:: Steps to unregister code 23184 23185 23186 File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface 23187 23188 29.1 JIT Declarations 23189 ===================== 23190 23191 These are the relevant struct declarations that a C program should 23192 include to implement the interface: 23193 23194 typedef enum 23195 { 23196 JIT_NOACTION = 0, 23197 JIT_REGISTER_FN, 23198 JIT_UNREGISTER_FN 23199 } jit_actions_t; 23200 23201 struct jit_code_entry 23202 { 23203 struct jit_code_entry *next_entry; 23204 struct jit_code_entry *prev_entry; 23205 const char *symfile_addr; 23206 uint64_t symfile_size; 23207 }; 23208 23209 struct jit_descriptor 23210 { 23211 uint32_t version; 23212 /* This type should be jit_actions_t, but we use uint32_t 23213 to be explicit about the bitwidth. */ 23214 uint32_t action_flag; 23215 struct jit_code_entry *relevant_entry; 23216 struct jit_code_entry *first_entry; 23217 }; 23218 23219 /* GDB puts a breakpoint in this function. */ 23220 void __attribute__((noinline)) __jit_debug_register_code() { }; 23221 23222 /* Make sure to specify the version statically, because the 23223 debugger may check the version before we can set it. */ 23224 struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 }; 23225 23226 If the JIT is multi-threaded, then it is important that the JIT 23227 synchronize any modifications to this global data properly, which can 23228 easily be done by putting a global mutex around modifications to these 23229 structures. 23230 23231 23232 File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface 23233 23234 29.2 Registering Code 23235 ===================== 23236 23237 To register code with GDB, the JIT should follow this protocol: 23238 23239 * Generate an object file in memory with symbols and other desired 23240 debug information. The file must include the virtual addresses of 23241 the sections. 23242 23243 * Create a code entry for the file, which gives the start and size 23244 of the symbol file. 23245 23246 * Add it to the linked list in the JIT descriptor. 23247 23248 * Point the relevant_entry field of the descriptor at the entry. 23249 23250 * Set `action_flag' to `JIT_REGISTER' and call 23251 `__jit_debug_register_code'. 23252 23253 When GDB is attached and the breakpoint fires, GDB uses the 23254 `relevant_entry' pointer so it doesn't have to walk the list looking for 23255 new code. However, the linked list must still be maintained in order 23256 to allow GDB to attach to a running process and still find the symbol 23257 files. 23258 23259 23260 File: gdb.info, Node: Unregistering Code, Prev: Registering Code, Up: JIT Interface 23261 23262 29.3 Unregistering Code 23263 ======================= 23264 23265 If code is freed, then the JIT should use the following protocol: 23266 23267 * Remove the code entry corresponding to the code from the linked 23268 list. 23269 23270 * Point the `relevant_entry' field of the descriptor at the code 23271 entry. 23272 23273 * Set `action_flag' to `JIT_UNREGISTER' and call 23274 `__jit_debug_register_code'. 23275 23276 If the JIT frees or recompiles code without unregistering it, then 23277 GDB and the JIT will leak the memory used for the associated symbol 23278 files. 23279 23280 23281 File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: JIT Interface, Up: Top 23282 23283 30 Reporting Bugs in GDB 23284 ************************ 23285 23286 Your bug reports play an essential role in making GDB reliable. 23287 23288 Reporting a bug may help you by bringing a solution to your problem, 23289 or it may not. But in any case the principal function of a bug report 23290 is to help the entire community by making the next version of GDB work 23291 better. Bug reports are your contribution to the maintenance of GDB. 23292 23293 In order for a bug report to serve its purpose, you must include the 23294 information that enables us to fix the bug. 23295 23296 * Menu: 23297 23298 * Bug Criteria:: Have you found a bug? 23299 * Bug Reporting:: How to report bugs 23300 23301 23302 File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs 23303 23304 30.1 Have You Found a Bug? 23305 ========================== 23306 23307 If you are not sure whether you have found a bug, here are some 23308 guidelines: 23309 23310 * If the debugger gets a fatal signal, for any input whatever, that 23311 is a GDB bug. Reliable debuggers never crash. 23312 23313 * If GDB produces an error message for valid input, that is a bug. 23314 (Note that if you're cross debugging, the problem may also be 23315 somewhere in the connection to the target.) 23316 23317 * If GDB does not produce an error message for invalid input, that 23318 is a bug. However, you should note that your idea of "invalid 23319 input" might be our idea of "an extension" or "support for 23320 traditional practice". 23321 23322 * If you are an experienced user of debugging tools, your suggestions 23323 for improvement of GDB are welcome in any case. 23324 23325 23326 File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs 23327 23328 30.2 How to Report Bugs 23329 ======================= 23330 23331 A number of companies and individuals offer support for GNU products. 23332 If you obtained GDB from a support organization, we recommend you 23333 contact that organization first. 23334 23335 You can find contact information for many support companies and 23336 individuals in the file `etc/SERVICE' in the GNU Emacs distribution. 23337 23338 In any event, we also recommend that you submit bug reports for GDB. 23339 The preferred method is to submit them directly using GDB's Bugs web 23340 page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the 23341 e-mail gateway <bug-gdb (a] gnu.org> can be used. 23342 23343 *Do not send bug reports to `info-gdb', or to `help-gdb', or to any 23344 newsgroups.* Most users of GDB do not want to receive bug reports. 23345 Those that do have arranged to receive `bug-gdb'. 23346 23347 The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which 23348 serves as a repeater. The mailing list and the newsgroup carry exactly 23349 the same messages. Often people think of posting bug reports to the 23350 newsgroup instead of mailing them. This appears to work, but it has one 23351 problem which can be crucial: a newsgroup posting often lacks a mail 23352 path back to the sender. Thus, if we need to ask for more information, 23353 we may be unable to reach you. For this reason, it is better to send 23354 bug reports to the mailing list. 23355 23356 The fundamental principle of reporting bugs usefully is this: 23357 *report all the facts*. If you are not sure whether to state a fact or 23358 leave it out, state it! 23359 23360 Often people omit facts because they think they know what causes the 23361 problem and assume that some details do not matter. Thus, you might 23362 assume that the name of the variable you use in an example does not 23363 matter. Well, probably it does not, but one cannot be sure. Perhaps 23364 the bug is a stray memory reference which happens to fetch from the 23365 location where that name is stored in memory; perhaps, if the name were 23366 different, the contents of that location would fool the debugger into 23367 doing the right thing despite the bug. Play it safe and give a 23368 specific, complete example. That is the easiest thing for you to do, 23369 and the most helpful. 23370 23371 Keep in mind that the purpose of a bug report is to enable us to fix 23372 the bug. It may be that the bug has been reported previously, but 23373 neither you nor we can know that unless your bug report is complete and 23374 self-contained. 23375 23376 Sometimes people give a few sketchy facts and ask, "Does this ring a 23377 bell?" Those bug reports are useless, and we urge everyone to _refuse 23378 to respond to them_ except to chide the sender to report bugs properly. 23379 23380 To enable us to fix the bug, you should include all these things: 23381 23382 * The version of GDB. GDB announces it if you start with no 23383 arguments; you can also print it at any time using `show version'. 23384 23385 Without this, we will not know whether there is any point in 23386 looking for the bug in the current version of GDB. 23387 23388 * The type of machine you are using, and the operating system name 23389 and version number. 23390 23391 * What compiler (and its version) was used to compile GDB--e.g. 23392 "gcc-2.8.1". 23393 23394 * What compiler (and its version) was used to compile the program 23395 you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP 23396 C Compiler". For GCC, you can say `gcc --version' to get this 23397 information; for other compilers, see the documentation for those 23398 compilers. 23399 23400 * The command arguments you gave the compiler to compile your 23401 example and observe the bug. For example, did you use `-O'? To 23402 guarantee you will not omit something important, list them all. A 23403 copy of the Makefile (or the output from make) is sufficient. 23404 23405 If we were to try to guess the arguments, we would probably guess 23406 wrong and then we might not encounter the bug. 23407 23408 * A complete input script, and all necessary source files, that will 23409 reproduce the bug. 23410 23411 * A description of what behavior you observe that you believe is 23412 incorrect. For example, "It gets a fatal signal." 23413 23414 Of course, if the bug is that GDB gets a fatal signal, then we 23415 will certainly notice it. But if the bug is incorrect output, we 23416 might not notice unless it is glaringly wrong. You might as well 23417 not give us a chance to make a mistake. 23418 23419 Even if the problem you experience is a fatal signal, you should 23420 still say so explicitly. Suppose something strange is going on, 23421 such as, your copy of GDB is out of synch, or you have encountered 23422 a bug in the C library on your system. (This has happened!) Your 23423 copy might crash and ours would not. If you told us to expect a 23424 crash, then when ours fails to crash, we would know that the bug 23425 was not happening for us. If you had not told us to expect a 23426 crash, then we would not be able to draw any conclusion from our 23427 observations. 23428 23429 To collect all this information, you can use a session recording 23430 program such as `script', which is available on many Unix systems. 23431 Just run your GDB session inside `script' and then include the 23432 `typescript' file with your bug report. 23433 23434 Another way to record a GDB session is to run GDB inside Emacs and 23435 then save the entire buffer to a file. 23436 23437 * If you wish to suggest changes to the GDB source, send us context 23438 diffs. If you even discuss something in the GDB source, refer to 23439 it by context, not by line number. 23440 23441 The line numbers in our development sources will not match those 23442 in your sources. Your line numbers would convey no useful 23443 information to us. 23444 23445 23446 Here are some things that are not necessary: 23447 23448 * A description of the envelope of the bug. 23449 23450 Often people who encounter a bug spend a lot of time investigating 23451 which changes to the input file will make the bug go away and which 23452 changes will not affect it. 23453 23454 This is often time consuming and not very useful, because the way 23455 we will find the bug is by running a single example under the 23456 debugger with breakpoints, not by pure deduction from a series of 23457 examples. We recommend that you save your time for something else. 23458 23459 Of course, if you can find a simpler example to report _instead_ 23460 of the original one, that is a convenience for us. Errors in the 23461 output will be easier to spot, running under the debugger will take 23462 less time, and so on. 23463 23464 However, simplification is not vital; if you do not want to do 23465 this, report the bug anyway and send us the entire test case you 23466 used. 23467 23468 * A patch for the bug. 23469 23470 A patch for the bug does help us if it is a good one. But do not 23471 omit the necessary information, such as the test case, on the 23472 assumption that a patch is all we need. We might see problems 23473 with your patch and decide to fix the problem another way, or we 23474 might not understand it at all. 23475 23476 Sometimes with a program as complicated as GDB it is very hard to 23477 construct an example that will make the program follow a certain 23478 path through the code. If you do not send us the example, we will 23479 not be able to construct one, so we will not be able to verify 23480 that the bug is fixed. 23481 23482 And if we cannot understand what bug you are trying to fix, or why 23483 your patch should be an improvement, we will not install it. A 23484 test case will help us to understand. 23485 23486 * A guess about what the bug is or what it depends on. 23487 23488 Such guesses are usually wrong. Even we cannot guess right about 23489 such things without first using the debugger to find the facts. 23490 23491 23492 File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top 23493 23494 31 Command Line Editing 23495 *********************** 23496 23497 This chapter describes the basic features of the GNU command line 23498 editing interface. 23499 23500 * Menu: 23501 23502 * Introduction and Notation:: Notation used in this text. 23503 * Readline Interaction:: The minimum set of commands for editing a line. 23504 * Readline Init File:: Customizing Readline from a user's view. 23505 * Bindable Readline Commands:: A description of most of the Readline commands 23506 available for binding 23507 * Readline vi Mode:: A short description of how to make Readline 23508 behave like the vi editor. 23509 23510 23511 File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing 23512 23513 31.1 Introduction to Line Editing 23514 ================================= 23515 23516 The following paragraphs describe the notation used to represent 23517 keystrokes. 23518 23519 The text `C-k' is read as `Control-K' and describes the character 23520 produced when the <k> key is pressed while the Control key is depressed. 23521 23522 The text `M-k' is read as `Meta-K' and describes the character 23523 produced when the Meta key (if you have one) is depressed, and the <k> 23524 key is pressed. The Meta key is labeled <ALT> on many keyboards. On 23525 keyboards with two keys labeled <ALT> (usually to either side of the 23526 space bar), the <ALT> on the left side is generally set to work as a 23527 Meta key. The <ALT> key on the right may also be configured to work as 23528 a Meta key or may be configured as some other modifier, such as a 23529 Compose key for typing accented characters. 23530 23531 If you do not have a Meta or <ALT> key, or another key working as a 23532 Meta key, the identical keystroke can be generated by typing <ESC> 23533 _first_, and then typing <k>. Either process is known as "metafying" 23534 the <k> key. 23535 23536 The text `M-C-k' is read as `Meta-Control-k' and describes the 23537 character produced by "metafying" `C-k'. 23538 23539 In addition, several keys have their own names. Specifically, 23540 <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves 23541 when seen in this text, or in an init file (*note Readline Init File::). 23542 If your keyboard lacks a <LFD> key, typing <C-j> will produce the 23543 desired character. The <RET> key may be labeled <Return> or <Enter> on 23544 some keyboards. 23545 23546 23547 File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing 23548 23549 31.2 Readline Interaction 23550 ========================= 23551 23552 Often during an interactive session you type in a long line of text, 23553 only to notice that the first word on the line is misspelled. The 23554 Readline library gives you a set of commands for manipulating the text 23555 as you type it in, allowing you to just fix your typo, and not forcing 23556 you to retype the majority of the line. Using these editing commands, 23557 you move the cursor to the place that needs correction, and delete or 23558 insert the text of the corrections. Then, when you are satisfied with 23559 the line, you simply press <RET>. You do not have to be at the end of 23560 the line to press <RET>; the entire line is accepted regardless of the 23561 location of the cursor within the line. 23562 23563 * Menu: 23564 23565 * Readline Bare Essentials:: The least you need to know about Readline. 23566 * Readline Movement Commands:: Moving about the input line. 23567 * Readline Killing Commands:: How to delete text, and how to get it back! 23568 * Readline Arguments:: Giving numeric arguments to commands. 23569 * Searching:: Searching through previous lines. 23570 23571 23572 File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction 23573 23574 31.2.1 Readline Bare Essentials 23575 ------------------------------- 23576 23577 In order to enter characters into the line, simply type them. The typed 23578 character appears where the cursor was, and then the cursor moves one 23579 space to the right. If you mistype a character, you can use your erase 23580 character to back up and delete the mistyped character. 23581 23582 Sometimes you may mistype a character, and not notice the error 23583 until you have typed several other characters. In that case, you can 23584 type `C-b' to move the cursor to the left, and then correct your 23585 mistake. Afterwards, you can move the cursor to the right with `C-f'. 23586 23587 When you add text in the middle of a line, you will notice that 23588 characters to the right of the cursor are `pushed over' to make room 23589 for the text that you have inserted. Likewise, when you delete text 23590 behind the cursor, characters to the right of the cursor are `pulled 23591 back' to fill in the blank space created by the removal of the text. A 23592 list of the bare essentials for editing the text of an input line 23593 follows. 23594 23595 `C-b' 23596 Move back one character. 23597 23598 `C-f' 23599 Move forward one character. 23600 23601 <DEL> or <Backspace> 23602 Delete the character to the left of the cursor. 23603 23604 `C-d' 23605 Delete the character underneath the cursor. 23606 23607 Printing characters 23608 Insert the character into the line at the cursor. 23609 23610 `C-_' or `C-x C-u' 23611 Undo the last editing command. You can undo all the way back to an 23612 empty line. 23613 23614 (Depending on your configuration, the <Backspace> key be set to delete 23615 the character to the left of the cursor and the <DEL> key set to delete 23616 the character underneath the cursor, like `C-d', rather than the 23617 character to the left of the cursor.) 23618 23619 23620 File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction 23621 23622 31.2.2 Readline Movement Commands 23623 --------------------------------- 23624 23625 The above table describes the most basic keystrokes that you need in 23626 order to do editing of the input line. For your convenience, many 23627 other commands have been added in addition to `C-b', `C-f', `C-d', and 23628 <DEL>. Here are some commands for moving more rapidly about the line. 23629 23630 `C-a' 23631 Move to the start of the line. 23632 23633 `C-e' 23634 Move to the end of the line. 23635 23636 `M-f' 23637 Move forward a word, where a word is composed of letters and 23638 digits. 23639 23640 `M-b' 23641 Move backward a word. 23642 23643 `C-l' 23644 Clear the screen, reprinting the current line at the top. 23645 23646 Notice how `C-f' moves forward a character, while `M-f' moves 23647 forward a word. It is a loose convention that control keystrokes 23648 operate on characters while meta keystrokes operate on words. 23649 23650 23651 File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction 23652 23653 31.2.3 Readline Killing Commands 23654 -------------------------------- 23655 23656 "Killing" text means to delete the text from the line, but to save it 23657 away for later use, usually by "yanking" (re-inserting) it back into 23658 the line. (`Cut' and `paste' are more recent jargon for `kill' and 23659 `yank'.) 23660 23661 If the description for a command says that it `kills' text, then you 23662 can be sure that you can get the text back in a different (or the same) 23663 place later. 23664 23665 When you use a kill command, the text is saved in a "kill-ring". 23666 Any number of consecutive kills save all of the killed text together, so 23667 that when you yank it back, you get it all. The kill ring is not line 23668 specific; the text that you killed on a previously typed line is 23669 available to be yanked back later, when you are typing another line. 23670 23671 Here is the list of commands for killing text. 23672 23673 `C-k' 23674 Kill the text from the current cursor position to the end of the 23675 line. 23676 23677 `M-d' 23678 Kill from the cursor to the end of the current word, or, if between 23679 words, to the end of the next word. Word boundaries are the same 23680 as those used by `M-f'. 23681 23682 `M-<DEL>' 23683 Kill from the cursor the start of the current word, or, if between 23684 words, to the start of the previous word. Word boundaries are the 23685 same as those used by `M-b'. 23686 23687 `C-w' 23688 Kill from the cursor to the previous whitespace. This is 23689 different than `M-<DEL>' because the word boundaries differ. 23690 23691 23692 Here is how to "yank" the text back into the line. Yanking means to 23693 copy the most-recently-killed text from the kill buffer. 23694 23695 `C-y' 23696 Yank the most recently killed text back into the buffer at the 23697 cursor. 23698 23699 `M-y' 23700 Rotate the kill-ring, and yank the new top. You can only do this 23701 if the prior command is `C-y' or `M-y'. 23702 23703 23704 File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction 23705 23706 31.2.4 Readline Arguments 23707 ------------------------- 23708 23709 You can pass numeric arguments to Readline commands. Sometimes the 23710 argument acts as a repeat count, other times it is the sign of the 23711 argument that is significant. If you pass a negative argument to a 23712 command which normally acts in a forward direction, that command will 23713 act in a backward direction. For example, to kill text back to the 23714 start of the line, you might type `M-- C-k'. 23715 23716 The general way to pass numeric arguments to a command is to type 23717 meta digits before the command. If the first `digit' typed is a minus 23718 sign (`-'), then the sign of the argument will be negative. Once you 23719 have typed one meta digit to get the argument started, you can type the 23720 remainder of the digits, and then the command. For example, to give 23721 the `C-d' command an argument of 10, you could type `M-1 0 C-d', which 23722 will delete the next ten characters on the input line. 23723 23724 23725 File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction 23726 23727 31.2.5 Searching for Commands in the History 23728 -------------------------------------------- 23729 23730 Readline provides commands for searching through the command history 23731 for lines containing a specified string. There are two search modes: 23732 "incremental" and "non-incremental". 23733 23734 Incremental searches begin before the user has finished typing the 23735 search string. As each character of the search string is typed, 23736 Readline displays the next entry from the history matching the string 23737 typed so far. An incremental search requires only as many characters 23738 as needed to find the desired history entry. To search backward in the 23739 history for a particular string, type `C-r'. Typing `C-s' searches 23740 forward through the history. The characters present in the value of 23741 the `isearch-terminators' variable are used to terminate an incremental 23742 search. If that variable has not been assigned a value, the <ESC> and 23743 `C-J' characters will terminate an incremental search. `C-g' will 23744 abort an incremental search and restore the original line. When the 23745 search is terminated, the history entry containing the search string 23746 becomes the current line. 23747 23748 To find other matching entries in the history list, type `C-r' or 23749 `C-s' as appropriate. This will search backward or forward in the 23750 history for the next entry matching the search string typed so far. 23751 Any other key sequence bound to a Readline command will terminate the 23752 search and execute that command. For instance, a <RET> will terminate 23753 the search and accept the line, thereby executing the command from the 23754 history list. A movement command will terminate the search, make the 23755 last line found the current line, and begin editing. 23756 23757 Readline remembers the last incremental search string. If two 23758 `C-r's are typed without any intervening characters defining a new 23759 search string, any remembered search string is used. 23760 23761 Non-incremental searches read the entire search string before 23762 starting to search for matching history lines. The search string may be 23763 typed by the user or be part of the contents of the current line. 23764 23765 23766 File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing 23767 23768 31.3 Readline Init File 23769 ======================= 23770 23771 Although the Readline library comes with a set of Emacs-like 23772 keybindings installed by default, it is possible to use a different set 23773 of keybindings. Any user can customize programs that use Readline by 23774 putting commands in an "inputrc" file, conventionally in his home 23775 directory. The name of this file is taken from the value of the 23776 environment variable `INPUTRC'. If that variable is unset, the default 23777 is `~/.inputrc'. 23778 23779 When a program which uses the Readline library starts up, the init 23780 file is read, and the key bindings are set. 23781 23782 In addition, the `C-x C-r' command re-reads this init file, thus 23783 incorporating any changes that you might have made to it. 23784 23785 * Menu: 23786 23787 * Readline Init File Syntax:: Syntax for the commands in the inputrc file. 23788 23789 * Conditional Init Constructs:: Conditional key bindings in the inputrc file. 23790 23791 * Sample Init File:: An example inputrc file. 23792 23793 23794 File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File 23795 23796 31.3.1 Readline Init File Syntax 23797 -------------------------------- 23798 23799 There are only a few basic constructs allowed in the Readline init 23800 file. Blank lines are ignored. Lines beginning with a `#' are 23801 comments. Lines beginning with a `$' indicate conditional constructs 23802 (*note Conditional Init Constructs::). Other lines denote variable 23803 settings and key bindings. 23804 23805 Variable Settings 23806 You can modify the run-time behavior of Readline by altering the 23807 values of variables in Readline using the `set' command within the 23808 init file. The syntax is simple: 23809 23810 set VARIABLE VALUE 23811 23812 Here, for example, is how to change from the default Emacs-like 23813 key binding to use `vi' line editing commands: 23814 23815 set editing-mode vi 23816 23817 Variable names and values, where appropriate, are recognized 23818 without regard to case. Unrecognized variable names are ignored. 23819 23820 Boolean variables (those that can be set to on or off) are set to 23821 on if the value is null or empty, ON (case-insensitive), or 1. 23822 Any other value results in the variable being set to off. 23823 23824 A great deal of run-time behavior is changeable with the following 23825 variables. 23826 23827 `bell-style' 23828 Controls what happens when Readline wants to ring the 23829 terminal bell. If set to `none', Readline never rings the 23830 bell. If set to `visible', Readline uses a visible bell if 23831 one is available. If set to `audible' (the default), 23832 Readline attempts to ring the terminal's bell. 23833 23834 `bind-tty-special-chars' 23835 If set to `on', Readline attempts to bind the control 23836 characters treated specially by the kernel's terminal driver 23837 to their Readline equivalents. 23838 23839 `comment-begin' 23840 The string to insert at the beginning of the line when the 23841 `insert-comment' command is executed. The default value is 23842 `"#"'. 23843 23844 `completion-ignore-case' 23845 If set to `on', Readline performs filename matching and 23846 completion in a case-insensitive fashion. The default value 23847 is `off'. 23848 23849 `completion-query-items' 23850 The number of possible completions that determines when the 23851 user is asked whether the list of possibilities should be 23852 displayed. If the number of possible completions is greater 23853 than this value, Readline will ask the user whether or not he 23854 wishes to view them; otherwise, they are simply listed. This 23855 variable must be set to an integer value greater than or 23856 equal to 0. A negative value means Readline should never ask. 23857 The default limit is `100'. 23858 23859 `convert-meta' 23860 If set to `on', Readline will convert characters with the 23861 eighth bit set to an ASCII key sequence by stripping the 23862 eighth bit and prefixing an <ESC> character, converting them 23863 to a meta-prefixed key sequence. The default value is `on'. 23864 23865 `disable-completion' 23866 If set to `On', Readline will inhibit word completion. 23867 Completion characters will be inserted into the line as if 23868 they had been mapped to `self-insert'. The default is `off'. 23869 23870 `editing-mode' 23871 The `editing-mode' variable controls which default set of key 23872 bindings is used. By default, Readline starts up in Emacs 23873 editing mode, where the keystrokes are most similar to Emacs. 23874 This variable can be set to either `emacs' or `vi'. 23875 23876 `enable-keypad' 23877 When set to `on', Readline will try to enable the application 23878 keypad when it is called. Some systems need this to enable 23879 the arrow keys. The default is `off'. 23880 23881 `expand-tilde' 23882 If set to `on', tilde expansion is performed when Readline 23883 attempts word completion. The default is `off'. 23884 23885 `history-preserve-point' 23886 If set to `on', the history code attempts to place point at 23887 the same location on each history line retrieved with 23888 `previous-history' or `next-history'. The default is `off'. 23889 23890 `horizontal-scroll-mode' 23891 This variable can be set to either `on' or `off'. Setting it 23892 to `on' means that the text of the lines being edited will 23893 scroll horizontally on a single screen line when they are 23894 longer than the width of the screen, instead of wrapping onto 23895 a new screen line. By default, this variable is set to `off'. 23896 23897 `input-meta' 23898 If set to `on', Readline will enable eight-bit input (it will 23899 not clear the eighth bit in the characters it reads), 23900 regardless of what the terminal claims it can support. The 23901 default value is `off'. The name `meta-flag' is a synonym 23902 for this variable. 23903 23904 `isearch-terminators' 23905 The string of characters that should terminate an incremental 23906 search without subsequently executing the character as a 23907 command (*note Searching::). If this variable has not been 23908 given a value, the characters <ESC> and `C-J' will terminate 23909 an incremental search. 23910 23911 `keymap' 23912 Sets Readline's idea of the current keymap for key binding 23913 commands. Acceptable `keymap' names are `emacs', 23914 `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', 23915 `vi-command', and `vi-insert'. `vi' is equivalent to 23916 `vi-command'; `emacs' is equivalent to `emacs-standard'. The 23917 default value is `emacs'. The value of the `editing-mode' 23918 variable also affects the default keymap. 23919 23920 `mark-directories' 23921 If set to `on', completed directory names have a slash 23922 appended. The default is `on'. 23923 23924 `mark-modified-lines' 23925 This variable, when set to `on', causes Readline to display an 23926 asterisk (`*') at the start of history lines which have been 23927 modified. This variable is `off' by default. 23928 23929 `mark-symlinked-directories' 23930 If set to `on', completed names which are symbolic links to 23931 directories have a slash appended (subject to the value of 23932 `mark-directories'). The default is `off'. 23933 23934 `match-hidden-files' 23935 This variable, when set to `on', causes Readline to match 23936 files whose names begin with a `.' (hidden files) when 23937 performing filename completion, unless the leading `.' is 23938 supplied by the user in the filename to be completed. This 23939 variable is `on' by default. 23940 23941 `output-meta' 23942 If set to `on', Readline will display characters with the 23943 eighth bit set directly rather than as a meta-prefixed escape 23944 sequence. The default is `off'. 23945 23946 `page-completions' 23947 If set to `on', Readline uses an internal `more'-like pager 23948 to display a screenful of possible completions at a time. 23949 This variable is `on' by default. 23950 23951 `print-completions-horizontally' 23952 If set to `on', Readline will display completions with matches 23953 sorted horizontally in alphabetical order, rather than down 23954 the screen. The default is `off'. 23955 23956 `show-all-if-ambiguous' 23957 This alters the default behavior of the completion functions. 23958 If set to `on', words which have more than one possible 23959 completion cause the matches to be listed immediately instead 23960 of ringing the bell. The default value is `off'. 23961 23962 `show-all-if-unmodified' 23963 This alters the default behavior of the completion functions 23964 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to 23965 `on', words which have more than one possible completion 23966 without any possible partial completion (the possible 23967 completions don't share a common prefix) cause the matches to 23968 be listed immediately instead of ringing the bell. The 23969 default value is `off'. 23970 23971 `visible-stats' 23972 If set to `on', a character denoting a file's type is 23973 appended to the filename when listing possible completions. 23974 The default is `off'. 23975 23976 23977 Key Bindings 23978 The syntax for controlling key bindings in the init file is 23979 simple. First you need to find the name of the command that you 23980 want to change. The following sections contain tables of the 23981 command name, the default keybinding, if any, and a short 23982 description of what the command does. 23983 23984 Once you know the name of the command, simply place on a line in 23985 the init file the name of the key you wish to bind the command to, 23986 a colon, and then the name of the command. The name of the key 23987 can be expressed in different ways, depending on what you find most 23988 comfortable. 23989 23990 In addition to command names, readline allows keys to be bound to 23991 a string that is inserted when the key is pressed (a MACRO). 23992 23993 KEYNAME: FUNCTION-NAME or MACRO 23994 KEYNAME is the name of a key spelled out in English. For 23995 example: 23996 Control-u: universal-argument 23997 Meta-Rubout: backward-kill-word 23998 Control-o: "> output" 23999 24000 In the above example, `C-u' is bound to the function 24001 `universal-argument', `M-DEL' is bound to the function 24002 `backward-kill-word', and `C-o' is bound to run the macro 24003 expressed on the right hand side (that is, to insert the text 24004 `> output' into the line). 24005 24006 A number of symbolic character names are recognized while 24007 processing this key binding syntax: DEL, ESC, ESCAPE, LFD, 24008 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. 24009 24010 "KEYSEQ": FUNCTION-NAME or MACRO 24011 KEYSEQ differs from KEYNAME above in that strings denoting an 24012 entire key sequence can be specified, by placing the key 24013 sequence in double quotes. Some GNU Emacs style key escapes 24014 can be used, as in the following example, but the special 24015 character names are not recognized. 24016 24017 "\C-u": universal-argument 24018 "\C-x\C-r": re-read-init-file 24019 "\e[11~": "Function Key 1" 24020 24021 In the above example, `C-u' is again bound to the function 24022 `universal-argument' (just as it was in the first example), 24023 `C-x C-r' is bound to the function `re-read-init-file', and 24024 `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function 24025 Key 1'. 24026 24027 24028 The following GNU Emacs style escape sequences are available when 24029 specifying key sequences: 24030 24031 `\C-' 24032 control prefix 24033 24034 `\M-' 24035 meta prefix 24036 24037 `\e' 24038 an escape character 24039 24040 `\\' 24041 backslash 24042 24043 `\"' 24044 <">, a double quotation mark 24045 24046 `\'' 24047 <'>, a single quote or apostrophe 24048 24049 In addition to the GNU Emacs style escape sequences, a second set 24050 of backslash escapes is available: 24051 24052 `\a' 24053 alert (bell) 24054 24055 `\b' 24056 backspace 24057 24058 `\d' 24059 delete 24060 24061 `\f' 24062 form feed 24063 24064 `\n' 24065 newline 24066 24067 `\r' 24068 carriage return 24069 24070 `\t' 24071 horizontal tab 24072 24073 `\v' 24074 vertical tab 24075 24076 `\NNN' 24077 the eight-bit character whose value is the octal value NNN 24078 (one to three digits) 24079 24080 `\xHH' 24081 the eight-bit character whose value is the hexadecimal value 24082 HH (one or two hex digits) 24083 24084 When entering the text of a macro, single or double quotes must be 24085 used to indicate a macro definition. Unquoted text is assumed to 24086 be a function name. In the macro body, the backslash escapes 24087 described above are expanded. Backslash will quote any other 24088 character in the macro text, including `"' and `''. For example, 24089 the following binding will make `C-x \' insert a single `\' into 24090 the line: 24091 "\C-x\\": "\\" 24092 24093 24094 24095 File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File 24096 24097 31.3.2 Conditional Init Constructs 24098 ---------------------------------- 24099 24100 Readline implements a facility similar in spirit to the conditional 24101 compilation features of the C preprocessor which allows key bindings 24102 and variable settings to be performed as the result of tests. There 24103 are four parser directives used. 24104 24105 `$if' 24106 The `$if' construct allows bindings to be made based on the 24107 editing mode, the terminal being used, or the application using 24108 Readline. The text of the test extends to the end of the line; no 24109 characters are required to isolate it. 24110 24111 `mode' 24112 The `mode=' form of the `$if' directive is used to test 24113 whether Readline is in `emacs' or `vi' mode. This may be 24114 used in conjunction with the `set keymap' command, for 24115 instance, to set bindings in the `emacs-standard' and 24116 `emacs-ctlx' keymaps only if Readline is starting out in 24117 `emacs' mode. 24118 24119 `term' 24120 The `term=' form may be used to include terminal-specific key 24121 bindings, perhaps to bind the key sequences output by the 24122 terminal's function keys. The word on the right side of the 24123 `=' is tested against both the full name of the terminal and 24124 the portion of the terminal name before the first `-'. This 24125 allows `sun' to match both `sun' and `sun-cmd', for instance. 24126 24127 `application' 24128 The APPLICATION construct is used to include 24129 application-specific settings. Each program using the 24130 Readline library sets the APPLICATION NAME, and you can test 24131 for a particular value. This could be used to bind key 24132 sequences to functions useful for a specific program. For 24133 instance, the following command adds a key sequence that 24134 quotes the current or previous word in Bash: 24135 $if Bash 24136 # Quote the current or previous word 24137 "\C-xq": "\eb\"\ef\"" 24138 $endif 24139 24140 `$endif' 24141 This command, as seen in the previous example, terminates an `$if' 24142 command. 24143 24144 `$else' 24145 Commands in this branch of the `$if' directive are executed if the 24146 test fails. 24147 24148 `$include' 24149 This directive takes a single filename as an argument and reads 24150 commands and bindings from that file. For example, the following 24151 directive reads from `/etc/inputrc': 24152 $include /etc/inputrc 24153 24154 24155 File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File 24156 24157 31.3.3 Sample Init File 24158 ----------------------- 24159 24160 Here is an example of an INPUTRC file. This illustrates key binding, 24161 variable assignment, and conditional syntax. 24162 24163 24164 # This file controls the behaviour of line input editing for 24165 # programs that use the GNU Readline library. Existing 24166 # programs include FTP, Bash, and GDB. 24167 # 24168 # You can re-read the inputrc file with C-x C-r. 24169 # Lines beginning with '#' are comments. 24170 # 24171 # First, include any systemwide bindings and variable 24172 # assignments from /etc/Inputrc 24173 $include /etc/Inputrc 24174 24175 # 24176 # Set various bindings for emacs mode. 24177 24178 set editing-mode emacs 24179 24180 $if mode=emacs 24181 24182 Meta-Control-h: backward-kill-word Text after the function name is ignored 24183 24184 # 24185 # Arrow keys in keypad mode 24186 # 24187 #"\M-OD": backward-char 24188 #"\M-OC": forward-char 24189 #"\M-OA": previous-history 24190 #"\M-OB": next-history 24191 # 24192 # Arrow keys in ANSI mode 24193 # 24194 "\M-[D": backward-char 24195 "\M-[C": forward-char 24196 "\M-[A": previous-history 24197 "\M-[B": next-history 24198 # 24199 # Arrow keys in 8 bit keypad mode 24200 # 24201 #"\M-\C-OD": backward-char 24202 #"\M-\C-OC": forward-char 24203 #"\M-\C-OA": previous-history 24204 #"\M-\C-OB": next-history 24205 # 24206 # Arrow keys in 8 bit ANSI mode 24207 # 24208 #"\M-\C-[D": backward-char 24209 #"\M-\C-[C": forward-char 24210 #"\M-\C-[A": previous-history 24211 #"\M-\C-[B": next-history 24212 24213 C-q: quoted-insert 24214 24215 $endif 24216 24217 # An old-style binding. This happens to be the default. 24218 TAB: complete 24219 24220 # Macros that are convenient for shell interaction 24221 $if Bash 24222 # edit the path 24223 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" 24224 # prepare to type a quoted word -- 24225 # insert open and close double quotes 24226 # and move to just after the open quote 24227 "\C-x\"": "\"\"\C-b" 24228 # insert a backslash (testing backslash escapes 24229 # in sequences and macros) 24230 "\C-x\\": "\\" 24231 # Quote the current or previous word 24232 "\C-xq": "\eb\"\ef\"" 24233 # Add a binding to refresh the line, which is unbound 24234 "\C-xr": redraw-current-line 24235 # Edit variable on current line. 24236 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" 24237 $endif 24238 24239 # use a visible bell if one is available 24240 set bell-style visible 24241 24242 # don't strip characters to 7 bits when reading 24243 set input-meta on 24244 24245 # allow iso-latin1 characters to be inserted rather 24246 # than converted to prefix-meta sequences 24247 set convert-meta off 24248 24249 # display characters with the eighth bit set directly 24250 # rather than as meta-prefixed characters 24251 set output-meta on 24252 24253 # if there are more than 150 possible completions for 24254 # a word, ask the user if he wants to see all of them 24255 set completion-query-items 150 24256 24257 # For FTP 24258 $if Ftp 24259 "\C-xg": "get \M-?" 24260 "\C-xt": "put \M-?" 24261 "\M-.": yank-last-arg 24262 $endif 24263 24264 24265 File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing 24266 24267 31.4 Bindable Readline Commands 24268 =============================== 24269 24270 * Menu: 24271 24272 * Commands For Moving:: Moving about the line. 24273 * Commands For History:: Getting at previous lines. 24274 * Commands For Text:: Commands for changing text. 24275 * Commands For Killing:: Commands for killing and yanking. 24276 * Numeric Arguments:: Specifying numeric arguments, repeat counts. 24277 * Commands For Completion:: Getting Readline to do the typing for you. 24278 * Keyboard Macros:: Saving and re-executing typed characters 24279 * Miscellaneous Commands:: Other miscellaneous commands. 24280 24281 This section describes Readline commands that may be bound to key 24282 sequences. Command names without an accompanying key sequence are 24283 unbound by default. 24284 24285 In the following descriptions, "point" refers to the current cursor 24286 position, and "mark" refers to a cursor position saved by the 24287 `set-mark' command. The text between the point and mark is referred to 24288 as the "region". 24289 24290 24291 File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands 24292 24293 31.4.1 Commands For Moving 24294 -------------------------- 24295 24296 `beginning-of-line (C-a)' 24297 Move to the start of the current line. 24298 24299 `end-of-line (C-e)' 24300 Move to the end of the line. 24301 24302 `forward-char (C-f)' 24303 Move forward a character. 24304 24305 `backward-char (C-b)' 24306 Move back a character. 24307 24308 `forward-word (M-f)' 24309 Move forward to the end of the next word. Words are composed of 24310 letters and digits. 24311 24312 `backward-word (M-b)' 24313 Move back to the start of the current or previous word. Words are 24314 composed of letters and digits. 24315 24316 `clear-screen (C-l)' 24317 Clear the screen and redraw the current line, leaving the current 24318 line at the top of the screen. 24319 24320 `redraw-current-line ()' 24321 Refresh the current line. By default, this is unbound. 24322 24323 24324 24325 File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands 24326 24327 31.4.2 Commands For Manipulating The History 24328 -------------------------------------------- 24329 24330 `accept-line (Newline or Return)' 24331 Accept the line regardless of where the cursor is. If this line is 24332 non-empty, it may be added to the history list for future recall 24333 with `add_history()'. If this line is a modified history line, 24334 the history line is restored to its original state. 24335 24336 `previous-history (C-p)' 24337 Move `back' through the history list, fetching the previous 24338 command. 24339 24340 `next-history (C-n)' 24341 Move `forward' through the history list, fetching the next command. 24342 24343 `beginning-of-history (M-<)' 24344 Move to the first line in the history. 24345 24346 `end-of-history (M->)' 24347 Move to the end of the input history, i.e., the line currently 24348 being entered. 24349 24350 `reverse-search-history (C-r)' 24351 Search backward starting at the current line and moving `up' 24352 through the history as necessary. This is an incremental search. 24353 24354 `forward-search-history (C-s)' 24355 Search forward starting at the current line and moving `down' 24356 through the the history as necessary. This is an incremental 24357 search. 24358 24359 `non-incremental-reverse-search-history (M-p)' 24360 Search backward starting at the current line and moving `up' 24361 through the history as necessary using a non-incremental search 24362 for a string supplied by the user. 24363 24364 `non-incremental-forward-search-history (M-n)' 24365 Search forward starting at the current line and moving `down' 24366 through the the history as necessary using a non-incremental search 24367 for a string supplied by the user. 24368 24369 `history-search-forward ()' 24370 Search forward through the history for the string of characters 24371 between the start of the current line and the point. This is a 24372 non-incremental search. By default, this command is unbound. 24373 24374 `history-search-backward ()' 24375 Search backward through the history for the string of characters 24376 between the start of the current line and the point. This is a 24377 non-incremental search. By default, this command is unbound. 24378 24379 `yank-nth-arg (M-C-y)' 24380 Insert the first argument to the previous command (usually the 24381 second word on the previous line) at point. With an argument N, 24382 insert the Nth word from the previous command (the words in the 24383 previous command begin with word 0). A negative argument inserts 24384 the Nth word from the end of the previous command. Once the 24385 argument N is computed, the argument is extracted as if the `!N' 24386 history expansion had been specified. 24387 24388 `yank-last-arg (M-. or M-_)' 24389 Insert last argument to the previous command (the last word of the 24390 previous history entry). With an argument, behave exactly like 24391 `yank-nth-arg'. Successive calls to `yank-last-arg' move back 24392 through the history list, inserting the last argument of each line 24393 in turn. The history expansion facilities are used to extract the 24394 last argument, as if the `!$' history expansion had been specified. 24395 24396 24397 24398 File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands 24399 24400 31.4.3 Commands For Changing Text 24401 --------------------------------- 24402 24403 `delete-char (C-d)' 24404 Delete the character at point. If point is at the beginning of 24405 the line, there are no characters in the line, and the last 24406 character typed was not bound to `delete-char', then return EOF. 24407 24408 `backward-delete-char (Rubout)' 24409 Delete the character behind the cursor. A numeric argument means 24410 to kill the characters instead of deleting them. 24411 24412 `forward-backward-delete-char ()' 24413 Delete the character under the cursor, unless the cursor is at the 24414 end of the line, in which case the character behind the cursor is 24415 deleted. By default, this is not bound to a key. 24416 24417 `quoted-insert (C-q or C-v)' 24418 Add the next character typed to the line verbatim. This is how to 24419 insert key sequences like `C-q', for example. 24420 24421 `tab-insert (M-<TAB>)' 24422 Insert a tab character. 24423 24424 `self-insert (a, b, A, 1, !, ...)' 24425 Insert yourself. 24426 24427 `transpose-chars (C-t)' 24428 Drag the character before the cursor forward over the character at 24429 the cursor, moving the cursor forward as well. If the insertion 24430 point is at the end of the line, then this transposes the last two 24431 characters of the line. Negative arguments have no effect. 24432 24433 `transpose-words (M-t)' 24434 Drag the word before point past the word after point, moving point 24435 past that word as well. If the insertion point is at the end of 24436 the line, this transposes the last two words on the line. 24437 24438 `upcase-word (M-u)' 24439 Uppercase the current (or following) word. With a negative 24440 argument, uppercase the previous word, but do not move the cursor. 24441 24442 `downcase-word (M-l)' 24443 Lowercase the current (or following) word. With a negative 24444 argument, lowercase the previous word, but do not move the cursor. 24445 24446 `capitalize-word (M-c)' 24447 Capitalize the current (or following) word. With a negative 24448 argument, capitalize the previous word, but do not move the cursor. 24449 24450 `overwrite-mode ()' 24451 Toggle overwrite mode. With an explicit positive numeric argument, 24452 switches to overwrite mode. With an explicit non-positive numeric 24453 argument, switches to insert mode. This command affects only 24454 `emacs' mode; `vi' mode does overwrite differently. Each call to 24455 `readline()' starts in insert mode. 24456 24457 In overwrite mode, characters bound to `self-insert' replace the 24458 text at point rather than pushing the text to the right. 24459 Characters bound to `backward-delete-char' replace the character 24460 before point with a space. 24461 24462 By default, this command is unbound. 24463 24464 24465 24466 File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands 24467 24468 31.4.4 Killing And Yanking 24469 -------------------------- 24470 24471 `kill-line (C-k)' 24472 Kill the text from point to the end of the line. 24473 24474 `backward-kill-line (C-x Rubout)' 24475 Kill backward to the beginning of the line. 24476 24477 `unix-line-discard (C-u)' 24478 Kill backward from the cursor to the beginning of the current line. 24479 24480 `kill-whole-line ()' 24481 Kill all characters on the current line, no matter where point is. 24482 By default, this is unbound. 24483 24484 `kill-word (M-d)' 24485 Kill from point to the end of the current word, or if between 24486 words, to the end of the next word. Word boundaries are the same 24487 as `forward-word'. 24488 24489 `backward-kill-word (M-<DEL>)' 24490 Kill the word behind point. Word boundaries are the same as 24491 `backward-word'. 24492 24493 `unix-word-rubout (C-w)' 24494 Kill the word behind point, using white space as a word boundary. 24495 The killed text is saved on the kill-ring. 24496 24497 `unix-filename-rubout ()' 24498 Kill the word behind point, using white space and the slash 24499 character as the word boundaries. The killed text is saved on the 24500 kill-ring. 24501 24502 `delete-horizontal-space ()' 24503 Delete all spaces and tabs around point. By default, this is 24504 unbound. 24505 24506 `kill-region ()' 24507 Kill the text in the current region. By default, this command is 24508 unbound. 24509 24510 `copy-region-as-kill ()' 24511 Copy the text in the region to the kill buffer, so it can be yanked 24512 right away. By default, this command is unbound. 24513 24514 `copy-backward-word ()' 24515 Copy the word before point to the kill buffer. The word 24516 boundaries are the same as `backward-word'. By default, this 24517 command is unbound. 24518 24519 `copy-forward-word ()' 24520 Copy the word following point to the kill buffer. The word 24521 boundaries are the same as `forward-word'. By default, this 24522 command is unbound. 24523 24524 `yank (C-y)' 24525 Yank the top of the kill ring into the buffer at point. 24526 24527 `yank-pop (M-y)' 24528 Rotate the kill-ring, and yank the new top. You can only do this 24529 if the prior command is `yank' or `yank-pop'. 24530 24531 24532 File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands 24533 24534 31.4.5 Specifying Numeric Arguments 24535 ----------------------------------- 24536 24537 `digit-argument (M-0, M-1, ... M--)' 24538 Add this digit to the argument already accumulating, or start a new 24539 argument. `M--' starts a negative argument. 24540 24541 `universal-argument ()' 24542 This is another way to specify an argument. If this command is 24543 followed by one or more digits, optionally with a leading minus 24544 sign, those digits define the argument. If the command is 24545 followed by digits, executing `universal-argument' again ends the 24546 numeric argument, but is otherwise ignored. As a special case, if 24547 this command is immediately followed by a character that is 24548 neither a digit or minus sign, the argument count for the next 24549 command is multiplied by four. The argument count is initially 24550 one, so executing this function the first time makes the argument 24551 count four, a second time makes the argument count sixteen, and so 24552 on. By default, this is not bound to a key. 24553 24554 24555 File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands 24556 24557 31.4.6 Letting Readline Type For You 24558 ------------------------------------ 24559 24560 `complete (<TAB>)' 24561 Attempt to perform completion on the text before point. The 24562 actual completion performed is application-specific. The default 24563 is filename completion. 24564 24565 `possible-completions (M-?)' 24566 List the possible completions of the text before point. 24567 24568 `insert-completions (M-*)' 24569 Insert all completions of the text before point that would have 24570 been generated by `possible-completions'. 24571 24572 `menu-complete ()' 24573 Similar to `complete', but replaces the word to be completed with 24574 a single match from the list of possible completions. Repeated 24575 execution of `menu-complete' steps through the list of possible 24576 completions, inserting each match in turn. At the end of the list 24577 of completions, the bell is rung (subject to the setting of 24578 `bell-style') and the original text is restored. An argument of N 24579 moves N positions forward in the list of matches; a negative 24580 argument may be used to move backward through the list. This 24581 command is intended to be bound to <TAB>, but is unbound by 24582 default. 24583 24584 `delete-char-or-list ()' 24585 Deletes the character under the cursor if not at the beginning or 24586 end of the line (like `delete-char'). If at the end of the line, 24587 behaves identically to `possible-completions'. This command is 24588 unbound by default. 24589 24590 24591 24592 File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands 24593 24594 31.4.7 Keyboard Macros 24595 ---------------------- 24596 24597 `start-kbd-macro (C-x ()' 24598 Begin saving the characters typed into the current keyboard macro. 24599 24600 `end-kbd-macro (C-x ))' 24601 Stop saving the characters typed into the current keyboard macro 24602 and save the definition. 24603 24604 `call-last-kbd-macro (C-x e)' 24605 Re-execute the last keyboard macro defined, by making the 24606 characters in the macro appear as if typed at the keyboard. 24607 24608 24609 24610 File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands 24611 24612 31.4.8 Some Miscellaneous Commands 24613 ---------------------------------- 24614 24615 `re-read-init-file (C-x C-r)' 24616 Read in the contents of the INPUTRC file, and incorporate any 24617 bindings or variable assignments found there. 24618 24619 `abort (C-g)' 24620 Abort the current editing command and ring the terminal's bell 24621 (subject to the setting of `bell-style'). 24622 24623 `do-uppercase-version (M-a, M-b, M-X, ...)' 24624 If the metafied character X is lowercase, run the command that is 24625 bound to the corresponding uppercase character. 24626 24627 `prefix-meta (<ESC>)' 24628 Metafy the next character typed. This is for keyboards without a 24629 meta key. Typing `<ESC> f' is equivalent to typing `M-f'. 24630 24631 `undo (C-_ or C-x C-u)' 24632 Incremental undo, separately remembered for each line. 24633 24634 `revert-line (M-r)' 24635 Undo all changes made to this line. This is like executing the 24636 `undo' command enough times to get back to the beginning. 24637 24638 `tilde-expand (M-~)' 24639 Perform tilde expansion on the current word. 24640 24641 `set-mark (C-@)' 24642 Set the mark to the point. If a numeric argument is supplied, the 24643 mark is set to that position. 24644 24645 `exchange-point-and-mark (C-x C-x)' 24646 Swap the point with the mark. The current cursor position is set 24647 to the saved position, and the old cursor position is saved as the 24648 mark. 24649 24650 `character-search (C-])' 24651 A character is read and point is moved to the next occurrence of 24652 that character. A negative count searches for previous 24653 occurrences. 24654 24655 `character-search-backward (M-C-])' 24656 A character is read and point is moved to the previous occurrence 24657 of that character. A negative count searches for subsequent 24658 occurrences. 24659 24660 `insert-comment (M-#)' 24661 Without a numeric argument, the value of the `comment-begin' 24662 variable is inserted at the beginning of the current line. If a 24663 numeric argument is supplied, this command acts as a toggle: if 24664 the characters at the beginning of the line do not match the value 24665 of `comment-begin', the value is inserted, otherwise the 24666 characters in `comment-begin' are deleted from the beginning of 24667 the line. In either case, the line is accepted as if a newline 24668 had been typed. 24669 24670 `dump-functions ()' 24671 Print all of the functions and their key bindings to the Readline 24672 output stream. If a numeric argument is supplied, the output is 24673 formatted in such a way that it can be made part of an INPUTRC 24674 file. This command is unbound by default. 24675 24676 `dump-variables ()' 24677 Print all of the settable variables and their values to the 24678 Readline output stream. If a numeric argument is supplied, the 24679 output is formatted in such a way that it can be made part of an 24680 INPUTRC file. This command is unbound by default. 24681 24682 `dump-macros ()' 24683 Print all of the Readline key sequences bound to macros and the 24684 strings they output. If a numeric argument is supplied, the 24685 output is formatted in such a way that it can be made part of an 24686 INPUTRC file. This command is unbound by default. 24687 24688 `emacs-editing-mode (C-e)' 24689 When in `vi' command mode, this causes a switch to `emacs' editing 24690 mode. 24691 24692 `vi-editing-mode (M-C-j)' 24693 When in `emacs' editing mode, this causes a switch to `vi' editing 24694 mode. 24695 24696 24697 24698 File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing 24699 24700 31.5 Readline vi Mode 24701 ===================== 24702 24703 While the Readline library does not have a full set of `vi' editing 24704 functions, it does contain enough to allow simple editing of the line. 24705 The Readline `vi' mode behaves as specified in the POSIX 1003.2 24706 standard. 24707 24708 In order to switch interactively between `emacs' and `vi' editing 24709 modes, use the command `M-C-j' (bound to emacs-editing-mode when in 24710 `vi' mode and to vi-editing-mode in `emacs' mode). The Readline 24711 default is `emacs' mode. 24712 24713 When you enter a line in `vi' mode, you are already placed in 24714 `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches 24715 you into `command' mode, where you can edit the text of the line with 24716 the standard `vi' movement keys, move to previous history lines with 24717 `k' and subsequent lines with `j', and so forth. 24718 24719 24720 File: gdb.info, Node: Using History Interactively, Next: Formatting Documentation, Prev: Command Line Editing, Up: Top 24721 24722 32 Using History Interactively 24723 ****************************** 24724 24725 This chapter describes how to use the GNU History Library interactively, 24726 from a user's standpoint. It should be considered a user's guide. For 24727 information on using the GNU History Library in other programs, see the 24728 GNU Readline Library Manual. 24729 24730 * Menu: 24731 24732 * History Interaction:: What it feels like using History as a user. 24733 24734 24735 File: gdb.info, Node: History Interaction, Up: Using History Interactively 24736 24737 32.1 History Expansion 24738 ====================== 24739 24740 The History library provides a history expansion feature that is similar 24741 to the history expansion provided by `csh'. This section describes the 24742 syntax used to manipulate the history information. 24743 24744 History expansions introduce words from the history list into the 24745 input stream, making it easy to repeat commands, insert the arguments 24746 to a previous command into the current input line, or fix errors in 24747 previous commands quickly. 24748 24749 History expansion takes place in two parts. The first is to 24750 determine which line from the history list should be used during 24751 substitution. The second is to select portions of that line for 24752 inclusion into the current one. The line selected from the history is 24753 called the "event", and the portions of that line that are acted upon 24754 are called "words". Various "modifiers" are available to manipulate 24755 the selected words. The line is broken into words in the same fashion 24756 that Bash does, so that several words surrounded by quotes are 24757 considered one word. History expansions are introduced by the 24758 appearance of the history expansion character, which is `!' by default. 24759 24760 * Menu: 24761 24762 * Event Designators:: How to specify which history line to use. 24763 * Word Designators:: Specifying which words are of interest. 24764 * Modifiers:: Modifying the results of substitution. 24765 24766 24767 File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction 24768 24769 32.1.1 Event Designators 24770 ------------------------ 24771 24772 An event designator is a reference to a command line entry in the 24773 history list. 24774 24775 `!' 24776 Start a history substitution, except when followed by a space, tab, 24777 the end of the line, or `='. 24778 24779 `!N' 24780 Refer to command line N. 24781 24782 `!-N' 24783 Refer to the command N lines back. 24784 24785 `!!' 24786 Refer to the previous command. This is a synonym for `!-1'. 24787 24788 `!STRING' 24789 Refer to the most recent command starting with STRING. 24790 24791 `!?STRING[?]' 24792 Refer to the most recent command containing STRING. The trailing 24793 `?' may be omitted if the STRING is followed immediately by a 24794 newline. 24795 24796 `^STRING1^STRING2^' 24797 Quick Substitution. Repeat the last command, replacing STRING1 24798 with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. 24799 24800 `!#' 24801 The entire command line typed so far. 24802 24803 24804 24805 File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction 24806 24807 32.1.2 Word Designators 24808 ----------------------- 24809 24810 Word designators are used to select desired words from the event. A 24811 `:' separates the event specification from the word designator. It may 24812 be omitted if the word designator begins with a `^', `$', `*', `-', or 24813 `%'. Words are numbered from the beginning of the line, with the first 24814 word being denoted by 0 (zero). Words are inserted into the current 24815 line separated by single spaces. 24816 24817 For example, 24818 24819 `!!' 24820 designates the preceding command. When you type this, the 24821 preceding command is repeated in toto. 24822 24823 `!!:$' 24824 designates the last argument of the preceding command. This may be 24825 shortened to `!$'. 24826 24827 `!fi:2' 24828 designates the second argument of the most recent command starting 24829 with the letters `fi'. 24830 24831 Here are the word designators: 24832 24833 `0 (zero)' 24834 The `0'th word. For many applications, this is the command word. 24835 24836 `N' 24837 The Nth word. 24838 24839 `^' 24840 The first argument; that is, word 1. 24841 24842 `$' 24843 The last argument. 24844 24845 `%' 24846 The word matched by the most recent `?STRING?' search. 24847 24848 `X-Y' 24849 A range of words; `-Y' abbreviates `0-Y'. 24850 24851 `*' 24852 All of the words, except the `0'th. This is a synonym for `1-$'. 24853 It is not an error to use `*' if there is just one word in the 24854 event; the empty string is returned in that case. 24855 24856 `X*' 24857 Abbreviates `X-$' 24858 24859 `X-' 24860 Abbreviates `X-$' like `X*', but omits the last word. 24861 24862 24863 If a word designator is supplied without an event specification, the 24864 previous command is used as the event. 24865 24866 24867 File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction 24868 24869 32.1.3 Modifiers 24870 ---------------- 24871 24872 After the optional word designator, you can add a sequence of one or 24873 more of the following modifiers, each preceded by a `:'. 24874 24875 `h' 24876 Remove a trailing pathname component, leaving only the head. 24877 24878 `t' 24879 Remove all leading pathname components, leaving the tail. 24880 24881 `r' 24882 Remove a trailing suffix of the form `.SUFFIX', leaving the 24883 basename. 24884 24885 `e' 24886 Remove all but the trailing suffix. 24887 24888 `p' 24889 Print the new command but do not execute it. 24890 24891 `s/OLD/NEW/' 24892 Substitute NEW for the first occurrence of OLD in the event line. 24893 Any delimiter may be used in place of `/'. The delimiter may be 24894 quoted in OLD and NEW with a single backslash. If `&' appears in 24895 NEW, it is replaced by OLD. A single backslash will quote the 24896 `&'. The final delimiter is optional if it is the last character 24897 on the input line. 24898 24899 `&' 24900 Repeat the previous substitution. 24901 24902 `g' 24903 `a' 24904 Cause changes to be applied over the entire event line. Used in 24905 conjunction with `s', as in `gs/OLD/NEW/', or with `&'. 24906 24907 `G' 24908 Apply the following `s' modifier once to each word in the event. 24909 24910 24911 24912 File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: Using History Interactively, Up: Top 24913 24914 Appendix A Formatting Documentation 24915 *********************************** 24916 24917 The GDB 4 release includes an already-formatted reference card, ready 24918 for printing with PostScript or Ghostscript, in the `gdb' subdirectory 24919 of the main source directory(1). If you can use PostScript or 24920 Ghostscript with your printer, you can print the reference card 24921 immediately with `refcard.ps'. 24922 24923 The release also includes the source for the reference card. You 24924 can format it, using TeX, by typing: 24925 24926 make refcard.dvi 24927 24928 The GDB reference card is designed to print in "landscape" mode on 24929 US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches 24930 high. You will need to specify this form of printing as an option to 24931 your DVI output program. 24932 24933 All the documentation for GDB comes as part of the machine-readable 24934 distribution. The documentation is written in Texinfo format, which is 24935 a documentation system that uses a single source file to produce both 24936 on-line information and a printed manual. You can use one of the Info 24937 formatting commands to create the on-line version of the documentation 24938 and TeX (or `texi2roff') to typeset the printed version. 24939 24940 GDB includes an already formatted copy of the on-line Info version 24941 of this manual in the `gdb' subdirectory. The main Info file is 24942 `gdb-7.1-android-gg2/gdb/gdb.info', and it refers to subordinate files 24943 matching `gdb.info*' in the same directory. If necessary, you can 24944 print out these files, or read them with any editor; but they are 24945 easier to read using the `info' subsystem in GNU Emacs or the 24946 standalone `info' program, available as part of the GNU Texinfo 24947 distribution. 24948 24949 If you want to format these Info files yourself, you need one of the 24950 Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. 24951 24952 If you have `makeinfo' installed, and are in the top level GDB 24953 source directory (`gdb-7.1-android-gg2', in the case of version 24954 7.1-android-gg2), you can make the Info file by typing: 24955 24956 cd gdb 24957 make gdb.info 24958 24959 If you want to typeset and print copies of this manual, you need TeX, 24960 a program to print its DVI output files, and `texinfo.tex', the Texinfo 24961 definitions file. 24962 24963 TeX is a typesetting program; it does not print files directly, but 24964 produces output files called DVI files. To print a typeset document, 24965 you need a program to print DVI files. If your system has TeX 24966 installed, chances are it has such a program. The precise command to 24967 use depends on your system; `lpr -d' is common; another (for PostScript 24968 devices) is `dvips'. The DVI print command may require a file name 24969 without any extension or a `.dvi' extension. 24970 24971 TeX also requires a macro definitions file called `texinfo.tex'. 24972 This file tells TeX how to typeset a document written in Texinfo 24973 format. On its own, TeX cannot either read or typeset a Texinfo file. 24974 `texinfo.tex' is distributed with GDB and is located in the 24975 `gdb-VERSION-NUMBER/texinfo' directory. 24976 24977 If you have TeX and a DVI printer program installed, you can typeset 24978 and print this manual. First switch to the `gdb' subdirectory of the 24979 main source directory (for example, to `gdb-7.1-android-gg2/gdb') and 24980 type: 24981 24982 make gdb.dvi 24983 24984 Then give `gdb.dvi' to your DVI printing program. 24985 24986 ---------- Footnotes ---------- 24987 24988 (1) In `gdb-7.1-android-gg2/gdb/refcard.ps' of the version 24989 7.1-android-gg2 release. 24990 24991 24992 File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top 24993 24994 Appendix B Installing GDB 24995 ************************* 24996 24997 * Menu: 24998 24999 * Requirements:: Requirements for building GDB 25000 * Running Configure:: Invoking the GDB `configure' script 25001 * Separate Objdir:: Compiling GDB in another directory 25002 * Config Names:: Specifying names for hosts and targets 25003 * Configure Options:: Summary of options for configure 25004 * System-wide configuration:: Having a system-wide init file 25005 25006 25007 File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB 25008 25009 B.1 Requirements for Building GDB 25010 ================================= 25011 25012 Building GDB requires various tools and packages to be available. 25013 Other packages will be used only if they are found. 25014 25015 Tools/Packages Necessary for Building GDB 25016 ========================================= 25017 25018 ISO C90 compiler 25019 GDB is written in ISO C90. It should be buildable with any 25020 working C90 compiler, e.g. GCC. 25021 25022 25023 Tools/Packages Optional for Building GDB 25024 ======================================== 25025 25026 Expat 25027 GDB can use the Expat XML parsing library. This library may be 25028 included with your operating system distribution; if it is not, you 25029 can get the latest version from `http://expat.sourceforge.net'. 25030 The `configure' script will search for this library in several 25031 standard locations; if it is installed in an unusual path, you can 25032 use the `--with-libexpat-prefix' option to specify its location. 25033 25034 Expat is used for: 25035 25036 * Remote protocol memory maps (*note Memory Map Format::) 25037 25038 * Target descriptions (*note Target Descriptions::) 25039 25040 * Remote shared library lists (*note Library List Format::) 25041 25042 * MS-Windows shared libraries (*note Shared Libraries::) 25043 25044 zlib 25045 GDB will use the `zlib' library, if available, to read compressed 25046 debug sections. Some linkers, such as GNU gold, are capable of 25047 producing binaries with compressed debug sections. If GDB is 25048 compiled with `zlib', it will be able to read the debug 25049 information in such binaries. 25050 25051 The `zlib' library is likely included with your operating system 25052 distribution; if it is not, you can get the latest version from 25053 `http://zlib.net'. 25054 25055 iconv 25056 GDB's features related to character sets (*note Character Sets::) 25057 require a functioning `iconv' implementation. If you are on a GNU 25058 system, then this is provided by the GNU C Library. Some other 25059 systems also provide a working `iconv'. 25060 25061 On systems with `iconv', you can install GNU Libiconv. If you 25062 have previously installed Libiconv, you can use the 25063 `--with-libiconv-prefix' option to configure. 25064 25065 GDB's top-level `configure' and `Makefile' will arrange to build 25066 Libiconv if a directory named `libiconv' appears in the top-most 25067 source directory. If Libiconv is built this way, and if the 25068 operating system does not provide a suitable `iconv' 25069 implementation, then the just-built library will automatically be 25070 used by GDB. One easy way to set this up is to download GNU 25071 Libiconv, unpack it, and then rename the directory holding the 25072 Libiconv source code to `libiconv'. 25073 25074 25075 File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB 25076 25077 B.2 Invoking the GDB `configure' Script 25078 ======================================= 25079 25080 GDB comes with a `configure' script that automates the process of 25081 preparing GDB for installation; you can then use `make' to build the 25082 `gdb' program. 25083 25084 The GDB distribution includes all the source code you need for GDB 25085 in a single directory, whose name is usually composed by appending the 25086 version number to `gdb'. 25087 25088 For example, the GDB version 7.1-android-gg2 distribution is in the 25089 `gdb-7.1-android-gg2' directory. That directory contains: 25090 25091 `gdb-7.1-android-gg2/configure (and supporting files)' 25092 script for configuring GDB and all its supporting libraries 25093 25094 `gdb-7.1-android-gg2/gdb' 25095 the source specific to GDB itself 25096 25097 `gdb-7.1-android-gg2/bfd' 25098 source for the Binary File Descriptor library 25099 25100 `gdb-7.1-android-gg2/include' 25101 GNU include files 25102 25103 `gdb-7.1-android-gg2/libiberty' 25104 source for the `-liberty' free software library 25105 25106 `gdb-7.1-android-gg2/opcodes' 25107 source for the library of opcode tables and disassemblers 25108 25109 `gdb-7.1-android-gg2/readline' 25110 source for the GNU command-line interface 25111 25112 `gdb-7.1-android-gg2/glob' 25113 source for the GNU filename pattern-matching subroutine 25114 25115 `gdb-7.1-android-gg2/mmalloc' 25116 source for the GNU memory-mapped malloc package 25117 25118 The simplest way to configure and build GDB is to run `configure' 25119 from the `gdb-VERSION-NUMBER' source directory, which in this example 25120 is the `gdb-7.1-android-gg2' directory. 25121 25122 First switch to the `gdb-VERSION-NUMBER' source directory if you are 25123 not already in it; then run `configure'. Pass the identifier for the 25124 platform on which GDB will run as an argument. 25125 25126 For example: 25127 25128 cd gdb-7.1-android-gg2 25129 ./configure HOST 25130 make 25131 25132 where HOST is an identifier such as `sun4' or `decstation', that 25133 identifies the platform where GDB will run. (You can often leave off 25134 HOST; `configure' tries to guess the correct value by examining your 25135 system.) 25136 25137 Running `configure HOST' and then running `make' builds the `bfd', 25138 `readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. 25139 The configured source files, and the binaries, are left in the 25140 corresponding source directories. 25141 25142 `configure' is a Bourne-shell (`/bin/sh') script; if your system 25143 does not recognize this automatically when you run a different shell, 25144 you may need to run `sh' on it explicitly: 25145 25146 sh configure HOST 25147 25148 If you run `configure' from a directory that contains source 25149 directories for multiple libraries or programs, such as the 25150 `gdb-7.1-android-gg2' source directory for version 7.1-android-gg2, 25151 `configure' creates configuration files for every directory level 25152 underneath (unless you tell it not to, with the `--norecursion' option). 25153 25154 You should run the `configure' script from the top directory in the 25155 source tree, the `gdb-VERSION-NUMBER' directory. If you run 25156 `configure' from one of the subdirectories, you will configure only 25157 that subdirectory. That is usually not what you want. In particular, 25158 if you run the first `configure' from the `gdb' subdirectory of the 25159 `gdb-VERSION-NUMBER' directory, you will omit the configuration of 25160 `bfd', `readline', and other sibling directories of the `gdb' 25161 subdirectory. This leads to build errors about missing include files 25162 such as `bfd/bfd.h'. 25163 25164 You can install `gdb' anywhere; it has no hardwired paths. However, 25165 you should make sure that the shell on your path (named by the `SHELL' 25166 environment variable) is publicly readable. Remember that GDB uses the 25167 shell to start your program--some systems refuse to let GDB debug child 25168 processes whose programs are not readable. 25169 25170 25171 File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB 25172 25173 B.3 Compiling GDB in Another Directory 25174 ====================================== 25175 25176 If you want to run GDB versions for several host or target machines, 25177 you need a different `gdb' compiled for each combination of host and 25178 target. `configure' is designed to make this easy by allowing you to 25179 generate each configuration in a separate subdirectory, rather than in 25180 the source directory. If your `make' program handles the `VPATH' 25181 feature (GNU `make' does), running `make' in each of these directories 25182 builds the `gdb' program specified there. 25183 25184 To build `gdb' in a separate directory, run `configure' with the 25185 `--srcdir' option to specify where to find the source. (You also need 25186 to specify a path to find `configure' itself from your working 25187 directory. If the path to `configure' would be the same as the 25188 argument to `--srcdir', you can leave out the `--srcdir' option; it is 25189 assumed.) 25190 25191 For example, with version 7.1-android-gg2, you can build GDB in a 25192 separate directory for a Sun 4 like this: 25193 25194 cd gdb-7.1-android-gg2 25195 mkdir ../gdb-sun4 25196 cd ../gdb-sun4 25197 ../gdb-7.1-android-gg2/configure sun4 25198 make 25199 25200 When `configure' builds a configuration using a remote source 25201 directory, it creates a tree for the binaries with the same structure 25202 (and using the same names) as the tree under the source directory. In 25203 the example, you'd find the Sun 4 library `libiberty.a' in the 25204 directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. 25205 25206 Make sure that your path to the `configure' script has just one 25207 instance of `gdb' in it. If your path to `configure' looks like 25208 `../gdb-7.1-android-gg2/gdb/configure', you are configuring only one 25209 subdirectory of GDB, not the whole package. This leads to build errors 25210 about missing include files such as `bfd/bfd.h'. 25211 25212 One popular reason to build several GDB configurations in separate 25213 directories is to configure GDB for cross-compiling (where GDB runs on 25214 one machine--the "host"--while debugging programs that run on another 25215 machine--the "target"). You specify a cross-debugging target by giving 25216 the `--target=TARGET' option to `configure'. 25217 25218 When you run `make' to build a program or library, you must run it 25219 in a configured directory--whatever directory you were in when you 25220 called `configure' (or one of its subdirectories). 25221 25222 The `Makefile' that `configure' generates in each source directory 25223 also runs recursively. If you type `make' in a source directory such 25224 as `gdb-7.1-android-gg2' (or in a separate configured directory 25225 configured with `--srcdir=DIRNAME/gdb-7.1-android-gg2'), you will build 25226 all the required libraries, and then build GDB. 25227 25228 When you have multiple hosts or targets configured in separate 25229 directories, you can run `make' on them in parallel (for example, if 25230 they are NFS-mounted on each of the hosts); they will not interfere 25231 with each other. 25232 25233 25234 File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB 25235 25236 B.4 Specifying Names for Hosts and Targets 25237 ========================================== 25238 25239 The specifications used for hosts and targets in the `configure' script 25240 are based on a three-part naming scheme, but some short predefined 25241 aliases are also supported. The full naming scheme encodes three pieces 25242 of information in the following pattern: 25243 25244 ARCHITECTURE-VENDOR-OS 25245 25246 For example, you can use the alias `sun4' as a HOST argument, or as 25247 the value for TARGET in a `--target=TARGET' option. The equivalent 25248 full name is `sparc-sun-sunos4'. 25249 25250 The `configure' script accompanying GDB does not provide any query 25251 facility to list all supported host and target names or aliases. 25252 `configure' calls the Bourne shell script `config.sub' to map 25253 abbreviations to full names; you can read the script, if you wish, or 25254 you can use it to test your guesses on abbreviations--for example: 25255 25256 % sh config.sub i386-linux 25257 i386-pc-linux-gnu 25258 % sh config.sub alpha-linux 25259 alpha-unknown-linux-gnu 25260 % sh config.sub hp9k700 25261 hppa1.1-hp-hpux 25262 % sh config.sub sun4 25263 sparc-sun-sunos4.1.1 25264 % sh config.sub sun3 25265 m68k-sun-sunos4.1.1 25266 % sh config.sub i986v 25267 Invalid configuration `i986v': machine `i986v' not recognized 25268 25269 `config.sub' is also distributed in the GDB source directory 25270 (`gdb-7.1-android-gg2', for version 7.1-android-gg2). 25271 25272 25273 File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB 25274 25275 B.5 `configure' Options 25276 ======================= 25277 25278 Here is a summary of the `configure' options and arguments that are 25279 most often useful for building GDB. `configure' also has several other 25280 options not listed here. *note (configure.info)What Configure Does::, 25281 for a full explanation of `configure'. 25282 25283 configure [--help] 25284 [--prefix=DIR] 25285 [--exec-prefix=DIR] 25286 [--srcdir=DIRNAME] 25287 [--norecursion] [--rm] 25288 [--target=TARGET] 25289 HOST 25290 25291 You may introduce options with a single `-' rather than `--' if you 25292 prefer; but you may abbreviate option names if you use `--'. 25293 25294 `--help' 25295 Display a quick summary of how to invoke `configure'. 25296 25297 `--prefix=DIR' 25298 Configure the source to install programs and files under directory 25299 `DIR'. 25300 25301 `--exec-prefix=DIR' 25302 Configure the source to install programs under directory `DIR'. 25303 25304 `--srcdir=DIRNAME' 25305 *Warning: using this option requires GNU `make', or another `make' 25306 that implements the `VPATH' feature.* 25307 Use this option to make configurations in directories separate 25308 from the GDB source directories. Among other things, you can use 25309 this to build (or maintain) several configurations simultaneously, 25310 in separate directories. `configure' writes 25311 configuration-specific files in the current directory, but 25312 arranges for them to use the source in the directory DIRNAME. 25313 `configure' creates directories under the working directory in 25314 parallel to the source directories below DIRNAME. 25315 25316 `--norecursion' 25317 Configure only the directory level where `configure' is executed; 25318 do not propagate configuration to subdirectories. 25319 25320 `--target=TARGET' 25321 Configure GDB for cross-debugging programs running on the specified 25322 TARGET. Without this option, GDB is configured to debug programs 25323 that run on the same machine (HOST) as GDB itself. 25324 25325 There is no convenient way to generate a list of all available 25326 targets. 25327 25328 `HOST ...' 25329 Configure GDB to run on the specified HOST. 25330 25331 There is no convenient way to generate a list of all available 25332 hosts. 25333 25334 There are many other options available as well, but they are 25335 generally needed for special purposes only. 25336 25337 25338 File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB 25339 25340 B.6 System-wide configuration and settings 25341 ========================================== 25342 25343 GDB can be configured to have a system-wide init file; this file will 25344 be read and executed at startup (*note What GDB does during startup: 25345 Startup.). 25346 25347 Here is the corresponding configure option: 25348 25349 `--with-system-gdbinit=FILE' 25350 Specify that the default location of the system-wide init file is 25351 FILE. 25352 25353 If GDB has been configured with the option `--prefix=$prefix', it 25354 may be subject to relocation. Two possible cases: 25355 25356 * If the default location of this init file contains `$prefix', it 25357 will be subject to relocation. Suppose that the configure options 25358 are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit'; 25359 if GDB is moved from `$prefix' to `$install', the system init file 25360 is looked for as `$install/etc/gdbinit' instead of 25361 `$prefix/etc/gdbinit'. 25362 25363 * By contrast, if the default location does not contain the prefix, 25364 it will not be relocated. E.g. if GDB has been configured with 25365 `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit', 25366 then GDB will always look for `/usr/share/gdb/gdbinit', wherever 25367 GDB is installed. 25368 25369 25370 File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top 25371 25372 Appendix C Maintenance Commands 25373 ******************************* 25374 25375 In addition to commands intended for GDB users, GDB includes a number 25376 of commands intended for GDB developers, that are not documented 25377 elsewhere in this manual. These commands are provided here for 25378 reference. (For commands that turn on debugging messages, see *Note 25379 Debugging Output::.) 25380 25381 `maint agent EXPRESSION' 25382 `maint agent-eval EXPRESSION' 25383 Translate the given EXPRESSION into remote agent bytecodes. This 25384 command is useful for debugging the Agent Expression mechanism 25385 (*note Agent Expressions::). The `agent' version produces an 25386 expression useful for data collection, such as by tracepoints, 25387 while `maint agent-eval' produces an expression that evaluates 25388 directly to a result. For instance, a collection expression for 25389 `globa + globb' will include bytecodes to record four bytes of 25390 memory at each of the addresses of `globa' and `globb', while 25391 discarding the result of the addition, while an evaluation 25392 expression will do the addition and return the sum. 25393 25394 `maint info breakpoints' 25395 Using the same format as `info breakpoints', display both the 25396 breakpoints you've set explicitly, and those GDB is using for 25397 internal purposes. Internal breakpoints are shown with negative 25398 breakpoint numbers. The type column identifies what kind of 25399 breakpoint is shown: 25400 25401 `breakpoint' 25402 Normal, explicitly set breakpoint. 25403 25404 `watchpoint' 25405 Normal, explicitly set watchpoint. 25406 25407 `longjmp' 25408 Internal breakpoint, used to handle correctly stepping through 25409 `longjmp' calls. 25410 25411 `longjmp resume' 25412 Internal breakpoint at the target of a `longjmp'. 25413 25414 `until' 25415 Temporary internal breakpoint used by the GDB `until' command. 25416 25417 `finish' 25418 Temporary internal breakpoint used by the GDB `finish' 25419 command. 25420 25421 `shlib events' 25422 Shared library events. 25423 25424 25425 `set displaced-stepping' 25426 `show displaced-stepping' 25427 Control whether or not GDB will do "displaced stepping" if the 25428 target supports it. Displaced stepping is a way to single-step 25429 over breakpoints without removing them from the inferior, by 25430 executing an out-of-line copy of the instruction that was 25431 originally at the breakpoint location. It is also known as 25432 out-of-line single-stepping. 25433 25434 `set displaced-stepping on' 25435 If the target architecture supports it, GDB will use 25436 displaced stepping to step over breakpoints. 25437 25438 `set displaced-stepping off' 25439 GDB will not use displaced stepping to step over breakpoints, 25440 even if such is supported by the target architecture. 25441 25442 `set displaced-stepping auto' 25443 This is the default mode. GDB will use displaced stepping 25444 only if non-stop mode is active (*note Non-Stop Mode::) and 25445 the target architecture supports displaced stepping. 25446 25447 `maint check-symtabs' 25448 Check the consistency of psymtabs and symtabs. 25449 25450 `maint cplus first_component NAME' 25451 Print the first C++ class/namespace component of NAME. 25452 25453 `maint cplus namespace' 25454 Print the list of possible C++ namespaces. 25455 25456 `maint demangle NAME' 25457 Demangle a C++ or Objective-C mangled NAME. 25458 25459 `maint deprecate COMMAND [REPLACEMENT]' 25460 `maint undeprecate COMMAND' 25461 Deprecate or undeprecate the named COMMAND. Deprecated commands 25462 cause GDB to issue a warning when you use them. The optional 25463 argument REPLACEMENT says which newer command should be used in 25464 favor of the deprecated one; if it is given, GDB will mention the 25465 replacement as part of the warning. 25466 25467 `maint dump-me' 25468 Cause a fatal signal in the debugger and force it to dump its core. 25469 This is supported only on systems which support aborting a program 25470 with the `SIGQUIT' signal. 25471 25472 `maint internal-error [MESSAGE-TEXT]' 25473 `maint internal-warning [MESSAGE-TEXT]' 25474 Cause GDB to call the internal function `internal_error' or 25475 `internal_warning' and hence behave as though an internal error or 25476 internal warning has been detected. In addition to reporting the 25477 internal problem, these functions give the user the opportunity to 25478 either quit GDB or create a core file of the current GDB session. 25479 25480 These commands take an optional parameter MESSAGE-TEXT that is 25481 used as the text of the error or warning message. 25482 25483 Here's an example of using `internal-error': 25484 25485 (gdb) maint internal-error testing, 1, 2 25486 .../maint.c:121: internal-error: testing, 1, 2 25487 A problem internal to GDB has been detected. Further 25488 debugging may prove unreliable. 25489 Quit this debugging session? (y or n) n 25490 Create a core file? (y or n) n 25491 (gdb) 25492 25493 `maint set internal-error ACTION [ask|yes|no]' 25494 `maint show internal-error ACTION' 25495 `maint set internal-warning ACTION [ask|yes|no]' 25496 `maint show internal-warning ACTION' 25497 When GDB reports an internal problem (error or warning) it gives 25498 the user the opportunity to both quit GDB and create a core file 25499 of the current GDB session. These commands let you override the 25500 default behaviour for each particular ACTION, described in the 25501 table below. 25502 25503 `quit' 25504 You can specify that GDB should always (yes) or never (no) 25505 quit. The default is to ask the user what to do. 25506 25507 `corefile' 25508 You can specify that GDB should always (yes) or never (no) 25509 create a core file. The default is to ask the user what to 25510 do. 25511 25512 `maint packet TEXT' 25513 If GDB is talking to an inferior via the serial protocol, then 25514 this command sends the string TEXT to the inferior, and displays 25515 the response packet. GDB supplies the initial `$' character, the 25516 terminating `#' character, and the checksum. 25517 25518 `maint print architecture [FILE]' 25519 Print the entire architecture configuration. The optional argument 25520 FILE names the file where the output goes. 25521 25522 `maint print c-tdesc' 25523 Print the current target description (*note Target Descriptions::) 25524 as a C source file. The created source file can be used in GDB 25525 when an XML parser is not available to parse the description. 25526 25527 `maint print dummy-frames' 25528 Prints the contents of GDB's internal dummy-frame stack. 25529 25530 (gdb) b add 25531 ... 25532 (gdb) print add(2,3) 25533 Breakpoint 2, add (a=2, b=3) at ... 25534 58 return (a + b); 25535 The program being debugged stopped while in a function called from GDB. 25536 ... 25537 (gdb) maint print dummy-frames 25538 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 25539 top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c} 25540 call_lo=0x01014000 call_hi=0x01014001 25541 (gdb) 25542 25543 Takes an optional file parameter. 25544 25545 `maint print registers [FILE]' 25546 `maint print raw-registers [FILE]' 25547 `maint print cooked-registers [FILE]' 25548 `maint print register-groups [FILE]' 25549 Print GDB's internal register data structures. 25550 25551 The command `maint print raw-registers' includes the contents of 25552 the raw register cache; the command `maint print cooked-registers' 25553 includes the (cooked) value of all registers; and the command 25554 `maint print register-groups' includes the groups that each 25555 register is a member of. *Note Registers: (gdbint)Registers. 25556 25557 These commands take an optional parameter, a file name to which to 25558 write the information. 25559 25560 `maint print reggroups [FILE]' 25561 Print GDB's internal register group data structures. The optional 25562 argument FILE tells to what file to write the information. 25563 25564 The register groups info looks like this: 25565 25566 (gdb) maint print reggroups 25567 Group Type 25568 general user 25569 float user 25570 all user 25571 vector user 25572 system user 25573 save internal 25574 restore internal 25575 25576 `flushregs' 25577 This command forces GDB to flush its internal register cache. 25578 25579 `maint print objfiles' 25580 Print a dump of all known object files. For each object file, this 25581 command prints its name, address in memory, and all of its psymtabs 25582 and symtabs. 25583 25584 `maint print statistics' 25585 This command prints, for each object file in the program, various 25586 data about that object file followed by the byte cache ("bcache") 25587 statistics for the object file. The objfile data includes the 25588 number of minimal, partial, full, and stabs symbols, the number of 25589 types defined by the objfile, the number of as yet unexpanded psym 25590 tables, the number of line tables and string tables, and the 25591 amount of memory used by the various tables. The bcache 25592 statistics include the counts, sizes, and counts of duplicates of 25593 all and unique objects, max, average, and median entry size, total 25594 memory used and its overhead and savings, and various measures of 25595 the hash table size and chain lengths. 25596 25597 `maint print target-stack' 25598 A "target" is an interface between the debugger and a particular 25599 kind of file or process. Targets can be stacked in "strata", so 25600 that more than one target can potentially respond to a request. 25601 In particular, memory accesses will walk down the stack of targets 25602 until they find a target that is interested in handling that 25603 particular address. 25604 25605 This command prints a short description of each layer that was 25606 pushed on the "target stack", starting from the top layer down to 25607 the bottom one. 25608 25609 `maint print type EXPR' 25610 Print the type chain for a type specified by EXPR. The argument 25611 can be either a type name or a symbol. If it is a symbol, the 25612 type of that symbol is described. The type chain produced by this 25613 command is a recursive definition of the data type as stored in 25614 GDB's data structures, including its flags and contained types. 25615 25616 `maint set dwarf2 max-cache-age' 25617 `maint show dwarf2 max-cache-age' 25618 Control the DWARF 2 compilation unit cache. 25619 25620 In object files with inter-compilation-unit references, such as 25621 those produced by the GCC option `-feliminate-dwarf2-dups', the 25622 DWARF 2 reader needs to frequently refer to previously read 25623 compilation units. This setting controls how long a compilation 25624 unit will remain in the cache if it is not referenced. A higher 25625 limit means that cached compilation units will be stored in memory 25626 longer, and more total memory will be used. Setting it to zero 25627 disables caching, which will slow down GDB startup, but reduce 25628 memory consumption. 25629 25630 `maint set profile' 25631 `maint show profile' 25632 Control profiling of GDB. 25633 25634 Profiling will be disabled until you use the `maint set profile' 25635 command to enable it. When you enable profiling, the system will 25636 begin collecting timing and execution count data; when you disable 25637 profiling or exit GDB, the results will be written to a log file. 25638 Remember that if you use profiling, GDB will overwrite the 25639 profiling log file (often called `gmon.out'). If you have a 25640 record of important profiling data in a `gmon.out' file, be sure 25641 to move it to a safe location. 25642 25643 Configuring with `--enable-profiling' arranges for GDB to be 25644 compiled with the `-pg' compiler option. 25645 25646 `maint set show-debug-regs' 25647 `maint show show-debug-regs' 25648 Control whether to show variables that mirror the hardware debug 25649 registers. Use `ON' to enable, `OFF' to disable. If enabled, the 25650 debug registers values are shown when GDB inserts or removes a 25651 hardware breakpoint or watchpoint, and when the inferior triggers 25652 a hardware-assisted breakpoint or watchpoint. 25653 25654 `maint space' 25655 Control whether to display memory usage for each command. If set 25656 to a nonzero value, GDB will display how much memory each command 25657 took, following the command's own output. This can also be 25658 requested by invoking GDB with the `--statistics' command-line 25659 switch (*note Mode Options::). 25660 25661 `maint time' 25662 Control whether to display the execution time for each command. If 25663 set to a nonzero value, GDB will display how much time it took to 25664 execute each command, following the command's own output. The 25665 time is not printed for the commands that run the target, since 25666 there's no mechanism currently to compute how much time was spend 25667 by GDB and how much time was spend by the program been debugged. 25668 it's not possibly currently This can also be requested by invoking 25669 GDB with the `--statistics' command-line switch (*note Mode 25670 Options::). 25671 25672 `maint translate-address [SECTION] ADDR' 25673 Find the symbol stored at the location specified by the address 25674 ADDR and an optional section name SECTION. If found, GDB prints 25675 the name of the closest symbol and an offset from the symbol's 25676 location to the specified address. This is similar to the `info 25677 address' command (*note Symbols::), except that this command also 25678 allows to find symbols in other sections. 25679 25680 If section was not specified, the section in which the symbol was 25681 found is also printed. For dynamically linked executables, the 25682 name of executable or shared library containing the symbol is 25683 printed as well. 25684 25685 25686 The following command is useful for non-interactive invocations of 25687 GDB, such as in the test suite. 25688 25689 `set watchdog NSEC' 25690 Set the maximum number of seconds GDB will wait for the target 25691 operation to finish. If this time expires, GDB reports and error 25692 and the command is aborted. 25693 25694 `show watchdog' 25695 Show the current setting of the target wait timeout. 25696 25697 25698 File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top 25699 25700 Appendix D GDB Remote Serial Protocol 25701 ************************************* 25702 25703 * Menu: 25704 25705 * Overview:: 25706 * Packets:: 25707 * Stop Reply Packets:: 25708 * General Query Packets:: 25709 * Architecture-Specific Protocol Details:: 25710 * Tracepoint Packets:: 25711 * Host I/O Packets:: 25712 * Interrupts:: 25713 * Notification Packets:: 25714 * Remote Non-Stop:: 25715 * Packet Acknowledgment:: 25716 * Examples:: 25717 * File-I/O Remote Protocol Extension:: 25718 * Library List Format:: 25719 * Memory Map Format:: 25720 * Thread List Format:: 25721 25722 25723 File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol 25724 25725 D.1 Overview 25726 ============ 25727 25728 There may be occasions when you need to know something about the 25729 protocol--for example, if there is only one serial port to your target 25730 machine, you might want your program to do something special if it 25731 recognizes a packet meant for GDB. 25732 25733 In the examples below, `->' and `<-' are used to indicate 25734 transmitted and received data, respectively. 25735 25736 All GDB commands and responses (other than acknowledgments and 25737 notifications, see *Note Notification Packets::) are sent as a PACKET. 25738 A PACKET is introduced with the character `$', the actual PACKET-DATA, 25739 and the terminating character `#' followed by a two-digit CHECKSUM: 25740 25741 `$'PACKET-DATA`#'CHECKSUM 25742 The two-digit CHECKSUM is computed as the modulo 256 sum of all 25743 characters between the leading `$' and the trailing `#' (an eight bit 25744 unsigned checksum). 25745 25746 Implementors should note that prior to GDB 5.0 the protocol 25747 specification also included an optional two-digit SEQUENCE-ID: 25748 25749 `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM 25750 25751 That SEQUENCE-ID was appended to the acknowledgment. GDB has never 25752 output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 25753 must not accept SEQUENCE-ID. 25754 25755 When either the host or the target machine receives a packet, the 25756 first response expected is an acknowledgment: either `+' (to indicate 25757 the package was received correctly) or `-' (to request retransmission): 25758 25759 -> `$'PACKET-DATA`#'CHECKSUM 25760 <- `+' 25761 The `+'/`-' acknowledgments can be disabled once a connection is 25762 established. *Note Packet Acknowledgment::, for details. 25763 25764 The host (GDB) sends COMMANDs, and the target (the debugging stub 25765 incorporated in your program) sends a RESPONSE. In the case of step 25766 and continue COMMANDs, the response is only sent when the operation has 25767 completed, and the target has again stopped all threads in all attached 25768 processes. This is the default all-stop mode behavior, but the remote 25769 protocol also supports GDB's non-stop execution mode; see *Note Remote 25770 Non-Stop::, for details. 25771 25772 PACKET-DATA consists of a sequence of characters with the exception 25773 of `#' and `$' (see `X' packet for additional exceptions). 25774 25775 Fields within the packet should be separated using `,' `;' or `:'. 25776 Except where otherwise noted all numbers are represented in HEX with 25777 leading zeros suppressed. 25778 25779 Implementors should note that prior to GDB 5.0, the character `:' 25780 could not appear as the third character in a packet (as it would 25781 potentially conflict with the SEQUENCE-ID). 25782 25783 Binary data in most packets is encoded either as two hexadecimal 25784 digits per byte of binary data. This allowed the traditional remote 25785 protocol to work over connections which were only seven-bit clean. 25786 Some packets designed more recently assume an eight-bit clean 25787 connection, and use a more efficient encoding to send and receive 25788 binary data. 25789 25790 The binary data representation uses `7d' (ASCII `}') as an escape 25791 character. Any escaped byte is transmitted as the escape character 25792 followed by the original character XORed with `0x20'. For example, the 25793 byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The 25794 bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}') 25795 must always be escaped. Responses sent by the stub must also escape 25796 `0x2a' (ASCII `*'), so that it is not interpreted as the start of a 25797 run-length encoded sequence (described next). 25798 25799 Response DATA can be run-length encoded to save space. Run-length 25800 encoding replaces runs of identical characters with one instance of the 25801 repeated character, followed by a `*' and a repeat count. The repeat 25802 count is itself sent encoded, to avoid binary characters in DATA: a 25803 value of N is sent as `N+29'. For a repeat count greater or equal to 25804 3, this produces a printable ASCII character, e.g. a space (ASCII code 25805 32) for a repeat count of 3. (This is because run-length encoding 25806 starts to win for counts 3 or more.) Thus, for example, `0* ' is a 25807 run-length encoding of "0000": the space character after `*' means 25808 repeat the leading `0' `32 - 29 = 3' more times. 25809 25810 The printable characters `#' and `$' or with a numeric value greater 25811 than 126 must not be used. Runs of six repeats (`#') or seven repeats 25812 (`$') can be expanded using a repeat count of only five (`"'). For 25813 example, `00000000' can be encoded as `0*"00'. 25814 25815 The error response returned for some packets includes a two character 25816 error number. That number is not well defined. 25817 25818 For any COMMAND not supported by the stub, an empty response 25819 (`$#00') should be returned. That way it is possible to extend the 25820 protocol. A newer GDB can tell if a packet is supported based on that 25821 response. 25822 25823 A stub is required to support the `g', `G', `m', `M', `c', and `s' 25824 COMMANDs. All other COMMANDs are optional. 25825 25826 25827 File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol 25828 25829 D.2 Packets 25830 =========== 25831 25832 The following table provides a complete list of all currently defined 25833 COMMANDs and their corresponding response DATA. *Note File-I/O Remote 25834 Protocol Extension::, for details about the File I/O extension of the 25835 remote protocol. 25836 25837 Each packet's description has a template showing the packet's overall 25838 syntax, followed by an explanation of the packet's meaning. We include 25839 spaces in some of the templates for clarity; these are not part of the 25840 packet's syntax. No GDB packet uses spaces to separate its components. 25841 For example, a template like `foo BAR BAZ' describes a packet 25842 beginning with the three ASCII bytes `foo', followed by a BAR, followed 25843 directly by a BAZ. GDB does not transmit a space character between the 25844 `foo' and the BAR, or between the BAR and the BAZ. 25845 25846 Several packets and replies include a THREAD-ID field to identify a 25847 thread. Normally these are positive numbers with a target-specific 25848 interpretation, formatted as big-endian hex strings. A THREAD-ID can 25849 also be a literal `-1' to indicate all threads, or `0' to pick any 25850 thread. 25851 25852 In addition, the remote protocol supports a multiprocess feature in 25853 which the THREAD-ID syntax is extended to optionally include both 25854 process and thread ID fields, as `pPID.TID'. The PID (process) and TID 25855 (thread) components each have the format described above: a positive 25856 number with target-specific interpretation formatted as a big-endian 25857 hex string, literal `-1' to indicate all processes or threads 25858 (respectively), or `0' to indicate an arbitrary process or thread. 25859 Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It 25860 is an error to specify all processes but a specific thread, such as 25861 `p-1.TID'. Note that the `p' prefix is _not_ used for those packets 25862 and replies explicitly documented to include a process ID, rather than 25863 a THREAD-ID. 25864 25865 The multiprocess THREAD-ID syntax extensions are only used if both 25866 GDB and the stub report support for the `multiprocess' feature using 25867 `qSupported'. *Note multiprocess extensions::, for more information. 25868 25869 Note that all packet forms beginning with an upper- or lower-case 25870 letter, other than those described here, are reserved for future use. 25871 25872 Here are the packet descriptions. 25873 25874 `!' 25875 Enable extended mode. In extended mode, the remote server is made 25876 persistent. The `R' packet is used to restart the program being 25877 debugged. 25878 25879 Reply: 25880 `OK' 25881 The remote target both supports and has enabled extended mode. 25882 25883 `?' 25884 Indicate the reason the target halted. The reply is the same as 25885 for step and continue. This packet has a special interpretation 25886 when the target is in non-stop mode; see *Note Remote Non-Stop::. 25887 25888 Reply: *Note Stop Reply Packets::, for the reply specifications. 25889 25890 `A ARGLEN,ARGNUM,ARG,...' 25891 Initialized `argv[]' array passed into program. ARGLEN specifies 25892 the number of bytes in the hex encoded byte stream ARG. See 25893 `gdbserver' for more details. 25894 25895 Reply: 25896 `OK' 25897 The arguments were set. 25898 25899 `E NN' 25900 An error occurred. 25901 25902 `b BAUD' 25903 (Don't use this packet; its behavior is not well-defined.) Change 25904 the serial line speed to BAUD. 25905 25906 JTC: _When does the transport layer state change? When it's 25907 received, or after the ACK is transmitted. In either case, there 25908 are problems if the command or the acknowledgment packet is 25909 dropped._ 25910 25911 Stan: _If people really wanted to add something like this, and get 25912 it working for the first time, they ought to modify ser-unix.c to 25913 send some kind of out-of-band message to a specially-setup stub 25914 and have the switch happen "in between" packets, so that from 25915 remote protocol's point of view, nothing actually happened._ 25916 25917 `B ADDR,MODE' 25918 Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR. 25919 25920 Don't use this packet. Use the `Z' and `z' packets instead (*note 25921 insert breakpoint or watchpoint packet::). 25922 25923 `bc' 25924 Backward continue. Execute the target system in reverse. No 25925 parameter. *Note Reverse Execution::, for more information. 25926 25927 Reply: *Note Stop Reply Packets::, for the reply specifications. 25928 25929 `bs' 25930 Backward single step. Execute one instruction in reverse. No 25931 parameter. *Note Reverse Execution::, for more information. 25932 25933 Reply: *Note Stop Reply Packets::, for the reply specifications. 25934 25935 `c [ADDR]' 25936 Continue. ADDR is address to resume. If ADDR is omitted, resume 25937 at current address. 25938 25939 Reply: *Note Stop Reply Packets::, for the reply specifications. 25940 25941 `C SIG[;ADDR]' 25942 Continue with signal SIG (hex signal number). If `;ADDR' is 25943 omitted, resume at same address. 25944 25945 Reply: *Note Stop Reply Packets::, for the reply specifications. 25946 25947 `d' 25948 Toggle debug flag. 25949 25950 Don't use this packet; instead, define a general set packet (*note 25951 General Query Packets::). 25952 25953 `D' 25954 `D;PID' 25955 The first form of the packet is used to detach GDB from the remote 25956 system. It is sent to the remote target before GDB disconnects 25957 via the `detach' command. 25958 25959 The second form, including a process ID, is used when multiprocess 25960 protocol extensions are enabled (*note multiprocess extensions::), 25961 to detach only a specific process. The PID is specified as a 25962 big-endian hex string. 25963 25964 Reply: 25965 `OK' 25966 for success 25967 25968 `E NN' 25969 for an error 25970 25971 `F RC,EE,CF;XX' 25972 A reply from GDB to an `F' packet sent by the target. This is 25973 part of the File-I/O protocol extension. *Note File-I/O Remote 25974 Protocol Extension::, for the specification. 25975 25976 `g' 25977 Read general registers. 25978 25979 Reply: 25980 `XX...' 25981 Each byte of register data is described by two hex digits. 25982 The bytes with the register are transmitted in target byte 25983 order. The size of each register and their position within 25984 the `g' packet are determined by the GDB internal gdbarch 25985 functions `DEPRECATED_REGISTER_RAW_SIZE' and 25986 `gdbarch_register_name'. The specification of several 25987 standard `g' packets is specified below. 25988 25989 `E NN' 25990 for an error. 25991 25992 `G XX...' 25993 Write general registers. *Note read registers packet::, for a 25994 description of the XX... data. 25995 25996 Reply: 25997 `OK' 25998 for success 25999 26000 `E NN' 26001 for an error 26002 26003 `H C THREAD-ID' 26004 Set thread for subsequent operations (`m', `M', `g', `G', et.al.). 26005 C depends on the operation to be performed: it should be `c' for 26006 step and continue operations, `g' for other operations. The 26007 thread designator THREAD-ID has the format and interpretation 26008 described in *Note thread-id syntax::. 26009 26010 Reply: 26011 `OK' 26012 for success 26013 26014 `E NN' 26015 for an error 26016 26017 `i [ADDR[,NNN]]' 26018 Step the remote target by a single clock cycle. If `,NNN' is 26019 present, cycle step NNN cycles. If ADDR is present, cycle step 26020 starting at that address. 26021 26022 `I' 26023 Signal, then cycle step. *Note step with signal packet::. *Note 26024 cycle step packet::. 26025 26026 `k' 26027 Kill request. 26028 26029 FIXME: _There is no description of how to operate when a specific 26030 thread context has been selected (i.e. does 'k' kill only that 26031 thread?)_. 26032 26033 `m ADDR,LENGTH' 26034 Read LENGTH bytes of memory starting at address ADDR. Note that 26035 ADDR may not be aligned to any particular boundary. 26036 26037 The stub need not use any particular size or alignment when 26038 gathering data from memory for the response; even if ADDR is 26039 word-aligned and LENGTH is a multiple of the word size, the stub 26040 is free to use byte accesses, or not. For this reason, this 26041 packet may not be suitable for accessing memory-mapped I/O devices. 26042 26043 Reply: 26044 `XX...' 26045 Memory contents; each byte is transmitted as a two-digit 26046 hexadecimal number. The reply may contain fewer bytes than 26047 requested if the server was able to read only part of the 26048 region of memory. 26049 26050 `E NN' 26051 NN is errno 26052 26053 `M ADDR,LENGTH:XX...' 26054 Write LENGTH bytes of memory starting at address ADDR. XX... is 26055 the data; each byte is transmitted as a two-digit hexadecimal 26056 number. 26057 26058 Reply: 26059 `OK' 26060 for success 26061 26062 `E NN' 26063 for an error (this includes the case where only part of the 26064 data was written). 26065 26066 `p N' 26067 Read the value of register N; N is in hex. *Note read registers 26068 packet::, for a description of how the returned register value is 26069 encoded. 26070 26071 Reply: 26072 `XX...' 26073 the register's value 26074 26075 `E NN' 26076 for an error 26077 26078 `' 26079 Indicating an unrecognized QUERY. 26080 26081 `P N...=R...' 26082 Write register N... with value R.... The register number N is in 26083 hexadecimal, and R... contains two hex digits for each byte in the 26084 register (target byte order). 26085 26086 Reply: 26087 `OK' 26088 for success 26089 26090 `E NN' 26091 for an error 26092 26093 `q NAME PARAMS...' 26094 `Q NAME PARAMS...' 26095 General query (`q') and set (`Q'). These packets are described 26096 fully in *Note General Query Packets::. 26097 26098 `r' 26099 Reset the entire system. 26100 26101 Don't use this packet; use the `R' packet instead. 26102 26103 `R XX' 26104 Restart the program being debugged. XX, while needed, is ignored. 26105 This packet is only available in extended mode (*note extended 26106 mode::). 26107 26108 The `R' packet has no reply. 26109 26110 `s [ADDR]' 26111 Single step. ADDR is the address at which to resume. If ADDR is 26112 omitted, resume at same address. 26113 26114 Reply: *Note Stop Reply Packets::, for the reply specifications. 26115 26116 `S SIG[;ADDR]' 26117 Step with signal. This is analogous to the `C' packet, but 26118 requests a single-step, rather than a normal resumption of 26119 execution. 26120 26121 Reply: *Note Stop Reply Packets::, for the reply specifications. 26122 26123 `t ADDR:PP,MM' 26124 Search backwards starting at address ADDR for a match with pattern 26125 PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 26126 digits. 26127 26128 `T THREAD-ID' 26129 Find out if the thread THREAD-ID is alive. *Note thread-id 26130 syntax::. 26131 26132 Reply: 26133 `OK' 26134 thread is still alive 26135 26136 `E NN' 26137 thread is dead 26138 26139 `v' 26140 Packets starting with `v' are identified by a multi-letter name, 26141 up to the first `;' or `?' (or the end of the packet). 26142 26143 `vAttach;PID' 26144 Attach to a new process with the specified process ID PID. The 26145 process ID is a hexadecimal integer identifying the process. In 26146 all-stop mode, all threads in the attached process are stopped; in 26147 non-stop mode, it may be attached without being stopped if that is 26148 supported by the target. 26149 26150 This packet is only available in extended mode (*note extended 26151 mode::). 26152 26153 Reply: 26154 `E NN' 26155 for an error 26156 26157 `Any stop packet' 26158 for success in all-stop mode (*note Stop Reply Packets::) 26159 26160 `OK' 26161 for success in non-stop mode (*note Remote Non-Stop::) 26162 26163 `vCont[;ACTION[:THREAD-ID]]...' 26164 Resume the inferior, specifying different actions for each thread. 26165 If an action is specified with no THREAD-ID, then it is applied to 26166 any threads that don't have a specific action specified; if no 26167 default action is specified then other threads should remain 26168 stopped in all-stop mode and in their current state in non-stop 26169 mode. Specifying multiple default actions is an error; specifying 26170 no actions is also an error. Thread IDs are specified using the 26171 syntax described in *Note thread-id syntax::. 26172 26173 Currently supported actions are: 26174 26175 `c' 26176 Continue. 26177 26178 `C SIG' 26179 Continue with signal SIG. The signal SIG should be two hex 26180 digits. 26181 26182 `s' 26183 Step. 26184 26185 `S SIG' 26186 Step with signal SIG. The signal SIG should be two hex 26187 digits. 26188 26189 `t' 26190 Stop. 26191 26192 The optional argument ADDR normally associated with the `c', `C', 26193 `s', and `S' packets is not supported in `vCont'. 26194 26195 The `t' action is only relevant in non-stop mode (*note Remote 26196 Non-Stop::) and may be ignored by the stub otherwise. A stop 26197 reply should be generated for any affected thread not already 26198 stopped. When a thread is stopped by means of a `t' action, the 26199 corresponding stop reply should indicate that the thread has 26200 stopped with signal `0', regardless of whether the target uses 26201 some other signal as an implementation detail. 26202 26203 Reply: *Note Stop Reply Packets::, for the reply specifications. 26204 26205 `vCont?' 26206 Request a list of actions supported by the `vCont' packet. 26207 26208 Reply: 26209 `vCont[;ACTION...]' 26210 The `vCont' packet is supported. Each ACTION is a supported 26211 command in the `vCont' packet. 26212 26213 `' 26214 The `vCont' packet is not supported. 26215 26216 `vFile:OPERATION:PARAMETER...' 26217 Perform a file operation on the target system. For details, see 26218 *Note Host I/O Packets::. 26219 26220 `vFlashErase:ADDR,LENGTH' 26221 Direct the stub to erase LENGTH bytes of flash starting at ADDR. 26222 The region may enclose any number of flash blocks, but its start 26223 and end must fall on block boundaries, as indicated by the flash 26224 block size appearing in the memory map (*note Memory Map 26225 Format::). GDB groups flash memory programming operations 26226 together, and sends a `vFlashDone' request after each group; the 26227 stub is allowed to delay erase operation until the `vFlashDone' 26228 packet is received. 26229 26230 The stub must support `vCont' if it reports support for 26231 multiprocess extensions (*note multiprocess extensions::). Note 26232 that in this case `vCont' actions can be specified to apply to all 26233 threads in a process by using the `pPID.-1' form of the THREAD-ID. 26234 26235 Reply: 26236 `OK' 26237 for success 26238 26239 `E NN' 26240 for an error 26241 26242 `vFlashWrite:ADDR:XX...' 26243 Direct the stub to write data to flash address ADDR. The data is 26244 passed in binary form using the same encoding as for the `X' 26245 packet (*note Binary Data::). The memory ranges specified by 26246 `vFlashWrite' packets preceding a `vFlashDone' packet must not 26247 overlap, and must appear in order of increasing addresses 26248 (although `vFlashErase' packets for higher addresses may already 26249 have been received; the ordering is guaranteed only between 26250 `vFlashWrite' packets). If a packet writes to an address that was 26251 neither erased by a preceding `vFlashErase' packet nor by some 26252 other target-specific method, the results are unpredictable. 26253 26254 Reply: 26255 `OK' 26256 for success 26257 26258 `E.memtype' 26259 for vFlashWrite addressing non-flash memory 26260 26261 `E NN' 26262 for an error 26263 26264 `vFlashDone' 26265 Indicate to the stub that flash programming operation is finished. 26266 The stub is permitted to delay or batch the effects of a group of 26267 `vFlashErase' and `vFlashWrite' packets until a `vFlashDone' 26268 packet is received. The contents of the affected regions of flash 26269 memory are unpredictable until the `vFlashDone' request is 26270 completed. 26271 26272 `vKill;PID' 26273 Kill the process with the specified process ID. PID is a 26274 hexadecimal integer identifying the process. This packet is used 26275 in preference to `k' when multiprocess protocol extensions are 26276 supported; see *Note multiprocess extensions::. 26277 26278 Reply: 26279 `E NN' 26280 for an error 26281 26282 `OK' 26283 for success 26284 26285 `vRun;FILENAME[;ARGUMENT]...' 26286 Run the program FILENAME, passing it each ARGUMENT on its command 26287 line. The file and arguments are hex-encoded strings. If 26288 FILENAME is an empty string, the stub may use a default program 26289 (e.g. the last program run). The program is created in the stopped 26290 state. 26291 26292 This packet is only available in extended mode (*note extended 26293 mode::). 26294 26295 Reply: 26296 `E NN' 26297 for an error 26298 26299 `Any stop packet' 26300 for success (*note Stop Reply Packets::) 26301 26302 `vStopped' 26303 In non-stop mode (*note Remote Non-Stop::), acknowledge a previous 26304 stop reply and prompt for the stub to report another one. 26305 26306 Reply: 26307 `Any stop packet' 26308 if there is another unreported stop event (*note Stop Reply 26309 Packets::) 26310 26311 `OK' 26312 if there are no unreported stop events 26313 26314 `X ADDR,LENGTH:XX...' 26315 Write data to memory, where the data is transmitted in binary. 26316 ADDR is address, LENGTH is number of bytes, `XX...' is binary data 26317 (*note Binary Data::). 26318 26319 Reply: 26320 `OK' 26321 for success 26322 26323 `E NN' 26324 for an error 26325 26326 `z TYPE,ADDR,KIND' 26327 `Z TYPE,ADDR,KIND' 26328 Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint 26329 starting at address ADDRESS of kind KIND. 26330 26331 Each breakpoint and watchpoint packet TYPE is documented 26332 separately. 26333 26334 _Implementation notes: A remote target shall return an empty string 26335 for an unrecognized breakpoint or watchpoint packet TYPE. A 26336 remote target shall support either both or neither of a given 26337 `ZTYPE...' and `zTYPE...' packet pair. To avoid potential 26338 problems with duplicate packets, the operations should be 26339 implemented in an idempotent way._ 26340 26341 `z0,ADDR,KIND' 26342 `Z0,ADDR,KIND' 26343 Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR 26344 of type KIND. 26345 26346 A memory breakpoint is implemented by replacing the instruction at 26347 ADDR with a software breakpoint or trap instruction. The KIND is 26348 target-specific and typically indicates the size of the breakpoint 26349 in bytes that should be inserted. E.g., the ARM and MIPS can 26350 insert either a 2 or 4 byte breakpoint. Some architectures have 26351 additional meanings for KIND; see *Note Architecture-Specific 26352 Protocol Details::. 26353 26354 _Implementation note: It is possible for a target to copy or move 26355 code that contains memory breakpoints (e.g., when implementing 26356 overlays). The behavior of this packet, in the presence of such a 26357 target, is not defined._ 26358 26359 Reply: 26360 `OK' 26361 success 26362 26363 `' 26364 not supported 26365 26366 `E NN' 26367 for an error 26368 26369 `z1,ADDR,KIND' 26370 `Z1,ADDR,KIND' 26371 Insert (`Z1') or remove (`z1') a hardware breakpoint at address 26372 ADDR. 26373 26374 A hardware breakpoint is implemented using a mechanism that is not 26375 dependant on being able to modify the target's memory. KIND has 26376 the same meaning as in `Z0' packets. 26377 26378 _Implementation note: A hardware breakpoint is not affected by code 26379 movement._ 26380 26381 Reply: 26382 `OK' 26383 success 26384 26385 `' 26386 not supported 26387 26388 `E NN' 26389 for an error 26390 26391 `z2,ADDR,KIND' 26392 `Z2,ADDR,KIND' 26393 Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND 26394 is interpreted as the number of bytes to watch. 26395 26396 Reply: 26397 `OK' 26398 success 26399 26400 `' 26401 not supported 26402 26403 `E NN' 26404 for an error 26405 26406 `z3,ADDR,KIND' 26407 `Z3,ADDR,KIND' 26408 Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is 26409 interpreted as the number of bytes to watch. 26410 26411 Reply: 26412 `OK' 26413 success 26414 26415 `' 26416 not supported 26417 26418 `E NN' 26419 for an error 26420 26421 `z4,ADDR,KIND' 26422 `Z4,ADDR,KIND' 26423 Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND 26424 is interpreted as the number of bytes to watch. 26425 26426 Reply: 26427 `OK' 26428 success 26429 26430 `' 26431 not supported 26432 26433 `E NN' 26434 for an error 26435 26436 26437 26438 File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol 26439 26440 D.3 Stop Reply Packets 26441 ====================== 26442 26443 The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?' 26444 packets can receive any of the below as a reply. Except for `?' and 26445 `vStopped', that reply is only returned when the target halts. In the 26446 below the exact meaning of "signal number" is defined by the header 26447 `include/gdb/signals.h' in the GDB source code. 26448 26449 As in the description of request packets, we include spaces in the 26450 reply templates for clarity; these are not part of the reply packet's 26451 syntax. No GDB stop reply packet uses spaces to separate its 26452 components. 26453 26454 `S AA' 26455 The program received signal number AA (a two-digit hexadecimal 26456 number). This is equivalent to a `T' response with no N:R pairs. 26457 26458 `T AA N1:R1;N2:R2;...' 26459 The program received signal number AA (a two-digit hexadecimal 26460 number). This is equivalent to an `S' response, except that the 26461 `N:R' pairs can carry values of important registers and other 26462 information directly in the stop reply packet, reducing round-trip 26463 latency. Single-step and breakpoint traps are reported this way. 26464 Each `N:R' pair is interpreted as follows: 26465 26466 * If N is a hexadecimal number, it is a register number, and the 26467 corresponding R gives that register's value. R is a series 26468 of bytes in target byte order, with each byte given by a 26469 two-digit hex number. 26470 26471 * If N is `thread', then R is the THREAD-ID of the stopped 26472 thread, as specified in *Note thread-id syntax::. 26473 26474 * If N is `core', then R is the hexadecimal number of the core 26475 on which the stop event was detected. 26476 26477 * If N is a recognized "stop reason", it describes a more 26478 specific event that stopped the target. The currently 26479 defined stop reasons are listed below. AA should be `05', 26480 the trap signal. At most one stop reason should be present. 26481 26482 * Otherwise, GDB should ignore this `N:R' pair and go on to the 26483 next; this allows us to extend the protocol in the future. 26484 26485 The currently defined stop reasons are: 26486 26487 `watch' 26488 `rwatch' 26489 `awatch' 26490 The packet indicates a watchpoint hit, and R is the data 26491 address, in hex. 26492 26493 `library' 26494 The packet indicates that the loaded libraries have changed. 26495 GDB should use `qXfer:libraries:read' to fetch a new list of 26496 loaded libraries. R is ignored. 26497 26498 `replaylog' 26499 The packet indicates that the target cannot continue replaying 26500 logged execution events, because it has reached the end (or 26501 the beginning when executing backward) of the log. The value 26502 of R will be either `begin' or `end'. *Note Reverse 26503 Execution::, for more information. 26504 26505 `W AA' 26506 `W AA ; process:PID' 26507 The process exited, and AA is the exit status. This is only 26508 applicable to certain targets. 26509 26510 The second form of the response, including the process ID of the 26511 exited process, can be used only when GDB has reported support for 26512 multiprocess protocol extensions; see *Note multiprocess 26513 extensions::. The PID is formatted as a big-endian hex string. 26514 26515 `X AA' 26516 `X AA ; process:PID' 26517 The process terminated with signal AA. 26518 26519 The second form of the response, including the process ID of the 26520 terminated process, can be used only when GDB has reported support 26521 for multiprocess protocol extensions; see *Note multiprocess 26522 extensions::. The PID is formatted as a big-endian hex string. 26523 26524 `O XX...' 26525 `XX...' is hex encoding of ASCII data, to be written as the 26526 program's console output. This can happen at any time while the 26527 program is running and the debugger should continue to wait for 26528 `W', `T', etc. This reply is not permitted in non-stop mode. 26529 26530 `F CALL-ID,PARAMETER...' 26531 CALL-ID is the identifier which says which host system call should 26532 be called. This is just the name of the function. Translation 26533 into the correct system call is only applicable as it's defined in 26534 GDB. *Note File-I/O Remote Protocol Extension::, for a list of 26535 implemented system calls. 26536 26537 `PARAMETER...' is a list of parameters as defined for this very 26538 system call. 26539 26540 The target replies with this packet when it expects GDB to call a 26541 host system call on behalf of the target. GDB replies with an 26542 appropriate `F' packet and keeps up waiting for the next reply 26543 packet from the target. The latest `C', `c', `S' or `s' action is 26544 expected to be continued. *Note File-I/O Remote Protocol 26545 Extension::, for more details. 26546 26547 26548 26549 File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol 26550 26551 D.4 General Query Packets 26552 ========================= 26553 26554 Packets starting with `q' are "general query packets"; packets starting 26555 with `Q' are "general set packets". General query and set packets are 26556 a semi-unified form for retrieving and sending information to and from 26557 the stub. 26558 26559 The initial letter of a query or set packet is followed by a name 26560 indicating what sort of thing the packet applies to. For example, GDB 26561 may use a `qSymbol' packet to exchange symbol definitions with the 26562 stub. These packet names follow some conventions: 26563 26564 * The name must not contain commas, colons or semicolons. 26565 26566 * Most GDB query and set packets have a leading upper case letter. 26567 26568 * The names of custom vendor packets should use a company prefix, in 26569 lower case, followed by a period. For example, packets designed at 26570 the Acme Corporation might begin with `qacme.foo' (for querying 26571 foos) or `Qacme.bar' (for setting bars). 26572 26573 The name of a query or set packet should be separated from any 26574 parameters by a `:'; the parameters themselves should be separated by 26575 `,' or `;'. Stubs must be careful to match the full packet name, and 26576 check for a separator or the end of the packet, in case two packet 26577 names share a common prefix. New packets should not begin with `qC', 26578 `qP', or `qL'(1). 26579 26580 Like the descriptions of the other packets, each description here 26581 has a template showing the packet's overall syntax, followed by an 26582 explanation of the packet's meaning. We include spaces in some of the 26583 templates for clarity; these are not part of the packet's syntax. No 26584 GDB packet uses spaces to separate its components. 26585 26586 Here are the currently defined query and set packets: 26587 26588 `qC' 26589 Return the current thread ID. 26590 26591 Reply: 26592 `QC THREAD-ID' 26593 Where THREAD-ID is a thread ID as documented in *Note 26594 thread-id syntax::. 26595 26596 `(anything else)' 26597 Any other reply implies the old thread ID. 26598 26599 `qCRC:ADDR,LENGTH' 26600 Compute the CRC checksum of a block of memory using CRC-32 defined 26601 in IEEE 802.3. The CRC is computed byte at a time, taking the most 26602 significant bit of each byte first. The initial pattern code 26603 `0xffffffff' is used to ensure leading zeros affect the CRC. 26604 26605 _Note:_ This is the same CRC used in validating separate debug 26606 files (*note Debugging Information in Separate Files: Separate 26607 Debug Files.). However the algorithm is slightly different. When 26608 validating separate debug files, the CRC is computed taking the 26609 _least_ significant bit of each byte first, and the final result 26610 is inverted to detect trailing zeros. 26611 26612 Reply: 26613 `E NN' 26614 An error (such as memory fault) 26615 26616 `C CRC32' 26617 The specified memory region's checksum is CRC32. 26618 26619 `qfThreadInfo' 26620 `qsThreadInfo' 26621 Obtain a list of all active thread IDs from the target (OS). 26622 Since there may be too many active threads to fit into one reply 26623 packet, this query works iteratively: it may require more than one 26624 query/reply sequence to obtain the entire list of threads. The 26625 first query of the sequence will be the `qfThreadInfo' query; 26626 subsequent queries in the sequence will be the `qsThreadInfo' 26627 query. 26628 26629 NOTE: This packet replaces the `qL' query (see below). 26630 26631 Reply: 26632 `m THREAD-ID' 26633 A single thread ID 26634 26635 `m THREAD-ID,THREAD-ID...' 26636 a comma-separated list of thread IDs 26637 26638 `l' 26639 (lower case letter `L') denotes end of list. 26640 26641 In response to each query, the target will reply with a list of 26642 one or more thread IDs, separated by commas. GDB will respond to 26643 each reply with a request for more thread ids (using the `qs' form 26644 of the query), until the target responds with `l' (lower-case el, 26645 for "last"). Refer to *Note thread-id syntax::, for the format of 26646 the THREAD-ID fields. 26647 26648 `qGetTLSAddr:THREAD-ID,OFFSET,LM' 26649 Fetch the address associated with thread local storage specified 26650 by THREAD-ID, OFFSET, and LM. 26651 26652 THREAD-ID is the thread ID associated with the thread for which to 26653 fetch the TLS address. *Note thread-id syntax::. 26654 26655 OFFSET is the (big endian, hex encoded) offset associated with the 26656 thread local variable. (This offset is obtained from the debug 26657 information associated with the variable.) 26658 26659 LM is the (big endian, hex encoded) OS/ABI-specific encoding of the 26660 the load module associated with the thread local storage. For 26661 example, a GNU/Linux system will pass the link map address of the 26662 shared object associated with the thread local storage under 26663 consideration. Other operating environments may choose to 26664 represent the load module differently, so the precise meaning of 26665 this parameter will vary. 26666 26667 Reply: 26668 `XX...' 26669 Hex encoded (big endian) bytes representing the address of 26670 the thread local storage requested. 26671 26672 `E NN' 26673 An error occurred. NN are hex digits. 26674 26675 `' 26676 An empty reply indicates that `qGetTLSAddr' is not supported 26677 by the stub. 26678 26679 `qL STARTFLAG THREADCOUNT NEXTTHREAD' 26680 Obtain thread information from RTOS. Where: STARTFLAG (one hex 26681 digit) is one to indicate the first query and zero to indicate a 26682 subsequent query; THREADCOUNT (two hex digits) is the maximum 26683 number of threads the response packet can contain; and NEXTTHREAD 26684 (eight hex digits), for subsequent queries (STARTFLAG is zero), is 26685 returned in the response as ARGTHREAD. 26686 26687 Don't use this packet; use the `qfThreadInfo' query instead (see 26688 above). 26689 26690 Reply: 26691 `qM COUNT DONE ARGTHREAD THREAD...' 26692 Where: COUNT (two hex digits) is the number of threads being 26693 returned; DONE (one hex digit) is zero to indicate more 26694 threads and one indicates no further threads; ARGTHREADID 26695 (eight hex digits) is NEXTTHREAD from the request packet; 26696 THREAD... is a sequence of thread IDs from the target. 26697 THREADID (eight hex digits). See 26698 `remote.c:parse_threadlist_response()'. 26699 26700 `qOffsets' 26701 Get section offsets that the target used when relocating the 26702 downloaded image. 26703 26704 Reply: 26705 `Text=XXX;Data=YYY[;Bss=ZZZ]' 26706 Relocate the `Text' section by XXX from its original address. 26707 Relocate the `Data' section by YYY from its original address. 26708 If the object file format provides segment information (e.g. 26709 ELF `PT_LOAD' program headers), GDB will relocate entire 26710 segments by the supplied offsets. 26711 26712 _Note: while a `Bss' offset may be included in the response, 26713 GDB ignores this and instead applies the `Data' offset to the 26714 `Bss' section._ 26715 26716 `TextSeg=XXX[;DataSeg=YYY]' 26717 Relocate the first segment of the object file, which 26718 conventionally contains program code, to a starting address 26719 of XXX. If `DataSeg' is specified, relocate the second 26720 segment, which conventionally contains modifiable data, to a 26721 starting address of YYY. GDB will report an error if the 26722 object file does not contain segment information, or does not 26723 contain at least as many segments as mentioned in the reply. 26724 Extra segments are kept at fixed offsets relative to the last 26725 relocated segment. 26726 26727 `qP MODE THREAD-ID' 26728 Returns information on THREAD-ID. Where: MODE is a hex encoded 32 26729 bit mode; THREAD-ID is a thread ID (*note thread-id syntax::). 26730 26731 Don't use this packet; use the `qThreadExtraInfo' query instead 26732 (see below). 26733 26734 Reply: see `remote.c:remote_unpack_thread_info_response()'. 26735 26736 `QNonStop:1' 26737 26738 `QNonStop:0' 26739 Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode. 26740 *Note Remote Non-Stop::, for more information. 26741 26742 Reply: 26743 `OK' 26744 The request succeeded. 26745 26746 `E NN' 26747 An error occurred. NN are hex digits. 26748 26749 `' 26750 An empty reply indicates that `QNonStop' is not supported by 26751 the stub. 26752 26753 This packet is not probed by default; the remote stub must request 26754 it, by supplying an appropriate `qSupported' response (*note 26755 qSupported::). Use of this packet is controlled by the `set 26756 non-stop' command; *note Non-Stop Mode::. 26757 26758 `QPassSignals: SIGNAL [;SIGNAL]...' 26759 Each listed SIGNAL should be passed directly to the inferior 26760 process. Signals are numbered identically to continue packets and 26761 stop replies (*note Stop Reply Packets::). Each SIGNAL list item 26762 should be strictly greater than the previous item. These signals 26763 do not need to stop the inferior, or be reported to GDB. All 26764 other signals should be reported to GDB. Multiple `QPassSignals' 26765 packets do not combine; any earlier `QPassSignals' list is 26766 completely replaced by the new list. This packet improves 26767 performance when using `handle SIGNAL nostop noprint pass'. 26768 26769 Reply: 26770 `OK' 26771 The request succeeded. 26772 26773 `E NN' 26774 An error occurred. NN are hex digits. 26775 26776 `' 26777 An empty reply indicates that `QPassSignals' is not supported 26778 by the stub. 26779 26780 Use of this packet is controlled by the `set remote pass-signals' 26781 command (*note set remote pass-signals: Remote Configuration.). 26782 This packet is not probed by default; the remote stub must request 26783 it, by supplying an appropriate `qSupported' response (*note 26784 qSupported::). 26785 26786 `qRcmd,COMMAND' 26787 COMMAND (hex encoded) is passed to the local interpreter for 26788 execution. Invalid commands should be reported using the output 26789 string. Before the final result packet, the target may also 26790 respond with a number of intermediate `OOUTPUT' console output 26791 packets. _Implementors should note that providing access to a 26792 stubs's interpreter may have security implications_. 26793 26794 Reply: 26795 `OK' 26796 A command response with no output. 26797 26798 `OUTPUT' 26799 A command response with the hex encoded output string OUTPUT. 26800 26801 `E NN' 26802 Indicate a badly formed request. 26803 26804 `' 26805 An empty reply indicates that `qRcmd' is not recognized. 26806 26807 (Note that the `qRcmd' packet's name is separated from the command 26808 by a `,', not a `:', contrary to the naming conventions above. 26809 Please don't use this packet as a model for new packets.) 26810 26811 `qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN' 26812 Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and 26813 LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes, 26814 hex encoded. 26815 26816 Reply: 26817 `0' 26818 The pattern was not found. 26819 26820 `1,address' 26821 The pattern was found at ADDRESS. 26822 26823 `E NN' 26824 A badly formed request or an error was encountered while 26825 searching memory. 26826 26827 `' 26828 An empty reply indicates that `qSearch:memory' is not 26829 recognized. 26830 26831 `QStartNoAckMode' 26832 Request that the remote stub disable the normal `+'/`-' protocol 26833 acknowledgments (*note Packet Acknowledgment::). 26834 26835 Reply: 26836 `OK' 26837 The stub has switched to no-acknowledgment mode. GDB 26838 acknowledges this reponse, but neither the stub nor GDB shall 26839 send or expect further `+'/`-' acknowledgments in the current 26840 connection. 26841 26842 `' 26843 An empty reply indicates that the stub does not support 26844 no-acknowledgment mode. 26845 26846 `qSupported [:GDBFEATURE [;GDBFEATURE]... ]' 26847 Tell the remote stub about features supported by GDB, and query 26848 the stub for features it supports. This packet allows GDB and the 26849 remote stub to take advantage of each others' features. 26850 `qSupported' also consolidates multiple feature probes at startup, 26851 to improve GDB performance--a single larger packet performs better 26852 than multiple smaller probe packets on high-latency links. Some 26853 features may enable behavior which must not be on by default, e.g. 26854 because it would confuse older clients or stubs. Other features 26855 may describe packets which could be automatically probed for, but 26856 are not. These features must be reported before GDB will use 26857 them. This "default unsupported" behavior is not appropriate for 26858 all packets, but it helps to keep the initial connection time 26859 under control with new versions of GDB which support increasing 26860 numbers of packets. 26861 26862 Reply: 26863 `STUBFEATURE [;STUBFEATURE]...' 26864 The stub supports or does not support each returned 26865 STUBFEATURE, depending on the form of each STUBFEATURE (see 26866 below for the possible forms). 26867 26868 `' 26869 An empty reply indicates that `qSupported' is not recognized, 26870 or that no features needed to be reported to GDB. 26871 26872 The allowed forms for each feature (either a GDBFEATURE in the 26873 `qSupported' packet, or a STUBFEATURE in the response) are: 26874 26875 `NAME=VALUE' 26876 The remote protocol feature NAME is supported, and associated 26877 with the specified VALUE. The format of VALUE depends on the 26878 feature, but it must not include a semicolon. 26879 26880 `NAME+' 26881 The remote protocol feature NAME is supported, and does not 26882 need an associated value. 26883 26884 `NAME-' 26885 The remote protocol feature NAME is not supported. 26886 26887 `NAME?' 26888 The remote protocol feature NAME may be supported, and GDB 26889 should auto-detect support in some other way when it is 26890 needed. This form will not be used for GDBFEATURE 26891 notifications, but may be used for STUBFEATURE responses. 26892 26893 Whenever the stub receives a `qSupported' request, the supplied 26894 set of GDB features should override any previous request. This 26895 allows GDB to put the stub in a known state, even if the stub had 26896 previously been communicating with a different version of GDB. 26897 26898 The following values of GDBFEATURE (for the packet sent by GDB) 26899 are defined: 26900 26901 `multiprocess' 26902 This feature indicates whether GDB supports multiprocess 26903 extensions to the remote protocol. GDB does not use such 26904 extensions unless the stub also reports that it supports them 26905 by including `multiprocess+' in its `qSupported' reply. 26906 *Note multiprocess extensions::, for details. 26907 26908 Stubs should ignore any unknown values for GDBFEATURE. Any GDB 26909 which sends a `qSupported' packet supports receiving packets of 26910 unlimited length (earlier versions of GDB may reject overly long 26911 responses). Additional values for GDBFEATURE may be defined in 26912 the future to let the stub take advantage of new features in GDB, 26913 e.g. incompatible improvements in the remote protocol--the 26914 `multiprocess' feature is an example of such a feature. The 26915 stub's reply should be independent of the GDBFEATURE entries sent 26916 by GDB; first GDB describes all the features it supports, and then 26917 the stub replies with all the features it supports. 26918 26919 Similarly, GDB will silently ignore unrecognized stub feature 26920 responses, as long as each response uses one of the standard forms. 26921 26922 Some features are flags. A stub which supports a flag feature 26923 should respond with a `+' form response. Other features require 26924 values, and the stub should respond with an `=' form response. 26925 26926 Each feature has a default value, which GDB will use if 26927 `qSupported' is not available or if the feature is not mentioned 26928 in the `qSupported' response. The default values are fixed; a 26929 stub is free to omit any feature responses that match the defaults. 26930 26931 Not all features can be probed, but for those which can, the 26932 probing mechanism is useful: in some cases, a stub's internal 26933 architecture may not allow the protocol layer to know some 26934 information about the underlying target in advance. This is 26935 especially common in stubs which may be configured for multiple 26936 targets. 26937 26938 These are the currently defined stub features and their properties: 26939 26940 Feature Name Value Default Probe Allowed 26941 Required 26942 `PacketSize' Yes `-' No 26943 `qXfer:auxv:read' No `-' Yes 26944 `qXfer:features:read' No `-' Yes 26945 `qXfer:libraries:read' No `-' Yes 26946 `qXfer:memory-map:read' No `-' Yes 26947 `qXfer:spu:read' No `-' Yes 26948 `qXfer:spu:write' No `-' Yes 26949 `qXfer:siginfo:read' No `-' Yes 26950 `qXfer:siginfo:write' No `-' Yes 26951 `qXfer:threads:read' No `-' Yes 26952 `QNonStop' No `-' Yes 26953 `QPassSignals' No `-' Yes 26954 `QStartNoAckMode' No `-' Yes 26955 `multiprocess' No `-' No 26956 `ConditionalTracepoints'No `-' No 26957 `ReverseContinue' No `-' No 26958 `ReverseStep' No `-' No 26959 26960 These are the currently defined stub features, in more detail: 26961 26962 `PacketSize=BYTES' 26963 The remote stub can accept packets up to at least BYTES in 26964 length. GDB will send packets up to this size for bulk 26965 transfers, and will never send larger packets. This is a 26966 limit on the data characters in the packet, including the 26967 frame and checksum. There is no trailing NUL byte in a 26968 remote protocol packet; if the stub stores packets in a 26969 NUL-terminated format, it should allow an extra byte in its 26970 buffer for the NUL. If this stub feature is not supported, 26971 GDB guesses based on the size of the `g' packet response. 26972 26973 `qXfer:auxv:read' 26974 The remote stub understands the `qXfer:auxv:read' packet 26975 (*note qXfer auxiliary vector read::). 26976 26977 `qXfer:features:read' 26978 The remote stub understands the `qXfer:features:read' packet 26979 (*note qXfer target description read::). 26980 26981 `qXfer:libraries:read' 26982 The remote stub understands the `qXfer:libraries:read' packet 26983 (*note qXfer library list read::). 26984 26985 `qXfer:memory-map:read' 26986 The remote stub understands the `qXfer:memory-map:read' packet 26987 (*note qXfer memory map read::). 26988 26989 `qXfer:spu:read' 26990 The remote stub understands the `qXfer:spu:read' packet 26991 (*note qXfer spu read::). 26992 26993 `qXfer:spu:write' 26994 The remote stub understands the `qXfer:spu:write' packet 26995 (*note qXfer spu write::). 26996 26997 `qXfer:siginfo:read' 26998 The remote stub understands the `qXfer:siginfo:read' packet 26999 (*note qXfer siginfo read::). 27000 27001 `qXfer:siginfo:write' 27002 The remote stub understands the `qXfer:siginfo:write' packet 27003 (*note qXfer siginfo write::). 27004 27005 `qXfer:threads:read' 27006 The remote stub understands the `qXfer:threads:read' packet 27007 (*note qXfer threads read::). 27008 27009 `QNonStop' 27010 The remote stub understands the `QNonStop' packet (*note 27011 QNonStop::). 27012 27013 `QPassSignals' 27014 The remote stub understands the `QPassSignals' packet (*note 27015 QPassSignals::). 27016 27017 `QStartNoAckMode' 27018 The remote stub understands the `QStartNoAckMode' packet and 27019 prefers to operate in no-acknowledgment mode. *Note Packet 27020 Acknowledgment::. 27021 27022 `multiprocess' 27023 The remote stub understands the multiprocess extensions to 27024 the remote protocol syntax. The multiprocess extensions 27025 affect the syntax of thread IDs in both packets and replies 27026 (*note thread-id syntax::), and add process IDs to the `D' 27027 packet and `W' and `X' replies. Note that reporting this 27028 feature indicates support for the syntactic extensions only, 27029 not that the stub necessarily supports debugging of more than 27030 one process at a time. The stub must not use multiprocess 27031 extensions in packet replies unless GDB has also indicated it 27032 supports them in its `qSupported' request. 27033 27034 `qXfer:osdata:read' 27035 The remote stub understands the `qXfer:osdata:read' packet 27036 ((*note qXfer osdata read::). 27037 27038 `ConditionalTracepoints' 27039 The remote stub accepts and implements conditional 27040 expressions defined for tracepoints (*note Tracepoint 27041 Conditions::). 27042 27043 `ReverseContinue' 27044 The remote stub accepts and implements the reverse continue 27045 packet (*note bc::). 27046 27047 `ReverseStep' 27048 The remote stub accepts and implements the reverse step packet 27049 (*note bs::). 27050 27051 27052 `qSymbol::' 27053 Notify the target that GDB is prepared to serve symbol lookup 27054 requests. Accept requests from the target for the values of 27055 symbols. 27056 27057 Reply: 27058 `OK' 27059 The target does not need to look up any (more) symbols. 27060 27061 `qSymbol:SYM_NAME' 27062 The target requests the value of symbol SYM_NAME (hex 27063 encoded). GDB may provide the value by using the 27064 `qSymbol:SYM_VALUE:SYM_NAME' message, described below. 27065 27066 `qSymbol:SYM_VALUE:SYM_NAME' 27067 Set the value of SYM_NAME to SYM_VALUE. 27068 27069 SYM_NAME (hex encoded) is the name of a symbol whose value the 27070 target has previously requested. 27071 27072 SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot 27073 supply a value for SYM_NAME, then this field will be empty. 27074 27075 Reply: 27076 `OK' 27077 The target does not need to look up any (more) symbols. 27078 27079 `qSymbol:SYM_NAME' 27080 The target requests the value of a new symbol SYM_NAME (hex 27081 encoded). GDB will continue to supply the values of symbols 27082 (if available), until the target ceases to request them. 27083 27084 `qTBuffer' 27085 27086 `QTDisconnected' 27087 `QTDP' 27088 `QTDV' 27089 `qTfP' 27090 `qTfV' 27091 `QTFrame' 27092 *Note Tracepoint Packets::. 27093 27094 `qThreadExtraInfo,THREAD-ID' 27095 Obtain a printable string description of a thread's attributes from 27096 the target OS. THREAD-ID is a thread ID; see *Note thread-id 27097 syntax::. This string may contain anything that the target OS 27098 thinks is interesting for GDB to tell the user about the thread. 27099 The string is displayed in GDB's `info threads' display. Some 27100 examples of possible thread extra info strings are `Runnable', or 27101 `Blocked on Mutex'. 27102 27103 Reply: 27104 `XX...' 27105 Where `XX...' is a hex encoding of ASCII data, comprising the 27106 printable string containing the extra information about the 27107 thread's attributes. 27108 27109 (Note that the `qThreadExtraInfo' packet's name is separated from 27110 the command by a `,', not a `:', contrary to the naming 27111 conventions above. Please don't use this packet as a model for new 27112 packets.) 27113 27114 `QTSave' 27115 27116 `qTsP' 27117 27118 `qTsV' 27119 `QTStart' 27120 `QTStop' 27121 `QTinit' 27122 `QTro' 27123 `qTStatus' 27124 `qTV' 27125 *Note Tracepoint Packets::. 27126 27127 `qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH' 27128 Read uninterpreted bytes from the target's special data area 27129 identified by the keyword OBJECT. Request LENGTH bytes starting 27130 at OFFSET bytes into the data. The content and encoding of ANNEX 27131 is specific to OBJECT; it can supply additional details about what 27132 data to access. 27133 27134 Here are the specific requests of this form defined so far. All 27135 `qXfer:OBJECT:read:...' requests use the same reply formats, 27136 listed below. 27137 27138 `qXfer:auxv:read::OFFSET,LENGTH' 27139 Access the target's "auxiliary vector". *Note auxiliary 27140 vector: OS Information. Note ANNEX must be empty. 27141 27142 This packet is not probed by default; the remote stub must 27143 request it, by supplying an appropriate `qSupported' response 27144 (*note qSupported::). 27145 27146 `qXfer:features:read:ANNEX:OFFSET,LENGTH' 27147 Access the "target description". *Note Target 27148 Descriptions::. The annex specifies which XML document to 27149 access. The main description is always loaded from the 27150 `target.xml' annex. 27151 27152 This packet is not probed by default; the remote stub must 27153 request it, by supplying an appropriate `qSupported' response 27154 (*note qSupported::). 27155 27156 `qXfer:libraries:read:ANNEX:OFFSET,LENGTH' 27157 Access the target's list of loaded libraries. *Note Library 27158 List Format::. The annex part of the generic `qXfer' packet 27159 must be empty (*note qXfer read::). 27160 27161 Targets which maintain a list of libraries in the program's 27162 memory do not need to implement this packet; it is designed 27163 for platforms where the operating system manages the list of 27164 loaded libraries. 27165 27166 This packet is not probed by default; the remote stub must 27167 request it, by supplying an appropriate `qSupported' response 27168 (*note qSupported::). 27169 27170 `qXfer:memory-map:read::OFFSET,LENGTH' 27171 Access the target's "memory-map". *Note Memory Map Format::. 27172 The annex part of the generic `qXfer' packet must be empty 27173 (*note qXfer read::). 27174 27175 This packet is not probed by default; the remote stub must 27176 request it, by supplying an appropriate `qSupported' response 27177 (*note qSupported::). 27178 27179 `qXfer:siginfo:read::OFFSET,LENGTH' 27180 Read contents of the extra signal information on the target 27181 system. The annex part of the generic `qXfer' packet must be 27182 empty (*note qXfer read::). 27183 27184 This packet is not probed by default; the remote stub must 27185 request it, by supplying an appropriate `qSupported' response 27186 (*note qSupported::). 27187 27188 `qXfer:spu:read:ANNEX:OFFSET,LENGTH' 27189 Read contents of an `spufs' file on the target system. The 27190 annex specifies which file to read; it must be of the form 27191 `ID/NAME', where ID specifies an SPU context ID in the target 27192 process, and NAME identifes the `spufs' file in that context 27193 to be accessed. 27194 27195 This packet is not probed by default; the remote stub must 27196 request it, by supplying an appropriate `qSupported' response 27197 (*note qSupported::). 27198 27199 `qXfer:threads:read::OFFSET,LENGTH' 27200 Access the list of threads on target. *Note Thread List 27201 Format::. The annex part of the generic `qXfer' packet must 27202 be empty (*note qXfer read::). 27203 27204 This packet is not probed by default; the remote stub must 27205 request it, by supplying an appropriate `qSupported' response 27206 (*note qSupported::). 27207 27208 `qXfer:osdata:read::OFFSET,LENGTH' 27209 Access the target's "operating system information". *Note 27210 Operating System Information::. 27211 27212 27213 Reply: 27214 `m DATA' 27215 Data DATA (*note Binary Data::) has been read from the 27216 target. There may be more data at a higher address (although 27217 it is permitted to return `m' even for the last valid block 27218 of data, as long as at least one byte of data was read). 27219 DATA may have fewer bytes than the LENGTH in the request. 27220 27221 `l DATA' 27222 Data DATA (*note Binary Data::) has been read from the target. 27223 There is no more data to be read. DATA may have fewer bytes 27224 than the LENGTH in the request. 27225 27226 `l' 27227 The OFFSET in the request is at the end of the data. There 27228 is no more data to be read. 27229 27230 `E00' 27231 The request was malformed, or ANNEX was invalid. 27232 27233 `E NN' 27234 The offset was invalid, or there was an error encountered 27235 reading the data. NN is a hex-encoded `errno' value. 27236 27237 `' 27238 An empty reply indicates the OBJECT string was not recognized 27239 by the stub, or that the object does not support reading. 27240 27241 `qXfer:OBJECT:write:ANNEX:OFFSET:DATA...' 27242 Write uninterpreted bytes into the target's special data area 27243 identified by the keyword OBJECT, starting at OFFSET bytes into 27244 the data. DATA... is the binary-encoded data (*note Binary 27245 Data::) to be written. The content and encoding of ANNEX is 27246 specific to OBJECT; it can supply additional details about what 27247 data to access. 27248 27249 Here are the specific requests of this form defined so far. All 27250 `qXfer:OBJECT:write:...' requests use the same reply formats, 27251 listed below. 27252 27253 `qXfer:siginfo:write::OFFSET:DATA...' 27254 Write DATA to the extra signal information on the target 27255 system. The annex part of the generic `qXfer' packet must be 27256 empty (*note qXfer write::). 27257 27258 This packet is not probed by default; the remote stub must 27259 request it, by supplying an appropriate `qSupported' response 27260 (*note qSupported::). 27261 27262 `qXfer:spu:write:ANNEX:OFFSET:DATA...' 27263 Write DATA to an `spufs' file on the target system. The 27264 annex specifies which file to write; it must be of the form 27265 `ID/NAME', where ID specifies an SPU context ID in the target 27266 process, and NAME identifes the `spufs' file in that context 27267 to be accessed. 27268 27269 This packet is not probed by default; the remote stub must 27270 request it, by supplying an appropriate `qSupported' response 27271 (*note qSupported::). 27272 27273 Reply: 27274 `NN' 27275 NN (hex encoded) is the number of bytes written. This may be 27276 fewer bytes than supplied in the request. 27277 27278 `E00' 27279 The request was malformed, or ANNEX was invalid. 27280 27281 `E NN' 27282 The offset was invalid, or there was an error encountered 27283 writing the data. NN is a hex-encoded `errno' value. 27284 27285 `' 27286 An empty reply indicates the OBJECT string was not recognized 27287 by the stub, or that the object does not support writing. 27288 27289 `qXfer:OBJECT:OPERATION:...' 27290 Requests of this form may be added in the future. When a stub does 27291 not recognize the OBJECT keyword, or its support for OBJECT does 27292 not recognize the OPERATION keyword, the stub must respond with an 27293 empty packet. 27294 27295 `qAttached:PID' 27296 Return an indication of whether the remote server attached to an 27297 existing process or created a new process. When the multiprocess 27298 protocol extensions are supported (*note multiprocess 27299 extensions::), PID is an integer in hexadecimal format identifying 27300 the target process. Otherwise, GDB will omit the PID field and 27301 the query packet will be simplified as `qAttached'. 27302 27303 This query is used, for example, to know whether the remote process 27304 should be detached or killed when a GDB session is ended with the 27305 `quit' command. 27306 27307 Reply: 27308 `1' 27309 The remote server attached to an existing process. 27310 27311 `0' 27312 The remote server created a new process. 27313 27314 `E NN' 27315 A badly formed request or an error was encountered. 27316 27317 27318 ---------- Footnotes ---------- 27319 27320 (1) The `qP' and `qL' packets predate these conventions, and have 27321 arguments without any terminator for the packet name; we suspect they 27322 are in widespread use in places that are difficult to upgrade. The 27323 `qC' packet has no arguments, but some existing stubs (e.g. RedBoot) 27324 are known to not check for the end of the packet. 27325 27326 27327 File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol 27328 27329 D.5 Architecture-Specific Protocol Details 27330 ========================================== 27331 27332 This section describes how the remote protocol is applied to specific 27333 target architectures. Also see *Note Standard Target Features::, for 27334 details of XML target descriptions for each architecture. 27335 27336 D.5.1 ARM 27337 --------- 27338 27339 D.5.1.1 Breakpoint Kinds 27340 ........................ 27341 27342 These breakpoint kinds are defined for the `Z0' and `Z1' packets. 27343 27344 2 27345 16-bit Thumb mode breakpoint. 27346 27347 3 27348 32-bit Thumb mode (Thumb-2) breakpoint. 27349 27350 4 27351 32-bit ARM mode breakpoint. 27352 27353 27354 D.5.2 MIPS 27355 ---------- 27356 27357 D.5.2.1 Register Packet Format 27358 .............................. 27359 27360 The following `g'/`G' packets have previously been defined. In the 27361 below, some thirty-two bit registers are transferred as sixty-four 27362 bits. Those registers should be zero/sign extended (which?) to fill 27363 the space allocated. Register bytes are transferred in target byte 27364 order. The two nibbles within a register byte are transferred 27365 most-significant - least-significant. 27366 27367 MIPS32 27368 All registers are transferred as thirty-two bit quantities in the 27369 order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 27370 floating-point registers; fsr; fir; fp. 27371 27372 MIPS64 27373 All registers are transferred as sixty-four bit quantities 27374 (including thirty-two bit registers such as `sr'). The ordering 27375 is the same as `MIPS32'. 27376 27377 27378 27379 File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol 27380 27381 D.6 Tracepoint Packets 27382 ====================== 27383 27384 Here we describe the packets GDB uses to implement tracepoints (*note 27385 Tracepoints::). 27386 27387 `QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]' 27388 Create a new tracepoint, number N, at ADDR. If ENA is `E', then 27389 the tracepoint is enabled; if it is `D', then the tracepoint is 27390 disabled. STEP is the tracepoint's step count, and PASS is its 27391 pass count. If an `F' is present, then the tracepoint is to be a 27392 fast tracepoint, and the FLEN is the number of bytes that the 27393 target should copy elsewhere to make room for the tracepoint. If 27394 an `X' is present, it introduces a tracepoint condition, which 27395 consists of a hexadecimal length, followed by a comma and 27396 hex-encoded bytes, in a manner similar to action encodings as 27397 described below. If the trailing `-' is present, further `QTDP' 27398 packets will follow to specify this tracepoint's actions. 27399 27400 Replies: 27401 `OK' 27402 The packet was understood and carried out. 27403 27404 `' 27405 The packet was not recognized. 27406 27407 `QTDP:-N:ADDR:[S]ACTION...[-]' 27408 Define actions to be taken when a tracepoint is hit. N and ADDR 27409 must be the same as in the initial `QTDP' packet for this 27410 tracepoint. This packet may only be sent immediately after 27411 another `QTDP' packet that ended with a `-'. If the trailing `-' 27412 is present, further `QTDP' packets will follow, specifying more 27413 actions for this tracepoint. 27414 27415 In the series of action packets for a given tracepoint, at most one 27416 can have an `S' before its first ACTION. If such a packet is 27417 sent, it and the following packets define "while-stepping" 27418 actions. Any prior packets define ordinary actions -- that is, 27419 those taken when the tracepoint is first hit. If no action packet 27420 has an `S', then all the packets in the series specify ordinary 27421 tracepoint actions. 27422 27423 The `ACTION...' portion of the packet is a series of actions, 27424 concatenated without separators. Each action has one of the 27425 following forms: 27426 27427 `R MASK' 27428 Collect the registers whose bits are set in MASK. MASK is a 27429 hexadecimal number whose I'th bit is set if register number I 27430 should be collected. (The least significant bit is numbered 27431 zero.) Note that MASK may be any number of digits long; it 27432 may not fit in a 32-bit word. 27433 27434 `M BASEREG,OFFSET,LEN' 27435 Collect LEN bytes of memory starting at the address in 27436 register number BASEREG, plus OFFSET. If BASEREG is `-1', 27437 then the range has a fixed address: OFFSET is the address of 27438 the lowest byte to collect. The BASEREG, OFFSET, and LEN 27439 parameters are all unsigned hexadecimal values (the `-1' 27440 value for BASEREG is a special case). 27441 27442 `X LEN,EXPR' 27443 Evaluate EXPR, whose length is LEN, and collect memory as it 27444 directs. EXPR is an agent expression, as described in *Note 27445 Agent Expressions::. Each byte of the expression is encoded 27446 as a two-digit hex number in the packet; LEN is the number of 27447 bytes in the expression (and thus one-half the number of hex 27448 digits in the packet). 27449 27450 27451 Any number of actions may be packed together in a single `QTDP' 27452 packet, as long as the packet does not exceed the maximum packet 27453 length (400 bytes, for many stubs). There may be only one `R' 27454 action per tracepoint, and it must precede any `M' or `X' actions. 27455 Any registers referred to by `M' and `X' actions must be 27456 collected by a preceding `R' action. (The "while-stepping" 27457 actions are treated as if they were attached to a separate 27458 tracepoint, as far as these restrictions are concerned.) 27459 27460 Replies: 27461 `OK' 27462 The packet was understood and carried out. 27463 27464 `' 27465 The packet was not recognized. 27466 27467 `QTDV:N:VALUE' 27468 Create a new trace state variable, number N, with an initial value 27469 of VALUE, which is a 64-bit signed integer. Both N and VALUE are 27470 encoded as hexadecimal values. GDB has the option of not using 27471 this packet for initial values of zero; the target should simply 27472 create the trace state variables as they are mentioned in 27473 expressions. 27474 27475 `QTFrame:N' 27476 Select the N'th tracepoint frame from the buffer, and use the 27477 register and memory contents recorded there to answer subsequent 27478 request packets from GDB. 27479 27480 A successful reply from the stub indicates that the stub has found 27481 the requested frame. The response is a series of parts, 27482 concatenated without separators, describing the frame we selected. 27483 Each part has one of the following forms: 27484 27485 `F F' 27486 The selected frame is number N in the trace frame buffer; F 27487 is a hexadecimal number. If F is `-1', then there was no 27488 frame matching the criteria in the request packet. 27489 27490 `T T' 27491 The selected trace frame records a hit of tracepoint number T; 27492 T is a hexadecimal number. 27493 27494 27495 `QTFrame:pc:ADDR' 27496 Like `QTFrame:N', but select the first tracepoint frame after the 27497 currently selected frame whose PC is ADDR; ADDR is a hexadecimal 27498 number. 27499 27500 `QTFrame:tdp:T' 27501 Like `QTFrame:N', but select the first tracepoint frame after the 27502 currently selected frame that is a hit of tracepoint T; T is a 27503 hexadecimal number. 27504 27505 `QTFrame:range:START:END' 27506 Like `QTFrame:N', but select the first tracepoint frame after the 27507 currently selected frame whose PC is between START (inclusive) and 27508 END (inclusive); START and END are hexadecimal numbers. 27509 27510 `QTFrame:outside:START:END' 27511 Like `QTFrame:range:START:END', but select the first frame 27512 _outside_ the given range of addresses (exclusive). 27513 27514 `QTStart' 27515 Begin the tracepoint experiment. Begin collecting data from 27516 tracepoint hits in the trace frame buffer. 27517 27518 `QTStop' 27519 End the tracepoint experiment. Stop collecting trace frames. 27520 27521 `QTinit' 27522 Clear the table of tracepoints, and empty the trace frame buffer. 27523 27524 `QTro:START1,END1:START2,END2:...' 27525 Establish the given ranges of memory as "transparent". The stub 27526 will answer requests for these ranges from memory's current 27527 contents, if they were not collected as part of the tracepoint hit. 27528 27529 GDB uses this to mark read-only regions of memory, like those 27530 containing program code. Since these areas never change, they 27531 should still have the same contents they did when the tracepoint 27532 was hit, so there's no reason for the stub to refuse to provide 27533 their contents. 27534 27535 `QTDisconnected:VALUE' 27536 Set the choice to what to do with the tracing run when GDB 27537 disconnects from the target. A VALUE of 1 directs the target to 27538 continue the tracing run, while 0 tells the target to stop tracing 27539 if GDB is no longer in the picture. 27540 27541 `qTStatus' 27542 Ask the stub if there is a trace experiment running right now. 27543 27544 Replies: 27545 `T0' 27546 There is no trace experiment running. 27547 27548 `T1' 27549 There is a trace experiment running. 27550 27551 `qTV:VAR' 27552 Ask the stub for the value of the trace state variable number VAR. 27553 27554 Replies: 27555 `VVALUE' 27556 The value of the variable is VALUE. This will be the current 27557 value of the variable if the user is examining a running 27558 target, or a saved value if the variable was collected in the 27559 trace frame that the user is looking at. Note that multiple 27560 requests may result in different reply values, such as when 27561 requesting values while the program is running. 27562 27563 `U' 27564 The value of the variable is unknown. This would occur, for 27565 example, if the user is examining a trace frame in which the 27566 requested variable was not collected. 27567 27568 `qTfP' 27569 `qTsP' 27570 These packets request data about tracepoints that are being used by 27571 the target. GDB sends `qTfP' to get the first piece of data, and 27572 multiple `qTsP' to get additional pieces. Replies to these 27573 packets generally take the form of the `QTDP' packets that define 27574 tracepoints. (FIXME add detailed syntax) 27575 27576 `qTfV' 27577 `qTsV' 27578 These packets request data about trace state variables that are on 27579 the target. GDB sends `qTfV' to get the first vari of data, and 27580 multiple `qTsV' to get additional variables. Replies to these 27581 packets follow the syntax of the `QTDV' packets that define trace 27582 state variables. 27583 27584 `QTSave:FILENAME' 27585 This packet directs the target to save trace data to the file name 27586 FILENAME in the target's filesystem. FILENAME is encoded as a hex 27587 string; the interpretation of the file name (relative vs absolute, 27588 wild cards, etc) is up to the target. 27589 27590 `qTBuffer:OFFSET,LEN' 27591 Return up to LEN bytes of the current contents of trace buffer, 27592 starting at OFFSET. The trace buffer is treated as if it were a 27593 contiguous collection of traceframes, as per the trace file format. 27594 The reply consists as many hex-encoded bytes as the target can 27595 deliver in a packet; it is not an error to return fewer than were 27596 asked for. A reply consisting of just `l' indicates that no bytes 27597 are available. 27598 27599 27600 27601 File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol 27602 27603 D.7 Host I/O Packets 27604 ==================== 27605 27606 The "Host I/O" packets allow GDB to perform I/O operations on the far 27607 side of a remote link. For example, Host I/O is used to upload and 27608 download files to a remote target with its own filesystem. Host I/O 27609 uses the same constant values and data structure layout as the 27610 target-initiated File-I/O protocol. However, the Host I/O packets are 27611 structured differently. The target-initiated protocol relies on target 27612 memory to store parameters and buffers. Host I/O requests are 27613 initiated by GDB, and the target's memory is not involved. *Note 27614 File-I/O Remote Protocol Extension::, for more details on the 27615 target-initiated protocol. 27616 27617 The Host I/O request packets all encode a single operation along with 27618 its arguments. They have this format: 27619 27620 `vFile:OPERATION: PARAMETER...' 27621 OPERATION is the name of the particular request; the target should 27622 compare the entire packet name up to the second colon when checking 27623 for a supported operation. The format of PARAMETER depends on the 27624 operation. Numbers are always passed in hexadecimal. Negative 27625 numbers have an explicit minus sign (i.e. two's complement is not 27626 used). Strings (e.g. filenames) are encoded as a series of 27627 hexadecimal bytes. The last argument to a system call may be a 27628 buffer of escaped binary data (*note Binary Data::). 27629 27630 27631 The valid responses to Host I/O packets are: 27632 27633 `F RESULT [, ERRNO] [; ATTACHMENT]' 27634 RESULT is the integer value returned by this operation, usually 27635 non-negative for success and -1 for errors. If an error has 27636 occured, ERRNO will be included in the result. ERRNO will have a 27637 value defined by the File-I/O protocol (*note Errno Values::). For 27638 operations which return data, ATTACHMENT supplies the data as a 27639 binary buffer. Binary buffers in response packets are escaped in 27640 the normal way (*note Binary Data::). See the individual packet 27641 documentation for the interpretation of RESULT and ATTACHMENT. 27642 27643 `' 27644 An empty response indicates that this operation is not recognized. 27645 27646 27647 These are the supported Host I/O operations: 27648 27649 `vFile:open: PATHNAME, FLAGS, MODE' 27650 Open a file at PATHNAME and return a file descriptor for it, or 27651 return -1 if an error occurs. PATHNAME is a string, FLAGS is an 27652 integer indicating a mask of open flags (*note Open Flags::), and 27653 MODE is an integer indicating a mask of mode bits to use if the 27654 file is created (*note mode_t Values::). *Note open::, for 27655 details of the open flags and mode values. 27656 27657 `vFile:close: FD' 27658 Close the open file corresponding to FD and return 0, or -1 if an 27659 error occurs. 27660 27661 `vFile:pread: FD, COUNT, OFFSET' 27662 Read data from the open file corresponding to FD. Up to COUNT 27663 bytes will be read from the file, starting at OFFSET relative to 27664 the start of the file. The target may read fewer bytes; common 27665 reasons include packet size limits and an end-of-file condition. 27666 The number of bytes read is returned. Zero should only be 27667 returned for a successful read at the end of the file, or if COUNT 27668 was zero. 27669 27670 The data read should be returned as a binary attachment on success. 27671 If zero bytes were read, the response should include an empty 27672 binary attachment (i.e. a trailing semicolon). The return value 27673 is the number of target bytes read; the binary attachment may be 27674 longer if some characters were escaped. 27675 27676 `vFile:pwrite: FD, OFFSET, DATA' 27677 Write DATA (a binary buffer) to the open file corresponding to FD. 27678 Start the write at OFFSET from the start of the file. Unlike 27679 many `write' system calls, there is no separate COUNT argument; 27680 the length of DATA in the packet is used. `vFile:write' returns 27681 the number of bytes written, which may be shorter than the length 27682 of DATA, or -1 if an error occurred. 27683 27684 `vFile:unlink: PATHNAME' 27685 Delete the file at PATHNAME on the target. Return 0, or -1 if an 27686 error occurs. PATHNAME is a string. 27687 27688 27689 27690 File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol 27691 27692 D.8 Interrupts 27693 ============== 27694 27695 When a program on the remote target is running, GDB may attempt to 27696 interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by 27697 `g', control of which is specified via GDB's `interrupt-sequence'. 27698 27699 The precise meaning of `BREAK' is defined by the transport mechanism 27700 and may, in fact, be undefined. GDB does not currently define a 27701 `BREAK' mechanism for any of the network interfaces except for TCP, in 27702 which case GDB sends the `telnet' BREAK sequence. 27703 27704 `Ctrl-C', on the other hand, is defined and implemented for all 27705 transport mechanisms. It is represented by sending the single byte 27706 `0x03' without any of the usual packet overhead described in the 27707 Overview section (*note Overview::). When a `0x03' byte is transmitted 27708 as part of a packet, it is considered to be packet data and does _not_ 27709 represent an interrupt. E.g., an `X' packet (*note X packet::), used 27710 for binary downloads, may include an unescaped `0x03' as part of its 27711 packet. 27712 27713 `BREAK' followed by `g' is also known as Magic SysRq g. When Linux 27714 kernel receives this sequence from serial port, it stops execution and 27715 connects to gdb. 27716 27717 Stubs are not required to recognize these interrupt mechanisms and 27718 the precise meaning associated with receipt of the interrupt is 27719 implementation defined. If the target supports debugging of multiple 27720 threads and/or processes, it should attempt to interrupt all 27721 currently-executing threads and processes. If the stub is successful 27722 at interrupting the running program, it should send one of the stop 27723 reply packets (*note Stop Reply Packets::) to GDB as a result of 27724 successfully stopping the program in all-stop mode, and a stop reply 27725 for each stopped thread in non-stop mode. Interrupts received while the 27726 program is stopped are discarded. 27727 27728 27729 File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol 27730 27731 D.9 Notification Packets 27732 ======================== 27733 27734 The GDB remote serial protocol includes "notifications", packets that 27735 require no acknowledgment. Both the GDB and the stub may send 27736 notifications (although the only notifications defined at present are 27737 sent by the stub). Notifications carry information without incurring 27738 the round-trip latency of an acknowledgment, and so are useful for 27739 low-impact communications where occasional packet loss is not a problem. 27740 27741 A notification packet has the form `% DATA # CHECKSUM', where DATA 27742 is the content of the notification, and CHECKSUM is a checksum of DATA, 27743 computed and formatted as for ordinary GDB packets. A notification's 27744 DATA never contains `$', `%' or `#' characters. Upon receiving a 27745 notification, the recipient sends no `+' or `-' to acknowledge the 27746 notification's receipt or to report its corruption. 27747 27748 Every notification's DATA begins with a name, which contains no 27749 colon characters, followed by a colon character. 27750 27751 Recipients should silently ignore corrupted notifications and 27752 notifications they do not understand. Recipients should restart 27753 timeout periods on receipt of a well-formed notification, whether or 27754 not they understand it. 27755 27756 Senders should only send the notifications described here when this 27757 protocol description specifies that they are permitted. In the future, 27758 we may extend the protocol to permit existing notifications in new 27759 contexts; this rule helps older senders avoid confusing newer 27760 recipients. 27761 27762 (Older versions of GDB ignore bytes received until they see the `$' 27763 byte that begins an ordinary packet, so new stubs may transmit 27764 notifications without fear of confusing older clients. There are no 27765 notifications defined for GDB to send at the moment, but we assume that 27766 most older stubs would ignore them, as well.) 27767 27768 The following notification packets from the stub to GDB are defined: 27769 27770 `Stop: REPLY' 27771 Report an asynchronous stop event in non-stop mode. The REPLY has 27772 the form of a stop reply, as described in *Note Stop Reply 27773 Packets::. Refer to *Note Remote Non-Stop::, for information on 27774 how these notifications are acknowledged by GDB. 27775 27776 27777 File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol 27778 27779 D.10 Remote Protocol Support for Non-Stop Mode 27780 ============================================== 27781 27782 GDB's remote protocol supports non-stop debugging of multi-threaded 27783 programs, as described in *Note Non-Stop Mode::. If the stub supports 27784 non-stop mode, it should report that to GDB by including `QNonStop+' in 27785 its `qSupported' response (*note qSupported::). 27786 27787 GDB typically sends a `QNonStop' packet only when establishing a new 27788 connection with the stub. Entering non-stop mode does not alter the 27789 state of any currently-running threads, but targets must stop all 27790 threads in any already-attached processes when entering all-stop mode. 27791 GDB uses the `?' packet as necessary to probe the target state after a 27792 mode change. 27793 27794 In non-stop mode, when an attached process encounters an event that 27795 would otherwise be reported with a stop reply, it uses the asynchronous 27796 notification mechanism (*note Notification Packets::) to inform GDB. 27797 In contrast to all-stop mode, where all threads in all processes are 27798 stopped when a stop reply is sent, in non-stop mode only the thread 27799 reporting the stop event is stopped. That is, when reporting a `S' or 27800 `T' response to indicate completion of a step operation, hitting a 27801 breakpoint, or a fault, only the affected thread is stopped; any other 27802 still-running threads continue to run. When reporting a `W' or `X' 27803 response, all running threads belonging to other attached processes 27804 continue to run. 27805 27806 Only one stop reply notification at a time may be pending; if 27807 additional stop events occur before GDB has acknowledged the previous 27808 notification, they must be queued by the stub for later synchronous 27809 transmission in response to `vStopped' packets from GDB. Because the 27810 notification mechanism is unreliable, the stub is permitted to resend a 27811 stop reply notification if it believes GDB may not have received it. 27812 GDB ignores additional stop reply notifications received before it has 27813 finished processing a previous notification and the stub has completed 27814 sending any queued stop events. 27815 27816 Otherwise, GDB must be prepared to receive a stop reply notification 27817 at any time. Specifically, they may appear when GDB is not otherwise 27818 reading input from the stub, or when GDB is expecting to read a normal 27819 synchronous response or a `+'/`-' acknowledgment to a packet it has 27820 sent. Notification packets are distinct from any other communication 27821 from the stub so there is no ambiguity. 27822 27823 After receiving a stop reply notification, GDB shall acknowledge it 27824 by sending a `vStopped' packet (*note vStopped packet::) as a regular, 27825 synchronous request to the stub. Such acknowledgment is not required 27826 to happen immediately, as GDB is permitted to send other, unrelated 27827 packets to the stub first, which the stub should process normally. 27828 27829 Upon receiving a `vStopped' packet, if the stub has other queued 27830 stop events to report to GDB, it shall respond by sending a normal stop 27831 reply response. GDB shall then send another `vStopped' packet to 27832 solicit further responses; again, it is permitted to send other, 27833 unrelated packets as well which the stub should process normally. 27834 27835 If the stub receives a `vStopped' packet and there are no additional 27836 stop events to report, the stub shall return an `OK' response. At this 27837 point, if further stop events occur, the stub shall send a new stop 27838 reply notification, GDB shall accept the notification, and the process 27839 shall be repeated. 27840 27841 In non-stop mode, the target shall respond to the `?' packet as 27842 follows. First, any incomplete stop reply notification/`vStopped' 27843 sequence in progress is abandoned. The target must begin a new 27844 sequence reporting stop events for all stopped threads, whether or not 27845 it has previously reported those events to GDB. The first stop reply 27846 is sent as a synchronous reply to the `?' packet, and subsequent stop 27847 replies are sent as responses to `vStopped' packets using the mechanism 27848 described above. The target must not send asynchronous stop reply 27849 notifications until the sequence is complete. If all threads are 27850 running when the target receives the `?' packet, or if the target is 27851 not attached to any process, it shall respond `OK'. 27852 27853 27854 File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol 27855 27856 D.11 Packet Acknowledgment 27857 ========================== 27858 27859 By default, when either the host or the target machine receives a 27860 packet, the first response expected is an acknowledgment: either `+' 27861 (to indicate the package was received correctly) or `-' (to request 27862 retransmission). This mechanism allows the GDB remote protocol to 27863 operate over unreliable transport mechanisms, such as a serial line. 27864 27865 In cases where the transport mechanism is itself reliable (such as a 27866 pipe or TCP connection), the `+'/`-' acknowledgments are redundant. It 27867 may be desirable to disable them in that case to reduce communication 27868 overhead, or for other reasons. This can be accomplished by means of 27869 the `QStartNoAckMode' packet; *note QStartNoAckMode::. 27870 27871 When in no-acknowledgment mode, neither the stub nor GDB shall send 27872 or expect `+'/`-' protocol acknowledgments. The packet and response 27873 format still includes the normal checksum, as described in *Note 27874 Overview::, but the checksum may be ignored by the receiver. 27875 27876 If the stub supports `QStartNoAckMode' and prefers to operate in 27877 no-acknowledgment mode, it should report that to GDB by including 27878 `QStartNoAckMode+' in its response to `qSupported'; *note qSupported::. 27879 If GDB also supports `QStartNoAckMode' and it has not been disabled via 27880 the `set remote noack-packet off' command (*note Remote 27881 Configuration::), GDB may then send a `QStartNoAckMode' packet to the 27882 stub. Only then may the stub actually turn off packet acknowledgments. 27883 GDB sends a final `+' acknowledgment of the stub's `OK' response, which 27884 can be safely ignored by the stub. 27885 27886 Note that `set remote noack-packet' command only affects negotiation 27887 between GDB and the stub when subsequent connections are made; it does 27888 not affect the protocol acknowledgment state for any current connection. 27889 Since `+'/`-' acknowledgments are enabled by default when a new 27890 connection is established, there is also no protocol request to 27891 re-enable the acknowledgments for the current connection, once disabled. 27892 27893 27894 File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol 27895 27896 D.12 Examples 27897 ============= 27898 27899 Example sequence of a target being re-started. Notice how the restart 27900 does not get any direct output: 27901 27902 -> `R00' 27903 <- `+' 27904 _target restarts_ 27905 -> `?' 27906 <- `+' 27907 <- `T001:1234123412341234' 27908 -> `+' 27909 27910 Example sequence of a target being stepped by a single instruction: 27911 27912 -> `G1445...' 27913 <- `+' 27914 -> `s' 27915 <- `+' 27916 _time passes_ 27917 <- `T001:1234123412341234' 27918 -> `+' 27919 -> `g' 27920 <- `+' 27921 <- `1455...' 27922 -> `+' 27923 27924 27925 File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol 27926 27927 D.13 File-I/O Remote Protocol Extension 27928 ======================================= 27929 27930 * Menu: 27931 27932 * File-I/O Overview:: 27933 * Protocol Basics:: 27934 * The F Request Packet:: 27935 * The F Reply Packet:: 27936 * The Ctrl-C Message:: 27937 * Console I/O:: 27938 * List of Supported Calls:: 27939 * Protocol-specific Representation of Datatypes:: 27940 * Constants:: 27941 * File-I/O Examples:: 27942 27943 27944 File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension 27945 27946 D.13.1 File-I/O Overview 27947 ------------------------ 27948 27949 The "File I/O remote protocol extension" (short: File-I/O) allows the 27950 target to use the host's file system and console I/O to perform various 27951 system calls. System calls on the target system are translated into a 27952 remote protocol packet to the host system, which then performs the 27953 needed actions and returns a response packet to the target system. 27954 This simulates file system operations even on targets that lack file 27955 systems. 27956 27957 The protocol is defined to be independent of both the host and 27958 target systems. It uses its own internal representation of datatypes 27959 and values. Both GDB and the target's GDB stub are responsible for 27960 translating the system-dependent value representations into the internal 27961 protocol representations when data is transmitted. 27962 27963 The communication is synchronous. A system call is possible only 27964 when GDB is waiting for a response from the `C', `c', `S' or `s' 27965 packets. While GDB handles the request for a system call, the target 27966 is stopped to allow deterministic access to the target's memory. 27967 Therefore File-I/O is not interruptible by target signals. On the 27968 other hand, it is possible to interrupt File-I/O by a user interrupt 27969 (`Ctrl-C') within GDB. 27970 27971 The target's request to perform a host system call does not finish 27972 the latest `C', `c', `S' or `s' action. That means, after finishing 27973 the system call, the target returns to continuing the previous activity 27974 (continue, step). No additional continue or step request from GDB is 27975 required. 27976 27977 (gdb) continue 27978 <- target requests 'system call X' 27979 target is stopped, GDB executes system call 27980 -> GDB returns result 27981 ... target continues, GDB returns to wait for the target 27982 <- target hits breakpoint and sends a Txx packet 27983 27984 The protocol only supports I/O on the console and to regular files on 27985 the host file system. Character or block special devices, pipes, named 27986 pipes, sockets or any other communication method on the host system are 27987 not supported by this protocol. 27988 27989 File I/O is not supported in non-stop mode. 27990 27991 27992 File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension 27993 27994 D.13.2 Protocol Basics 27995 ---------------------- 27996 27997 The File-I/O protocol uses the `F' packet as the request as well as 27998 reply packet. Since a File-I/O system call can only occur when GDB is 27999 waiting for a response from the continuing or stepping target, the 28000 File-I/O request is a reply that GDB has to expect as a result of a 28001 previous `C', `c', `S' or `s' packet. This `F' packet contains all 28002 information needed to allow GDB to call the appropriate host system 28003 call: 28004 28005 * A unique identifier for the requested system call. 28006 28007 * All parameters to the system call. Pointers are given as addresses 28008 in the target memory address space. Pointers to strings are given 28009 as pointer/length pair. Numerical values are given as they are. 28010 Numerical control flags are given in a protocol-specific 28011 representation. 28012 28013 28014 At this point, GDB has to perform the following actions. 28015 28016 * If the parameters include pointer values to data needed as input 28017 to a system call, GDB requests this data from the target with a 28018 standard `m' packet request. This additional communication has to 28019 be expected by the target implementation and is handled as any 28020 other `m' packet. 28021 28022 * GDB translates all value from protocol representation to host 28023 representation as needed. Datatypes are coerced into the host 28024 types. 28025 28026 * GDB calls the system call. 28027 28028 * It then coerces datatypes back to protocol representation. 28029 28030 * If the system call is expected to return data in buffer space 28031 specified by pointer parameters to the call, the data is 28032 transmitted to the target using a `M' or `X' packet. This packet 28033 has to be expected by the target implementation and is handled as 28034 any other `M' or `X' packet. 28035 28036 28037 Eventually GDB replies with another `F' packet which contains all 28038 necessary information for the target to continue. This at least 28039 contains 28040 28041 * Return value. 28042 28043 * `errno', if has been changed by the system call. 28044 28045 * "Ctrl-C" flag. 28046 28047 28048 After having done the needed type and value coercion, the target 28049 continues the latest continue or step action. 28050 28051 28052 File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension 28053 28054 D.13.3 The `F' Request Packet 28055 ----------------------------- 28056 28057 The `F' request packet has the following format: 28058 28059 `FCALL-ID,PARAMETER...' 28060 CALL-ID is the identifier to indicate the host system call to be 28061 called. This is just the name of the function. 28062 28063 PARAMETER... are the parameters to the system call. Parameters 28064 are hexadecimal integer values, either the actual values in case 28065 of scalar datatypes, pointers to target buffer space in case of 28066 compound datatypes and unspecified memory areas, or pointer/length 28067 pairs in case of string parameters. These are appended to the 28068 CALL-ID as a comma-delimited list. All values are transmitted in 28069 ASCII string representation, pointer/length pairs separated by a 28070 slash. 28071 28072 28073 28074 File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension 28075 28076 D.13.4 The `F' Reply Packet 28077 --------------------------- 28078 28079 The `F' reply packet has the following format: 28080 28081 `FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT' 28082 RETCODE is the return code of the system call as hexadecimal value. 28083 28084 ERRNO is the `errno' set by the call, in protocol-specific 28085 representation. This parameter can be omitted if the call was 28086 successful. 28087 28088 CTRL-C FLAG is only sent if the user requested a break. In this 28089 case, ERRNO must be sent as well, even if the call was successful. 28090 The CTRL-C FLAG itself consists of the character `C': 28091 28092 F0,0,C 28093 28094 or, if the call was interrupted before the host call has been 28095 performed: 28096 28097 F-1,4,C 28098 28099 assuming 4 is the protocol-specific representation of `EINTR'. 28100 28101 28102 28103 File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension 28104 28105 D.13.5 The `Ctrl-C' Message 28106 --------------------------- 28107 28108 If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply 28109 Packet::), the target should behave as if it had gotten a break 28110 message. The meaning for the target is "system call interrupted by 28111 `SIGINT'". Consequentially, the target should actually stop (as with a 28112 break message) and return to GDB with a `T02' packet. 28113 28114 It's important for the target to know in which state the system call 28115 was interrupted. There are two possible cases: 28116 28117 * The system call hasn't been performed on the host yet. 28118 28119 * The system call on the host has been finished. 28120 28121 28122 These two states can be distinguished by the target by the value of 28123 the returned `errno'. If it's the protocol representation of `EINTR', 28124 the system call hasn't been performed. This is equivalent to the 28125 `EINTR' handling on POSIX systems. In any other case, the target may 28126 presume that the system call has been finished -- successfully or not 28127 -- and should behave as if the break message arrived right after the 28128 system call. 28129 28130 GDB must behave reliably. If the system call has not been called 28131 yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno' 28132 in the packet. If the system call on the host has been finished before 28133 the user requests a break, the full action must be finished by GDB. 28134 This requires sending `M' or `X' packets as necessary. The `F' packet 28135 may only be sent when either nothing has happened or the full action 28136 has been completed. 28137 28138 28139 File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension 28140 28141 D.13.6 Console I/O 28142 ------------------ 28143 28144 By default and if not explicitly closed by the target system, the file 28145 descriptors 0, 1 and 2 are connected to the GDB console. Output on the 28146 GDB console is handled as any other file output operation (`write(1, 28147 ...)' or `write(2, ...)'). Console input is handled by GDB so that 28148 after the target read request from file descriptor 0 all following 28149 typing is buffered until either one of the following conditions is met: 28150 28151 * The user types `Ctrl-c'. The behaviour is as explained above, and 28152 the `read' system call is treated as finished. 28153 28154 * The user presses <RET>. This is treated as end of input with a 28155 trailing newline. 28156 28157 * The user types `Ctrl-d'. This is treated as end of input. No 28158 trailing character (neither newline nor `Ctrl-D') is appended to 28159 the input. 28160 28161 28162 If the user has typed more characters than fit in the buffer given to 28163 the `read' call, the trailing characters are buffered in GDB until 28164 either another `read(0, ...)' is requested by the target, or debugging 28165 is stopped at the user's request. 28166 28167 28168 File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension 28169 28170 D.13.7 List of Supported Calls 28171 ------------------------------ 28172 28173 * Menu: 28174 28175 * open:: 28176 * close:: 28177 * read:: 28178 * write:: 28179 * lseek:: 28180 * rename:: 28181 * unlink:: 28182 * stat/fstat:: 28183 * gettimeofday:: 28184 * isatty:: 28185 * system:: 28186 28187 28188 File: gdb.info, Node: open, Next: close, Up: List of Supported Calls 28189 28190 open 28191 .... 28192 28193 Synopsis: 28194 int open(const char *pathname, int flags); 28195 int open(const char *pathname, int flags, mode_t mode); 28196 28197 Request: 28198 `Fopen,PATHPTR/LEN,FLAGS,MODE' 28199 28200 FLAGS is the bitwise `OR' of the following values: 28201 28202 `O_CREAT' 28203 If the file does not exist it will be created. The host 28204 rules apply as far as file ownership and time stamps are 28205 concerned. 28206 28207 `O_EXCL' 28208 When used with `O_CREAT', if the file already exists it is an 28209 error and open() fails. 28210 28211 `O_TRUNC' 28212 If the file already exists and the open mode allows writing 28213 (`O_RDWR' or `O_WRONLY' is given) it will be truncated to 28214 zero length. 28215 28216 `O_APPEND' 28217 The file is opened in append mode. 28218 28219 `O_RDONLY' 28220 The file is opened for reading only. 28221 28222 `O_WRONLY' 28223 The file is opened for writing only. 28224 28225 `O_RDWR' 28226 The file is opened for reading and writing. 28227 28228 Other bits are silently ignored. 28229 28230 MODE is the bitwise `OR' of the following values: 28231 28232 `S_IRUSR' 28233 User has read permission. 28234 28235 `S_IWUSR' 28236 User has write permission. 28237 28238 `S_IRGRP' 28239 Group has read permission. 28240 28241 `S_IWGRP' 28242 Group has write permission. 28243 28244 `S_IROTH' 28245 Others have read permission. 28246 28247 `S_IWOTH' 28248 Others have write permission. 28249 28250 Other bits are silently ignored. 28251 28252 Return value: 28253 `open' returns the new file descriptor or -1 if an error occurred. 28254 28255 Errors: 28256 28257 `EEXIST' 28258 PATHNAME already exists and `O_CREAT' and `O_EXCL' were used. 28259 28260 `EISDIR' 28261 PATHNAME refers to a directory. 28262 28263 `EACCES' 28264 The requested access is not allowed. 28265 28266 `ENAMETOOLONG' 28267 PATHNAME was too long. 28268 28269 `ENOENT' 28270 A directory component in PATHNAME does not exist. 28271 28272 `ENODEV' 28273 PATHNAME refers to a device, pipe, named pipe or socket. 28274 28275 `EROFS' 28276 PATHNAME refers to a file on a read-only filesystem and write 28277 access was requested. 28278 28279 `EFAULT' 28280 PATHNAME is an invalid pointer value. 28281 28282 `ENOSPC' 28283 No space on device to create the file. 28284 28285 `EMFILE' 28286 The process already has the maximum number of files open. 28287 28288 `ENFILE' 28289 The limit on the total number of files open on the system has 28290 been reached. 28291 28292 `EINTR' 28293 The call was interrupted by the user. 28294 28295 28296 28297 File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls 28298 28299 close 28300 ..... 28301 28302 Synopsis: 28303 int close(int fd); 28304 28305 Request: 28306 `Fclose,FD' 28307 28308 Return value: 28309 `close' returns zero on success, or -1 if an error occurred. 28310 28311 Errors: 28312 28313 `EBADF' 28314 FD isn't a valid open file descriptor. 28315 28316 `EINTR' 28317 The call was interrupted by the user. 28318 28319 28320 28321 File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls 28322 28323 read 28324 .... 28325 28326 Synopsis: 28327 int read(int fd, void *buf, unsigned int count); 28328 28329 Request: 28330 `Fread,FD,BUFPTR,COUNT' 28331 28332 Return value: 28333 On success, the number of bytes read is returned. Zero indicates 28334 end of file. If count is zero, read returns zero as well. On 28335 error, -1 is returned. 28336 28337 Errors: 28338 28339 `EBADF' 28340 FD is not a valid file descriptor or is not open for reading. 28341 28342 `EFAULT' 28343 BUFPTR is an invalid pointer value. 28344 28345 `EINTR' 28346 The call was interrupted by the user. 28347 28348 28349 28350 File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls 28351 28352 write 28353 ..... 28354 28355 Synopsis: 28356 int write(int fd, const void *buf, unsigned int count); 28357 28358 Request: 28359 `Fwrite,FD,BUFPTR,COUNT' 28360 28361 Return value: 28362 On success, the number of bytes written are returned. Zero 28363 indicates nothing was written. On error, -1 is returned. 28364 28365 Errors: 28366 28367 `EBADF' 28368 FD is not a valid file descriptor or is not open for writing. 28369 28370 `EFAULT' 28371 BUFPTR is an invalid pointer value. 28372 28373 `EFBIG' 28374 An attempt was made to write a file that exceeds the 28375 host-specific maximum file size allowed. 28376 28377 `ENOSPC' 28378 No space on device to write the data. 28379 28380 `EINTR' 28381 The call was interrupted by the user. 28382 28383 28384 28385 File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls 28386 28387 lseek 28388 ..... 28389 28390 Synopsis: 28391 long lseek (int fd, long offset, int flag); 28392 28393 Request: 28394 `Flseek,FD,OFFSET,FLAG' 28395 28396 FLAG is one of: 28397 28398 `SEEK_SET' 28399 The offset is set to OFFSET bytes. 28400 28401 `SEEK_CUR' 28402 The offset is set to its current location plus OFFSET bytes. 28403 28404 `SEEK_END' 28405 The offset is set to the size of the file plus OFFSET bytes. 28406 28407 Return value: 28408 On success, the resulting unsigned offset in bytes from the 28409 beginning of the file is returned. Otherwise, a value of -1 is 28410 returned. 28411 28412 Errors: 28413 28414 `EBADF' 28415 FD is not a valid open file descriptor. 28416 28417 `ESPIPE' 28418 FD is associated with the GDB console. 28419 28420 `EINVAL' 28421 FLAG is not a proper value. 28422 28423 `EINTR' 28424 The call was interrupted by the user. 28425 28426 28427 28428 File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls 28429 28430 rename 28431 ...... 28432 28433 Synopsis: 28434 int rename(const char *oldpath, const char *newpath); 28435 28436 Request: 28437 `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN' 28438 28439 Return value: 28440 On success, zero is returned. On error, -1 is returned. 28441 28442 Errors: 28443 28444 `EISDIR' 28445 NEWPATH is an existing directory, but OLDPATH is not a 28446 directory. 28447 28448 `EEXIST' 28449 NEWPATH is a non-empty directory. 28450 28451 `EBUSY' 28452 OLDPATH or NEWPATH is a directory that is in use by some 28453 process. 28454 28455 `EINVAL' 28456 An attempt was made to make a directory a subdirectory of 28457 itself. 28458 28459 `ENOTDIR' 28460 A component used as a directory in OLDPATH or new path is 28461 not a directory. Or OLDPATH is a directory and NEWPATH 28462 exists but is not a directory. 28463 28464 `EFAULT' 28465 OLDPATHPTR or NEWPATHPTR are invalid pointer values. 28466 28467 `EACCES' 28468 No access to the file or the path of the file. 28469 28470 `ENAMETOOLONG' 28471 OLDPATH or NEWPATH was too long. 28472 28473 `ENOENT' 28474 A directory component in OLDPATH or NEWPATH does not exist. 28475 28476 `EROFS' 28477 The file is on a read-only filesystem. 28478 28479 `ENOSPC' 28480 The device containing the file has no room for the new 28481 directory entry. 28482 28483 `EINTR' 28484 The call was interrupted by the user. 28485 28486 28487 28488 File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls 28489 28490 unlink 28491 ...... 28492 28493 Synopsis: 28494 int unlink(const char *pathname); 28495 28496 Request: 28497 `Funlink,PATHNAMEPTR/LEN' 28498 28499 Return value: 28500 On success, zero is returned. On error, -1 is returned. 28501 28502 Errors: 28503 28504 `EACCES' 28505 No access to the file or the path of the file. 28506 28507 `EPERM' 28508 The system does not allow unlinking of directories. 28509 28510 `EBUSY' 28511 The file PATHNAME cannot be unlinked because it's being used 28512 by another process. 28513 28514 `EFAULT' 28515 PATHNAMEPTR is an invalid pointer value. 28516 28517 `ENAMETOOLONG' 28518 PATHNAME was too long. 28519 28520 `ENOENT' 28521 A directory component in PATHNAME does not exist. 28522 28523 `ENOTDIR' 28524 A component of the path is not a directory. 28525 28526 `EROFS' 28527 The file is on a read-only filesystem. 28528 28529 `EINTR' 28530 The call was interrupted by the user. 28531 28532 28533 28534 File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls 28535 28536 stat/fstat 28537 .......... 28538 28539 Synopsis: 28540 int stat(const char *pathname, struct stat *buf); 28541 int fstat(int fd, struct stat *buf); 28542 28543 Request: 28544 `Fstat,PATHNAMEPTR/LEN,BUFPTR' 28545 `Ffstat,FD,BUFPTR' 28546 28547 Return value: 28548 On success, zero is returned. On error, -1 is returned. 28549 28550 Errors: 28551 28552 `EBADF' 28553 FD is not a valid open file. 28554 28555 `ENOENT' 28556 A directory component in PATHNAME does not exist or the path 28557 is an empty string. 28558 28559 `ENOTDIR' 28560 A component of the path is not a directory. 28561 28562 `EFAULT' 28563 PATHNAMEPTR is an invalid pointer value. 28564 28565 `EACCES' 28566 No access to the file or the path of the file. 28567 28568 `ENAMETOOLONG' 28569 PATHNAME was too long. 28570 28571 `EINTR' 28572 The call was interrupted by the user. 28573 28574 28575 28576 File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls 28577 28578 gettimeofday 28579 ............ 28580 28581 Synopsis: 28582 int gettimeofday(struct timeval *tv, void *tz); 28583 28584 Request: 28585 `Fgettimeofday,TVPTR,TZPTR' 28586 28587 Return value: 28588 On success, 0 is returned, -1 otherwise. 28589 28590 Errors: 28591 28592 `EINVAL' 28593 TZ is a non-NULL pointer. 28594 28595 `EFAULT' 28596 TVPTR and/or TZPTR is an invalid pointer value. 28597 28598 28599 28600 File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls 28601 28602 isatty 28603 ...... 28604 28605 Synopsis: 28606 int isatty(int fd); 28607 28608 Request: 28609 `Fisatty,FD' 28610 28611 Return value: 28612 Returns 1 if FD refers to the GDB console, 0 otherwise. 28613 28614 Errors: 28615 28616 `EINTR' 28617 The call was interrupted by the user. 28618 28619 28620 Note that the `isatty' call is treated as a special case: it returns 28621 1 to the target if the file descriptor is attached to the GDB console, 28622 0 otherwise. Implementing through system calls would require 28623 implementing `ioctl' and would be more complex than needed. 28624 28625 28626 File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls 28627 28628 system 28629 ...... 28630 28631 Synopsis: 28632 int system(const char *command); 28633 28634 Request: 28635 `Fsystem,COMMANDPTR/LEN' 28636 28637 Return value: 28638 If LEN is zero, the return value indicates whether a shell is 28639 available. A zero return value indicates a shell is not available. 28640 For non-zero LEN, the value returned is -1 on error and the return 28641 status of the command otherwise. Only the exit status of the 28642 command is returned, which is extracted from the host's `system' 28643 return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh' 28644 could not be executed, 127 is returned. 28645 28646 Errors: 28647 28648 `EINTR' 28649 The call was interrupted by the user. 28650 28651 28652 GDB takes over the full task of calling the necessary host calls to 28653 perform the `system' call. The return value of `system' on the host is 28654 simplified before it's returned to the target. Any termination signal 28655 information from the child process is discarded, and the return value 28656 consists entirely of the exit status of the called command. 28657 28658 Due to security concerns, the `system' call is by default refused by 28659 GDB. The user has to allow this call explicitly with the `set remote 28660 system-call-allowed 1' command. 28661 28662 `set remote system-call-allowed' 28663 Control whether to allow the `system' calls in the File I/O 28664 protocol for the remote target. The default is zero (disabled). 28665 28666 `show remote system-call-allowed' 28667 Show whether the `system' calls are allowed in the File I/O 28668 protocol. 28669 28670 28671 File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension 28672 28673 D.13.8 Protocol-specific Representation of Datatypes 28674 ---------------------------------------------------- 28675 28676 * Menu: 28677 28678 * Integral Datatypes:: 28679 * Pointer Values:: 28680 * Memory Transfer:: 28681 * struct stat:: 28682 * struct timeval:: 28683 28684 28685 File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes 28686 28687 Integral Datatypes 28688 .................. 28689 28690 The integral datatypes used in the system calls are `int', `unsigned 28691 int', `long', `unsigned long', `mode_t', and `time_t'. 28692 28693 `int', `unsigned int', `mode_t' and `time_t' are implemented as 32 28694 bit values in this protocol. 28695 28696 `long' and `unsigned long' are implemented as 64 bit types. 28697 28698 *Note Limits::, for corresponding MIN and MAX values (similar to 28699 those in `limits.h') to allow range checking on host and target. 28700 28701 `time_t' datatypes are defined as seconds since the Epoch. 28702 28703 All integral datatypes transferred as part of a memory read or write 28704 of a structured datatype e.g. a `struct stat' have to be given in big 28705 endian byte order. 28706 28707 28708 File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes 28709 28710 Pointer Values 28711 .............. 28712 28713 Pointers to target data are transmitted as they are. An exception is 28714 made for pointers to buffers for which the length isn't transmitted as 28715 part of the function call, namely strings. Strings are transmitted as 28716 a pointer/length pair, both as hex values, e.g. 28717 28718 `1aaf/12' 28719 28720 which is a pointer to data of length 18 bytes at position 0x1aaf. The 28721 length is defined as the full string length in bytes, including the 28722 trailing null byte. For example, the string `"hello world"' at address 28723 0x123456 is transmitted as 28724 28725 `123456/d' 28726 28727 28728 File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes 28729 28730 Memory Transfer 28731 ............... 28732 28733 Structured data which is transferred using a memory read or write (for 28734 example, a `struct stat') is expected to be in a protocol-specific 28735 format with all scalar multibyte datatypes being big endian. 28736 Translation to this representation needs to be done both by the target 28737 before the `F' packet is sent, and by GDB before it transfers memory to 28738 the target. Transferred pointers to structured data should point to 28739 the already-coerced data at any time. 28740 28741 28742 File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes 28743 28744 struct stat 28745 ........... 28746 28747 The buffer of type `struct stat' used by the target and GDB is defined 28748 as follows: 28749 28750 struct stat { 28751 unsigned int st_dev; /* device */ 28752 unsigned int st_ino; /* inode */ 28753 mode_t st_mode; /* protection */ 28754 unsigned int st_nlink; /* number of hard links */ 28755 unsigned int st_uid; /* user ID of owner */ 28756 unsigned int st_gid; /* group ID of owner */ 28757 unsigned int st_rdev; /* device type (if inode device) */ 28758 unsigned long st_size; /* total size, in bytes */ 28759 unsigned long st_blksize; /* blocksize for filesystem I/O */ 28760 unsigned long st_blocks; /* number of blocks allocated */ 28761 time_t st_atime; /* time of last access */ 28762 time_t st_mtime; /* time of last modification */ 28763 time_t st_ctime; /* time of last change */ 28764 }; 28765 28766 The integral datatypes conform to the definitions given in the 28767 appropriate section (see *Note Integral Datatypes::, for details) so 28768 this structure is of size 64 bytes. 28769 28770 The values of several fields have a restricted meaning and/or range 28771 of values. 28772 28773 `st_dev' 28774 A value of 0 represents a file, 1 the console. 28775 28776 `st_ino' 28777 No valid meaning for the target. Transmitted unchanged. 28778 28779 `st_mode' 28780 Valid mode bits are described in *Note Constants::. Any other 28781 bits have currently no meaning for the target. 28782 28783 `st_uid' 28784 `st_gid' 28785 `st_rdev' 28786 No valid meaning for the target. Transmitted unchanged. 28787 28788 `st_atime' 28789 `st_mtime' 28790 `st_ctime' 28791 These values have a host and file system dependent accuracy. 28792 Especially on Windows hosts, the file system may not support exact 28793 timing values. 28794 28795 The target gets a `struct stat' of the above representation and is 28796 responsible for coercing it to the target representation before 28797 continuing. 28798 28799 Note that due to size differences between the host, target, and 28800 protocol representations of `struct stat' members, these members could 28801 eventually get truncated on the target. 28802 28803 28804 File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes 28805 28806 struct timeval 28807 .............. 28808 28809 The buffer of type `struct timeval' used by the File-I/O protocol is 28810 defined as follows: 28811 28812 struct timeval { 28813 time_t tv_sec; /* second */ 28814 long tv_usec; /* microsecond */ 28815 }; 28816 28817 The integral datatypes conform to the definitions given in the 28818 appropriate section (see *Note Integral Datatypes::, for details) so 28819 this structure is of size 8 bytes. 28820 28821 28822 File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension 28823 28824 D.13.9 Constants 28825 ---------------- 28826 28827 The following values are used for the constants inside of the protocol. 28828 GDB and target are responsible for translating these values before and 28829 after the call as needed. 28830 28831 * Menu: 28832 28833 * Open Flags:: 28834 * mode_t Values:: 28835 * Errno Values:: 28836 * Lseek Flags:: 28837 * Limits:: 28838 28839 28840 File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants 28841 28842 Open Flags 28843 .......... 28844 28845 All values are given in hexadecimal representation. 28846 28847 O_RDONLY 0x0 28848 O_WRONLY 0x1 28849 O_RDWR 0x2 28850 O_APPEND 0x8 28851 O_CREAT 0x200 28852 O_TRUNC 0x400 28853 O_EXCL 0x800 28854 28855 28856 File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants 28857 28858 mode_t Values 28859 ............. 28860 28861 All values are given in octal representation. 28862 28863 S_IFREG 0100000 28864 S_IFDIR 040000 28865 S_IRUSR 0400 28866 S_IWUSR 0200 28867 S_IXUSR 0100 28868 S_IRGRP 040 28869 S_IWGRP 020 28870 S_IXGRP 010 28871 S_IROTH 04 28872 S_IWOTH 02 28873 S_IXOTH 01 28874 28875 28876 File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants 28877 28878 Errno Values 28879 ............ 28880 28881 All values are given in decimal representation. 28882 28883 EPERM 1 28884 ENOENT 2 28885 EINTR 4 28886 EBADF 9 28887 EACCES 13 28888 EFAULT 14 28889 EBUSY 16 28890 EEXIST 17 28891 ENODEV 19 28892 ENOTDIR 20 28893 EISDIR 21 28894 EINVAL 22 28895 ENFILE 23 28896 EMFILE 24 28897 EFBIG 27 28898 ENOSPC 28 28899 ESPIPE 29 28900 EROFS 30 28901 ENAMETOOLONG 91 28902 EUNKNOWN 9999 28903 28904 `EUNKNOWN' is used as a fallback error value if a host system returns 28905 any error value not in the list of supported error numbers. 28906 28907 28908 File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants 28909 28910 Lseek Flags 28911 ........... 28912 28913 SEEK_SET 0 28914 SEEK_CUR 1 28915 SEEK_END 2 28916 28917 28918 File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants 28919 28920 Limits 28921 ...... 28922 28923 All values are given in decimal representation. 28924 28925 INT_MIN -2147483648 28926 INT_MAX 2147483647 28927 UINT_MAX 4294967295 28928 LONG_MIN -9223372036854775808 28929 LONG_MAX 9223372036854775807 28930 ULONG_MAX 18446744073709551615 28931 28932 28933 File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension 28934 28935 D.13.10 File-I/O Examples 28936 ------------------------- 28937 28938 Example sequence of a write call, file descriptor 3, buffer is at target 28939 address 0x1234, 6 bytes should be written: 28940 28941 <- `Fwrite,3,1234,6' 28942 _request memory read from target_ 28943 -> `m1234,6' 28944 <- XXXXXX 28945 _return "6 bytes written"_ 28946 -> `F6' 28947 28948 Example sequence of a read call, file descriptor 3, buffer is at 28949 target address 0x1234, 6 bytes should be read: 28950 28951 <- `Fread,3,1234,6' 28952 _request memory write to target_ 28953 -> `X1234,6:XXXXXX' 28954 _return "6 bytes read"_ 28955 -> `F6' 28956 28957 Example sequence of a read call, call fails on the host due to 28958 invalid file descriptor (`EBADF'): 28959 28960 <- `Fread,3,1234,6' 28961 -> `F-1,9' 28962 28963 Example sequence of a read call, user presses `Ctrl-c' before 28964 syscall on host is called: 28965 28966 <- `Fread,3,1234,6' 28967 -> `F-1,4,C' 28968 <- `T02' 28969 28970 Example sequence of a read call, user presses `Ctrl-c' after syscall 28971 on host is called: 28972 28973 <- `Fread,3,1234,6' 28974 -> `X1234,6:XXXXXX' 28975 <- `T02' 28976 28977 28978 File: gdb.info, Node: Library List Format, Next: Memory Map Format, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol 28979 28980 D.14 Library List Format 28981 ======================== 28982 28983 On some platforms, a dynamic loader (e.g. `ld.so') runs in the same 28984 process as your application to manage libraries. In this case, GDB can 28985 use the loader's symbol table and normal memory operations to maintain 28986 a list of shared libraries. On other platforms, the operating system 28987 manages loaded libraries. GDB can not retrieve the list of currently 28988 loaded libraries through memory operations, so it uses the 28989 `qXfer:libraries:read' packet (*note qXfer library list read::) 28990 instead. The remote stub queries the target's operating system and 28991 reports which libraries are loaded. 28992 28993 The `qXfer:libraries:read' packet returns an XML document which 28994 lists loaded libraries and their offsets. Each library has an 28995 associated name and one or more segment or section base addresses, 28996 which report where the library was loaded in memory. 28997 28998 For the common case of libraries that are fully linked binaries, the 28999 library should have a list of segments. If the target supports dynamic 29000 linking of a relocatable object file, its library XML element should 29001 instead include a list of allocated sections. The segment or section 29002 bases are start addresses, not relocation offsets; they do not depend 29003 on the library's link-time base addresses. 29004 29005 GDB must be linked with the Expat library to support XML library 29006 lists. *Note Expat::. 29007 29008 A simple memory map, with one loaded library relocated by a single 29009 offset, looks like this: 29010 29011 <library-list> 29012 <library name="/lib/libc.so.6"> 29013 <segment address="0x10000000"/> 29014 </library> 29015 </library-list> 29016 29017 Another simple memory map, with one loaded library with three 29018 allocated sections (.text, .data, .bss), looks like this: 29019 29020 <library-list> 29021 <library name="sharedlib.o"> 29022 <section address="0x10000000"/> 29023 <section address="0x20000000"/> 29024 <section address="0x30000000"/> 29025 </library> 29026 </library-list> 29027 29028 The format of a library list is described by this DTD: 29029 29030 <!-- library-list: Root element with versioning --> 29031 <!ELEMENT library-list (library)*> 29032 <!ATTLIST library-list version CDATA #FIXED "1.0"> 29033 <!ELEMENT library (segment*, section*)> 29034 <!ATTLIST library name CDATA #REQUIRED> 29035 <!ELEMENT segment EMPTY> 29036 <!ATTLIST segment address CDATA #REQUIRED> 29037 <!ELEMENT section EMPTY> 29038 <!ATTLIST section address CDATA #REQUIRED> 29039 29040 In addition, segments and section descriptors cannot be mixed within 29041 a single library element, and you must supply at least one segment or 29042 section for each library. 29043 29044 29045 File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format, Up: Remote Protocol 29046 29047 D.15 Memory Map Format 29048 ====================== 29049 29050 To be able to write into flash memory, GDB needs to obtain a memory map 29051 from the target. This section describes the format of the memory map. 29052 29053 The memory map is obtained using the `qXfer:memory-map:read' (*note 29054 qXfer memory map read::) packet and is an XML document that lists 29055 memory regions. 29056 29057 GDB must be linked with the Expat library to support XML memory 29058 maps. *Note Expat::. 29059 29060 The top-level structure of the document is shown below: 29061 29062 <?xml version="1.0"?> 29063 <!DOCTYPE memory-map 29064 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" 29065 "http://sourceware.org/gdb/gdb-memory-map.dtd"> 29066 <memory-map> 29067 region... 29068 </memory-map> 29069 29070 Each region can be either: 29071 29072 * A region of RAM starting at ADDR and extending for LENGTH bytes 29073 from there: 29074 29075 <memory type="ram" start="ADDR" length="LENGTH"/> 29076 29077 * A region of read-only memory: 29078 29079 <memory type="rom" start="ADDR" length="LENGTH"/> 29080 29081 * A region of flash memory, with erasure blocks BLOCKSIZE bytes in 29082 length: 29083 29084 <memory type="flash" start="ADDR" length="LENGTH"> 29085 <property name="blocksize">BLOCKSIZE</property> 29086 </memory> 29087 29088 29089 Regions must not overlap. GDB assumes that areas of memory not 29090 covered by the memory map are RAM, and uses the ordinary `M' and `X' 29091 packets to write to addresses in such ranges. 29092 29093 The formal DTD for memory map format is given below: 29094 29095 <!-- ................................................... --> 29096 <!-- Memory Map XML DTD ................................ --> 29097 <!-- File: memory-map.dtd .............................. --> 29098 <!-- .................................... .............. --> 29099 <!-- memory-map.dtd --> 29100 <!-- memory-map: Root element with versioning --> 29101 <!ELEMENT memory-map (memory | property)> 29102 <!ATTLIST memory-map version CDATA #FIXED "1.0.0"> 29103 <!ELEMENT memory (property)> 29104 <!-- memory: Specifies a memory region, 29105 and its type, or device. --> 29106 <!ATTLIST memory type CDATA #REQUIRED 29107 start CDATA #REQUIRED 29108 length CDATA #REQUIRED 29109 device CDATA #IMPLIED> 29110 <!-- property: Generic attribute tag --> 29111 <!ELEMENT property (#PCDATA | property)*> 29112 <!ATTLIST property name CDATA #REQUIRED> 29113 29114 29115 File: gdb.info, Node: Thread List Format, Prev: Memory Map Format, Up: Remote Protocol 29116 29117 D.16 Thread List Format 29118 ======================= 29119 29120 To efficiently update the list of threads and their attributes, GDB 29121 issues the `qXfer:threads:read' packet (*note qXfer threads read::) and 29122 obtains the XML document with the following structure: 29123 29124 <?xml version="1.0"?> 29125 <threads> 29126 <thread id="id" core="0"> 29127 ... description ... 29128 </thread> 29129 </threads> 29130 29131 Each `thread' element must have the `id' attribute that identifies 29132 the thread (*note thread-id syntax::). The `core' attribute, if 29133 present, specifies which processor core the thread was last executing 29134 on. The content of the of `thread' element is interpreted as 29135 human-readable auxilliary information. 29136 29137 29138 File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top 29139 29140 Appendix E The GDB Agent Expression Mechanism 29141 ********************************************* 29142 29143 In some applications, it is not feasible for the debugger to interrupt 29144 the program's execution long enough for the developer to learn anything 29145 helpful about its behavior. If the program's correctness depends on its 29146 real-time behavior, delays introduced by a debugger might cause the 29147 program to fail, even when the code itself is correct. It is useful to 29148 be able to observe the program's behavior without interrupting it. 29149 29150 Using GDB's `trace' and `collect' commands, the user can specify 29151 locations in the program, and arbitrary expressions to evaluate when 29152 those locations are reached. Later, using the `tfind' command, she can 29153 examine the values those expressions had when the program hit the trace 29154 points. The expressions may also denote objects in memory -- 29155 structures or arrays, for example -- whose values GDB should record; 29156 while visiting a particular tracepoint, the user may inspect those 29157 objects as if they were in memory at that moment. However, because GDB 29158 records these values without interacting with the user, it can do so 29159 quickly and unobtrusively, hopefully not disturbing the program's 29160 behavior. 29161 29162 When GDB is debugging a remote target, the GDB "agent" code running 29163 on the target computes the values of the expressions itself. To avoid 29164 having a full symbolic expression evaluator on the agent, GDB translates 29165 expressions in the source language into a simpler bytecode language, and 29166 then sends the bytecode to the agent; the agent then executes the 29167 bytecode, and records the values for GDB to retrieve later. 29168 29169 The bytecode language is simple; there are forty-odd opcodes, the 29170 bulk of which are the usual vocabulary of C operands (addition, 29171 subtraction, shifts, and so on) and various sizes of literals and 29172 memory reference operations. The bytecode interpreter operates 29173 strictly on machine-level values -- various sizes of integers and 29174 floating point numbers -- and requires no information about types or 29175 symbols; thus, the interpreter's internal data structures are simple, 29176 and each bytecode requires only a few native machine instructions to 29177 implement it. The interpreter is small, and strict limits on the 29178 memory and time required to evaluate an expression are easy to 29179 determine, making it suitable for use by the debugging agent in 29180 real-time applications. 29181 29182 * Menu: 29183 29184 * General Bytecode Design:: Overview of the interpreter. 29185 * Bytecode Descriptions:: What each one does. 29186 * Using Agent Expressions:: How agent expressions fit into the big picture. 29187 * Varying Target Capabilities:: How to discover what the target can do. 29188 * Rationale:: Why we did it this way. 29189 29190 29191 File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions 29192 29193 E.1 General Bytecode Design 29194 =========================== 29195 29196 The agent represents bytecode expressions as an array of bytes. Each 29197 instruction is one byte long (thus the term "bytecode"). Some 29198 instructions are followed by operand bytes; for example, the `goto' 29199 instruction is followed by a destination for the jump. 29200 29201 The bytecode interpreter is a stack-based machine; most instructions 29202 pop their operands off the stack, perform some operation, and push the 29203 result back on the stack for the next instruction to consume. Each 29204 element of the stack may contain either a integer or a floating point 29205 value; these values are as many bits wide as the largest integer that 29206 can be directly manipulated in the source language. Stack elements 29207 carry no record of their type; bytecode could push a value as an 29208 integer, then pop it as a floating point value. However, GDB will not 29209 generate code which does this. In C, one might define the type of a 29210 stack element as follows: 29211 union agent_val { 29212 LONGEST l; 29213 DOUBLEST d; 29214 }; 29215 where `LONGEST' and `DOUBLEST' are `typedef' names for the largest 29216 integer and floating point types on the machine. 29217 29218 By the time the bytecode interpreter reaches the end of the 29219 expression, the value of the expression should be the only value left 29220 on the stack. For tracing applications, `trace' bytecodes in the 29221 expression will have recorded the necessary data, and the value on the 29222 stack may be discarded. For other applications, like conditional 29223 breakpoints, the value may be useful. 29224 29225 Separate from the stack, the interpreter has two registers: 29226 `pc' 29227 The address of the next bytecode to execute. 29228 29229 `start' 29230 The address of the start of the bytecode expression, necessary for 29231 interpreting the `goto' and `if_goto' instructions. 29232 29233 Neither of these registers is directly visible to the bytecode 29234 language itself, but they are useful for defining the meanings of the 29235 bytecode operations. 29236 29237 There are no instructions to perform side effects on the running 29238 program, or call the program's functions; we assume that these 29239 expressions are only used for unobtrusive debugging, not for patching 29240 the running code. 29241 29242 Most bytecode instructions do not distinguish between the various 29243 sizes of values, and operate on full-width values; the upper bits of the 29244 values are simply ignored, since they do not usually make a difference 29245 to the value computed. The exceptions to this rule are: 29246 memory reference instructions (`ref'N) 29247 There are distinct instructions to fetch different word sizes from 29248 memory. Once on the stack, however, the values are treated as 29249 full-size integers. They may need to be sign-extended; the `ext' 29250 instruction exists for this purpose. 29251 29252 the sign-extension instruction (`ext' N) 29253 These clearly need to know which portion of their operand is to be 29254 extended to occupy the full length of the word. 29255 29256 29257 If the interpreter is unable to evaluate an expression completely for 29258 some reason (a memory location is inaccessible, or a divisor is zero, 29259 for example), we say that interpretation "terminates with an error". 29260 This means that the problem is reported back to the interpreter's caller 29261 in some helpful way. In general, code using agent expressions should 29262 assume that they may attempt to divide by zero, fetch arbitrary memory 29263 locations, and misbehave in other ways. 29264 29265 Even complicated C expressions compile to a few bytecode 29266 instructions; for example, the expression `x + y * z' would typically 29267 produce code like the following, assuming that `x' and `y' live in 29268 registers, and `z' is a global variable holding a 32-bit `int': 29269 reg 1 29270 reg 2 29271 const32 address of z 29272 ref32 29273 ext 32 29274 mul 29275 add 29276 end 29277 29278 In detail, these mean: 29279 `reg 1' 29280 Push the value of register 1 (presumably holding `x') onto the 29281 stack. 29282 29283 `reg 2' 29284 Push the value of register 2 (holding `y'). 29285 29286 `const32 address of z' 29287 Push the address of `z' onto the stack. 29288 29289 `ref32' 29290 Fetch a 32-bit word from the address at the top of the stack; 29291 replace the address on the stack with the value. Thus, we replace 29292 the address of `z' with `z''s value. 29293 29294 `ext 32' 29295 Sign-extend the value on the top of the stack from 32 bits to full 29296 length. This is necessary because `z' is a signed integer. 29297 29298 `mul' 29299 Pop the top two numbers on the stack, multiply them, and push their 29300 product. Now the top of the stack contains the value of the 29301 expression `y * z'. 29302 29303 `add' 29304 Pop the top two numbers, add them, and push the sum. Now the top 29305 of the stack contains the value of `x + y * z'. 29306 29307 `end' 29308 Stop executing; the value left on the stack top is the value to be 29309 recorded. 29310 29311 29312 29313 File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions 29314 29315 E.2 Bytecode Descriptions 29316 ========================= 29317 29318 Each bytecode description has the following form: 29319 29320 `add' (0x02): A B => A+B 29321 Pop the top two stack items, A and B, as integers; push their sum, 29322 as an integer. 29323 29324 29325 In this example, `add' is the name of the bytecode, and `(0x02)' is 29326 the one-byte value used to encode the bytecode, in hexadecimal. The 29327 phrase "A B => A+B" shows the stack before and after the bytecode 29328 executes. Beforehand, the stack must contain at least two values, A 29329 and B; since the top of the stack is to the right, B is on the top of 29330 the stack, and A is underneath it. After execution, the bytecode will 29331 have popped A and B from the stack, and replaced them with a single 29332 value, A+B. There may be other values on the stack below those shown, 29333 but the bytecode affects only those shown. 29334 29335 Here is another example: 29336 29337 `const8' (0x22) N: => N 29338 Push the 8-bit integer constant N on the stack, without sign 29339 extension. 29340 29341 29342 In this example, the bytecode `const8' takes an operand N directly 29343 from the bytecode stream; the operand follows the `const8' bytecode 29344 itself. We write any such operands immediately after the name of the 29345 bytecode, before the colon, and describe the exact encoding of the 29346 operand in the bytecode stream in the body of the bytecode description. 29347 29348 For the `const8' bytecode, there are no stack items given before the 29349 =>; this simply means that the bytecode consumes no values from the 29350 stack. If a bytecode consumes no values, or produces no values, the 29351 list on either side of the => may be empty. 29352 29353 If a value is written as A, B, or N, then the bytecode treats it as 29354 an integer. If a value is written is ADDR, then the bytecode treats it 29355 as an address. 29356 29357 We do not fully describe the floating point operations here; although 29358 this design can be extended in a clean way to handle floating point 29359 values, they are not of immediate interest to the customer, so we avoid 29360 describing them, to save time. 29361 29362 `float' (0x01): => 29363 Prefix for floating-point bytecodes. Not implemented yet. 29364 29365 `add' (0x02): A B => A+B 29366 Pop two integers from the stack, and push their sum, as an integer. 29367 29368 `sub' (0x03): A B => A-B 29369 Pop two integers from the stack, subtract the top value from the 29370 next-to-top value, and push the difference. 29371 29372 `mul' (0x04): A B => A*B 29373 Pop two integers from the stack, multiply them, and push the 29374 product on the stack. Note that, when one multiplies two N-bit 29375 numbers yielding another N-bit number, it is irrelevant whether the 29376 numbers are signed or not; the results are the same. 29377 29378 `div_signed' (0x05): A B => A/B 29379 Pop two signed integers from the stack; divide the next-to-top 29380 value by the top value, and push the quotient. If the divisor is 29381 zero, terminate with an error. 29382 29383 `div_unsigned' (0x06): A B => A/B 29384 Pop two unsigned integers from the stack; divide the next-to-top 29385 value by the top value, and push the quotient. If the divisor is 29386 zero, terminate with an error. 29387 29388 `rem_signed' (0x07): A B => A MODULO B 29389 Pop two signed integers from the stack; divide the next-to-top 29390 value by the top value, and push the remainder. If the divisor is 29391 zero, terminate with an error. 29392 29393 `rem_unsigned' (0x08): A B => A MODULO B 29394 Pop two unsigned integers from the stack; divide the next-to-top 29395 value by the top value, and push the remainder. If the divisor is 29396 zero, terminate with an error. 29397 29398 `lsh' (0x09): A B => A<<B 29399 Pop two integers from the stack; let A be the next-to-top value, 29400 and B be the top value. Shift A left by B bits, and push the 29401 result. 29402 29403 `rsh_signed' (0x0a): A B => `(signed)'A>>B 29404 Pop two integers from the stack; let A be the next-to-top value, 29405 and B be the top value. Shift A right by B bits, inserting copies 29406 of the top bit at the high end, and push the result. 29407 29408 `rsh_unsigned' (0x0b): A B => A>>B 29409 Pop two integers from the stack; let A be the next-to-top value, 29410 and B be the top value. Shift A right by B bits, inserting zero 29411 bits at the high end, and push the result. 29412 29413 `log_not' (0x0e): A => !A 29414 Pop an integer from the stack; if it is zero, push the value one; 29415 otherwise, push the value zero. 29416 29417 `bit_and' (0x0f): A B => A&B 29418 Pop two integers from the stack, and push their bitwise `and'. 29419 29420 `bit_or' (0x10): A B => A|B 29421 Pop two integers from the stack, and push their bitwise `or'. 29422 29423 `bit_xor' (0x11): A B => A^B 29424 Pop two integers from the stack, and push their bitwise 29425 exclusive-`or'. 29426 29427 `bit_not' (0x12): A => ~A 29428 Pop an integer from the stack, and push its bitwise complement. 29429 29430 `equal' (0x13): A B => A=B 29431 Pop two integers from the stack; if they are equal, push the value 29432 one; otherwise, push the value zero. 29433 29434 `less_signed' (0x14): A B => A<B 29435 Pop two signed integers from the stack; if the next-to-top value 29436 is less than the top value, push the value one; otherwise, push 29437 the value zero. 29438 29439 `less_unsigned' (0x15): A B => A<B 29440 Pop two unsigned integers from the stack; if the next-to-top value 29441 is less than the top value, push the value one; otherwise, push 29442 the value zero. 29443 29444 `ext' (0x16) N: A => A, sign-extended from N bits 29445 Pop an unsigned value from the stack; treating it as an N-bit 29446 twos-complement value, extend it to full length. This means that 29447 all bits to the left of bit N-1 (where the least significant bit 29448 is bit 0) are set to the value of bit N-1. Note that N may be 29449 larger than or equal to the width of the stack elements of the 29450 bytecode engine; in this case, the bytecode should have no effect. 29451 29452 The number of source bits to preserve, N, is encoded as a single 29453 byte unsigned integer following the `ext' bytecode. 29454 29455 `zero_ext' (0x2a) N: A => A, zero-extended from N bits 29456 Pop an unsigned value from the stack; zero all but the bottom N 29457 bits. This means that all bits to the left of bit N-1 (where the 29458 least significant bit is bit 0) are set to the value of bit N-1. 29459 29460 The number of source bits to preserve, N, is encoded as a single 29461 byte unsigned integer following the `zero_ext' bytecode. 29462 29463 `ref8' (0x17): ADDR => A 29464 `ref16' (0x18): ADDR => A 29465 `ref32' (0x19): ADDR => A 29466 `ref64' (0x1a): ADDR => A 29467 Pop an address ADDR from the stack. For bytecode `ref'N, fetch an 29468 N-bit value from ADDR, using the natural target endianness. Push 29469 the fetched value as an unsigned integer. 29470 29471 Note that ADDR may not be aligned in any particular way; the 29472 `refN' bytecodes should operate correctly for any address. 29473 29474 If attempting to access memory at ADDR would cause a processor 29475 exception of some sort, terminate with an error. 29476 29477 `ref_float' (0x1b): ADDR => D 29478 `ref_double' (0x1c): ADDR => D 29479 `ref_long_double' (0x1d): ADDR => D 29480 `l_to_d' (0x1e): A => D 29481 `d_to_l' (0x1f): D => A 29482 Not implemented yet. 29483 29484 `dup' (0x28): A => A A 29485 Push another copy of the stack's top element. 29486 29487 `swap' (0x2b): A B => B A 29488 Exchange the top two items on the stack. 29489 29490 `pop' (0x29): A => 29491 Discard the top value on the stack. 29492 29493 `if_goto' (0x20) OFFSET: A => 29494 Pop an integer off the stack; if it is non-zero, branch to the 29495 given offset in the bytecode string. Otherwise, continue to the 29496 next instruction in the bytecode stream. In other words, if A is 29497 non-zero, set the `pc' register to `start' + OFFSET. Thus, an 29498 offset of zero denotes the beginning of the expression. 29499 29500 The OFFSET is stored as a sixteen-bit unsigned value, stored 29501 immediately following the `if_goto' bytecode. It is always stored 29502 most significant byte first, regardless of the target's normal 29503 endianness. The offset is not guaranteed to fall at any particular 29504 alignment within the bytecode stream; thus, on machines where 29505 fetching a 16-bit on an unaligned address raises an exception, you 29506 should fetch the offset one byte at a time. 29507 29508 `goto' (0x21) OFFSET: => 29509 Branch unconditionally to OFFSET; in other words, set the `pc' 29510 register to `start' + OFFSET. 29511 29512 The offset is stored in the same way as for the `if_goto' bytecode. 29513 29514 `const8' (0x22) N: => N 29515 `const16' (0x23) N: => N 29516 `const32' (0x24) N: => N 29517 `const64' (0x25) N: => N 29518 Push the integer constant N on the stack, without sign extension. 29519 To produce a small negative value, push a small twos-complement 29520 value, and then sign-extend it using the `ext' bytecode. 29521 29522 The constant N is stored in the appropriate number of bytes 29523 following the `const'B bytecode. The constant N is always stored 29524 most significant byte first, regardless of the target's normal 29525 endianness. The constant is not guaranteed to fall at any 29526 particular alignment within the bytecode stream; thus, on machines 29527 where fetching a 16-bit on an unaligned address raises an 29528 exception, you should fetch N one byte at a time. 29529 29530 `reg' (0x26) N: => A 29531 Push the value of register number N, without sign extension. The 29532 registers are numbered following GDB's conventions. 29533 29534 The register number N is encoded as a 16-bit unsigned integer 29535 immediately following the `reg' bytecode. It is always stored most 29536 significant byte first, regardless of the target's normal 29537 endianness. The register number is not guaranteed to fall at any 29538 particular alignment within the bytecode stream; thus, on machines 29539 where fetching a 16-bit on an unaligned address raises an 29540 exception, you should fetch the register number one byte at a time. 29541 29542 `getv' (0x2c) N: => V 29543 Push the value of trace state variable number N, without sign 29544 extension. 29545 29546 The variable number N is encoded as a 16-bit unsigned integer 29547 immediately following the `getv' bytecode. It is always stored 29548 most significant byte first, regardless of the target's normal 29549 endianness. The variable number is not guaranteed to fall at any 29550 particular alignment within the bytecode stream; thus, on machines 29551 where fetching a 16-bit on an unaligned address raises an 29552 exception, you should fetch the register number one byte at a time. 29553 29554 `setv' (0x2d) N: => V 29555 Set trace state variable number N to the value found on the top of 29556 the stack. The stack is unchanged, so that the value is readily 29557 available if the assignment is part of a larger expression. The 29558 handling of N is as described for `getv'. 29559 29560 `trace' (0x0c): ADDR SIZE => 29561 Record the contents of the SIZE bytes at ADDR in a trace buffer, 29562 for later retrieval by GDB. 29563 29564 `trace_quick' (0x0d) SIZE: ADDR => ADDR 29565 Record the contents of the SIZE bytes at ADDR in a trace buffer, 29566 for later retrieval by GDB. SIZE is a single byte unsigned 29567 integer following the `trace' opcode. 29568 29569 This bytecode is equivalent to the sequence `dup const8 SIZE 29570 trace', but we provide it anyway to save space in bytecode strings. 29571 29572 `trace16' (0x30) SIZE: ADDR => ADDR 29573 Identical to trace_quick, except that SIZE is a 16-bit big-endian 29574 unsigned integer, not a single byte. This should probably have 29575 been named `trace_quick16', for consistency. 29576 29577 `tracev' (0x2e) N: => A 29578 Record the value of trace state variable number N in the trace 29579 buffer. The handling of N is as described for `getv'. 29580 29581 `end' (0x27): => 29582 Stop executing bytecode; the result should be the top element of 29583 the stack. If the purpose of the expression was to compute an 29584 lvalue or a range of memory, then the next-to-top of the stack is 29585 the lvalue's address, and the top of the stack is the lvalue's 29586 size, in bytes. 29587 29588 29589 29590 File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions 29591 29592 E.3 Using Agent Expressions 29593 =========================== 29594 29595 Agent expressions can be used in several different ways by GDB, and the 29596 debugger can generate different bytecode sequences as appropriate. 29597 29598 One possibility is to do expression evaluation on the target rather 29599 than the host, such as for the conditional of a conditional tracepoint. 29600 In such a case, GDB compiles the source expression into a bytecode 29601 sequence that simply gets values from registers or memory, does 29602 arithmetic, and returns a result. 29603 29604 Another way to use agent expressions is for tracepoint data 29605 collection. GDB generates a different bytecode sequence for 29606 collection; in addition to bytecodes that do the calculation, GDB adds 29607 `trace' bytecodes to save the pieces of memory that were used. 29608 29609 * The user selects trace points in the program's code at which GDB 29610 should collect data. 29611 29612 * The user specifies expressions to evaluate at each trace point. 29613 These expressions may denote objects in memory, in which case 29614 those objects' contents are recorded as the program runs, or 29615 computed values, in which case the values themselves are recorded. 29616 29617 * GDB transmits the tracepoints and their associated expressions to 29618 the GDB agent, running on the debugging target. 29619 29620 * The agent arranges to be notified when a trace point is hit. 29621 29622 * When execution on the target reaches a trace point, the agent 29623 evaluates the expressions associated with that trace point, and 29624 records the resulting values and memory ranges. 29625 29626 * Later, when the user selects a given trace event and inspects the 29627 objects and expression values recorded, GDB talks to the agent to 29628 retrieve recorded data as necessary to meet the user's requests. 29629 If the user asks to see an object whose contents have not been 29630 recorded, GDB reports an error. 29631 29632 29633 29634 File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions 29635 29636 E.4 Varying Target Capabilities 29637 =============================== 29638 29639 Some targets don't support floating-point, and some would rather not 29640 have to deal with `long long' operations. Also, different targets will 29641 have different stack sizes, and different bytecode buffer lengths. 29642 29643 Thus, GDB needs a way to ask the target about itself. We haven't 29644 worked out the details yet, but in general, GDB should be able to send 29645 the target a packet asking it to describe itself. The reply should be a 29646 packet whose length is explicit, so we can add new information to the 29647 packet in future revisions of the agent, without confusing old versions 29648 of GDB, and it should contain a version number. It should contain at 29649 least the following information: 29650 29651 * whether floating point is supported 29652 29653 * whether `long long' is supported 29654 29655 * maximum acceptable size of bytecode stack 29656 29657 * maximum acceptable length of bytecode expressions 29658 29659 * which registers are actually available for collection 29660 29661 * whether the target supports disabled tracepoints 29662 29663 29664 29665 File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions 29666 29667 E.5 Rationale 29668 ============= 29669 29670 Some of the design decisions apparent above are arguable. 29671 29672 What about stack overflow/underflow? 29673 GDB should be able to query the target to discover its stack size. 29674 Given that information, GDB can determine at translation time 29675 whether a given expression will overflow the stack. But this spec 29676 isn't about what kinds of error-checking GDB ought to do. 29677 29678 Why are you doing everything in LONGEST? 29679 Speed isn't important, but agent code size is; using LONGEST 29680 brings in a bunch of support code to do things like division, etc. 29681 So this is a serious concern. 29682 29683 First, note that you don't need different bytecodes for different 29684 operand sizes. You can generate code without _knowing_ how big the 29685 stack elements actually are on the target. If the target only 29686 supports 32-bit ints, and you don't send any 64-bit bytecodes, 29687 everything just works. The observation here is that the MIPS and 29688 the Alpha have only fixed-size registers, and you can still get 29689 C's semantics even though most instructions only operate on 29690 full-sized words. You just need to make sure everything is 29691 properly sign-extended at the right times. So there is no need 29692 for 32- and 64-bit variants of the bytecodes. Just implement 29693 everything using the largest size you support. 29694 29695 GDB should certainly check to see what sizes the target supports, 29696 so the user can get an error earlier, rather than later. But this 29697 information is not necessary for correctness. 29698 29699 Why don't you have `>' or `<=' operators? 29700 I want to keep the interpreter small, and we don't need them. We 29701 can combine the `less_' opcodes with `log_not', and swap the order 29702 of the operands, yielding all four asymmetrical comparison 29703 operators. For example, `(x <= y)' is `! (x > y)', which is `! (y 29704 < x)'. 29705 29706 Why do you have `log_not'? 29707 Why do you have `ext'? 29708 Why do you have `zero_ext'? 29709 These are all easily synthesized from other instructions, but I 29710 expect them to be used frequently, and they're simple, so I 29711 include them to keep bytecode strings short. 29712 29713 `log_not' is equivalent to `const8 0 equal'; it's used in half the 29714 relational operators. 29715 29716 `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed', 29717 where S is the size of the stack elements; it follows `refM' and 29718 REG bytecodes when the value should be signed. See the next 29719 bulleted item. 29720 29721 `zero_ext N' is equivalent to `constM MASK log_and'; it's used 29722 whenever we push the value of a register, because we can't assume 29723 the upper bits of the register aren't garbage. 29724 29725 Why not have sign-extending variants of the `ref' operators? 29726 Because that would double the number of `ref' operators, and we 29727 need the `ext' bytecode anyway for accessing bitfields. 29728 29729 Why not have constant-address variants of the `ref' operators? 29730 Because that would double the number of `ref' operators again, and 29731 `const32 ADDRESS ref32' is only one byte longer. 29732 29733 Why do the `refN' operators have to support unaligned fetches? 29734 GDB will generate bytecode that fetches multi-byte values at 29735 unaligned addresses whenever the executable's debugging 29736 information tells it to. Furthermore, GDB does not know the value 29737 the pointer will have when GDB generates the bytecode, so it 29738 cannot determine whether a particular fetch will be aligned or not. 29739 29740 In particular, structure bitfields may be several bytes long, but 29741 follow no alignment rules; members of packed structures are not 29742 necessarily aligned either. 29743 29744 In general, there are many cases where unaligned references occur 29745 in correct C code, either at the programmer's explicit request, or 29746 at the compiler's discretion. Thus, it is simpler to make the GDB 29747 agent bytecodes work correctly in all circumstances than to make 29748 GDB guess in each case whether the compiler did the usual thing. 29749 29750 Why are there no side-effecting operators? 29751 Because our current client doesn't want them? That's a cheap 29752 answer. I think the real answer is that I'm afraid of 29753 implementing function calls. We should re-visit this issue after 29754 the present contract is delivered. 29755 29756 Why aren't the `goto' ops PC-relative? 29757 The interpreter has the base address around anyway for PC bounds 29758 checking, and it seemed simpler. 29759 29760 Why is there only one offset size for the `goto' ops? 29761 Offsets are currently sixteen bits. I'm not happy with this 29762 situation either: 29763 29764 Suppose we have multiple branch ops with different offset sizes. 29765 As I generate code left-to-right, all my jumps are forward jumps 29766 (there are no loops in expressions), so I never know the target 29767 when I emit the jump opcode. Thus, I have to either always assume 29768 the largest offset size, or do jump relaxation on the code after I 29769 generate it, which seems like a big waste of time. 29770 29771 I can imagine a reasonable expression being longer than 256 bytes. 29772 I can't imagine one being longer than 64k. Thus, we need 16-bit 29773 offsets. This kind of reasoning is so bogus, but relaxation is 29774 pathetic. 29775 29776 The other approach would be to generate code right-to-left. Then 29777 I'd always know my offset size. That might be fun. 29778 29779 Where is the function call bytecode? 29780 When we add side-effects, we should add this. 29781 29782 Why does the `reg' bytecode take a 16-bit register number? 29783 Intel's IA-64 architecture has 128 general-purpose registers, and 29784 128 floating-point registers, and I'm sure it has some random 29785 control registers. 29786 29787 Why do we need `trace' and `trace_quick'? 29788 Because GDB needs to record all the memory contents and registers 29789 an expression touches. If the user wants to evaluate an expression 29790 `x->y->z', the agent must record the values of `x' and `x->y' as 29791 well as the value of `x->y->z'. 29792 29793 Don't the `trace' bytecodes make the interpreter less general? 29794 They do mean that the interpreter contains special-purpose code, 29795 but that doesn't mean the interpreter can only be used for that 29796 purpose. If an expression doesn't use the `trace' bytecodes, they 29797 don't get in its way. 29798 29799 Why doesn't `trace_quick' consume its arguments the way everything else does? 29800 In general, you do want your operators to consume their arguments; 29801 it's consistent, and generally reduces the amount of stack 29802 rearrangement necessary. However, `trace_quick' is a kludge to 29803 save space; it only exists so we needn't write `dup const8 SIZE 29804 trace' before every memory reference. Therefore, it's okay for it 29805 not to consume its arguments; it's meant for a specific context in 29806 which we know exactly what it should do with the stack. If we're 29807 going to have a kludge, it should be an effective kludge. 29808 29809 Why does `trace16' exist? 29810 That opcode was added by the customer that contracted Cygnus for 29811 the data tracing work. I personally think it is unnecessary; 29812 objects that large will be quite rare, so it is okay to use `dup 29813 const16 SIZE trace' in those cases. 29814 29815 Whatever we decide to do with `trace16', we should at least leave 29816 opcode 0x30 reserved, to remain compatible with the customer who 29817 added it. 29818 29819 29820 29821 File: gdb.info, Node: Trace File Format, Next: Copying, Prev: Operating System Information, Up: Top 29822 29823 Appendix F Trace File Format 29824 **************************** 29825 29826 The trace file comes in three parts: a header, a textual description 29827 section, and a trace frame section with binary data. 29828 29829 The header has the form `\x7fTRACE0\n'. The first byte is `0x7f' so 29830 as to indicate that the file contains binary data, while the `0' is a 29831 version number that may have different values in the future. 29832 29833 The description section consists of multiple lines of ASCII text 29834 separated by newline characters (`0xa'). The lines may include a 29835 variety of optional descriptive or context-setting information, such as 29836 tracepoint definitions or register set size. GDB will ignore any line 29837 that it does not recognize. An empty line marks the end of this 29838 section. 29839 29840 The trace frame section consists of a number of consecutive frames. 29841 Each frame begins with a two-byte tracepoint number, followed by a 29842 four-byte size giving the amount of data in the frame. The data in the 29843 frame consists of a number of blocks, each introduced by a character 29844 indicating its type (at least register, memory, and trace state 29845 variable). The data in this section is raw binary, not a hexadecimal 29846 or other encoding; its endianness matches the target's endianness. 29847 29848 `R BYTES' 29849 Register block. The number and ordering of bytes matches that of a 29850 `g' packet in the remote protocol. Note that these are the actual 29851 bytes, in target order and GDB register order, not a hexadecimal 29852 encoding. 29853 29854 `M ADDRESS LENGTH BYTES...' 29855 Memory block. This is a contiguous block of memory, at the 8-byte 29856 address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH 29857 bytes. 29858 29859 `V NUMBER VALUE' 29860 Trace state variable block. This records the 8-byte signed value 29861 VALUE of trace state variable numbered NUMBER. 29862 29863 29864 Future enhancements of the trace file format may include additional 29865 types of blocks. 29866 29867 29868 File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top 29869 29870 Appendix G Target Descriptions 29871 ****************************** 29872 29873 *Warning:* target descriptions are still under active development, and 29874 the contents and format may change between GDB releases. The format is 29875 expected to stabilize in the future. 29876 29877 One of the challenges of using GDB to debug embedded systems is that 29878 there are so many minor variants of each processor architecture in use. 29879 It is common practice for vendors to start with a standard processor 29880 core -- ARM, PowerPC, or MIPS, for example -- and then make changes to 29881 adapt it to a particular market niche. Some architectures have 29882 hundreds of variants, available from dozens of vendors. This leads to 29883 a number of problems: 29884 29885 * With so many different customized processors, it is difficult for 29886 the GDB maintainers to keep up with the changes. 29887 29888 * Since individual variants may have short lifetimes or limited 29889 audiences, it may not be worthwhile to carry information about 29890 every variant in the GDB source tree. 29891 29892 * When GDB does support the architecture of the embedded system at 29893 hand, the task of finding the correct architecture name to give the 29894 `set architecture' command can be error-prone. 29895 29896 To address these problems, the GDB remote protocol allows a target 29897 system to not only identify itself to GDB, but to actually describe its 29898 own features. This lets GDB support processor variants it has never 29899 seen before -- to the extent that the descriptions are accurate, and 29900 that GDB understands them. 29901 29902 GDB must be linked with the Expat library to support XML target 29903 descriptions. *Note Expat::. 29904 29905 * Menu: 29906 29907 * Retrieving Descriptions:: How descriptions are fetched from a target. 29908 * Target Description Format:: The contents of a target description. 29909 * Predefined Target Types:: Standard types available for target 29910 descriptions. 29911 * Standard Target Features:: Features GDB knows about. 29912 29913 29914 File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions 29915 29916 G.1 Retrieving Descriptions 29917 =========================== 29918 29919 Target descriptions can be read from the target automatically, or 29920 specified by the user manually. The default behavior is to read the 29921 description from the target. GDB retrieves it via the remote protocol 29922 using `qXfer' requests (*note qXfer: General Query Packets.). The 29923 ANNEX in the `qXfer' packet will be `target.xml'. The contents of the 29924 `target.xml' annex are an XML document, of the form described in *Note 29925 Target Description Format::. 29926 29927 Alternatively, you can specify a file to read for the target 29928 description. If a file is set, the target will not be queried. The 29929 commands to specify a file are: 29930 29931 `set tdesc filename PATH' 29932 Read the target description from PATH. 29933 29934 `unset tdesc filename' 29935 Do not read the XML target description from a file. GDB will use 29936 the description supplied by the current target. 29937 29938 `show tdesc filename' 29939 Show the filename to read for a target description, if any. 29940 29941 29942 File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions 29943 29944 G.2 Target Description Format 29945 ============================= 29946 29947 A target description annex is an XML (http://www.w3.org/XML/) document 29948 which complies with the Document Type Definition provided in the GDB 29949 sources in `gdb/features/gdb-target.dtd'. This means you can use 29950 generally available tools like `xmllint' to check that your feature 29951 descriptions are well-formed and valid. However, to help people 29952 unfamiliar with XML write descriptions for their targets, we also 29953 describe the grammar here. 29954 29955 Target descriptions can identify the architecture of the remote 29956 target and (for some architectures) provide information about custom 29957 register sets. They can also identify the OS ABI of the remote target. 29958 GDB can use this information to autoconfigure for your target, or to 29959 warn you if you connect to an unsupported target. 29960 29961 Here is a simple target description: 29962 29963 <target version="1.0"> 29964 <architecture>i386:x86-64</architecture> 29965 </target> 29966 29967 This minimal description only says that the target uses the x86-64 29968 architecture. 29969 29970 A target description has the following overall form, with [ ] marking 29971 optional elements and ... marking repeatable elements. The elements 29972 are explained further below. 29973 29974 <?xml version="1.0"?> 29975 <!DOCTYPE target SYSTEM "gdb-target.dtd"> 29976 <target version="1.0"> 29977 [ARCHITECTURE] 29978 [OSABI] 29979 [COMPATIBLE] 29980 [FEATURE...] 29981 </target> 29982 29983 The description is generally insensitive to whitespace and line breaks, 29984 under the usual common-sense rules. The XML version declaration and 29985 document type declaration can generally be omitted (GDB does not 29986 require them), but specifying them may be useful for XML validation 29987 tools. The `version' attribute for `<target>' may also be omitted, but 29988 we recommend including it; if future versions of GDB use an incompatible 29989 revision of `gdb-target.dtd', they will detect and report the version 29990 mismatch. 29991 29992 G.2.1 Inclusion 29993 --------------- 29994 29995 It can sometimes be valuable to split a target description up into 29996 several different annexes, either for organizational purposes, or to 29997 share files between different possible target descriptions. You can 29998 divide a description into multiple files by replacing any element of 29999 the target description with an inclusion directive of the form: 30000 30001 <xi:include href="DOCUMENT"/> 30002 30003 When GDB encounters an element of this form, it will retrieve the named 30004 XML DOCUMENT, and replace the inclusion directive with the contents of 30005 that document. If the current description was read using `qXfer', then 30006 so will be the included document; DOCUMENT will be interpreted as the 30007 name of an annex. If the current description was read from a file, GDB 30008 will look for DOCUMENT as a file in the same directory where it found 30009 the original description. 30010 30011 G.2.2 Architecture 30012 ------------------ 30013 30014 An `<architecture>' element has this form: 30015 30016 <architecture>ARCH</architecture> 30017 30018 ARCH is one of the architectures from the set accepted by `set 30019 architecture' (*note Specifying a Debugging Target: Targets.). 30020 30021 G.2.3 OS ABI 30022 ------------ 30023 30024 This optional field was introduced in GDB version 7.0. Previous 30025 versions of GDB ignore it. 30026 30027 An `<osabi>' element has this form: 30028 30029 <osabi>ABI-NAME</osabi> 30030 30031 ABI-NAME is an OS ABI name from the same selection accepted by 30032 `set osabi' (*note Configuring the Current ABI: ABI.). 30033 30034 G.2.4 Compatible Architecture 30035 ----------------------------- 30036 30037 This optional field was introduced in GDB version 7.0. Previous 30038 versions of GDB ignore it. 30039 30040 A `<compatible>' element has this form: 30041 30042 <compatible>ARCH</compatible> 30043 30044 ARCH is one of the architectures from the set accepted by `set 30045 architecture' (*note Specifying a Debugging Target: Targets.). 30046 30047 A `<compatible>' element is used to specify that the target is able 30048 to run binaries in some other than the main target architecture given 30049 by the `<architecture>' element. For example, on the Cell Broadband 30050 Engine, the main architecture is `powerpc:common' or 30051 `powerpc:common64', but the system is able to run binaries in the `spu' 30052 architecture as well. The way to describe this capability with 30053 `<compatible>' is as follows: 30054 30055 <architecture>powerpc:common</architecture> 30056 <compatible>spu</compatible> 30057 30058 G.2.5 Features 30059 -------------- 30060 30061 Each `<feature>' describes some logical portion of the target system. 30062 Features are currently used to describe available CPU registers and the 30063 types of their contents. A `<feature>' element has this form: 30064 30065 <feature name="NAME"> 30066 [TYPE...] 30067 REG... 30068 </feature> 30069 30070 Each feature's name should be unique within the description. The name 30071 of a feature does not matter unless GDB has some special knowledge of 30072 the contents of that feature; if it does, the feature should have its 30073 standard name. *Note Standard Target Features::. 30074 30075 G.2.6 Types 30076 ----------- 30077 30078 Any register's value is a collection of bits which GDB must interpret. 30079 The default interpretation is a two's complement integer, but other 30080 types can be requested by name in the register description. Some 30081 predefined types are provided by GDB (*note Predefined Target Types::), 30082 and the description can define additional composite types. 30083 30084 Each type element must have an `id' attribute, which gives a unique 30085 (within the containing `<feature>') name to the type. Types must be 30086 defined before they are used. 30087 30088 Some targets offer vector registers, which can be treated as arrays 30089 of scalar elements. These types are written as `<vector>' elements, 30090 specifying the array element type, TYPE, and the number of elements, 30091 COUNT: 30092 30093 <vector id="ID" type="TYPE" count="COUNT"/> 30094 30095 If a register's value is usefully viewed in multiple ways, define it 30096 with a union type containing the useful representations. The `<union>' 30097 element contains one or more `<field>' elements, each of which has a 30098 NAME and a TYPE: 30099 30100 <union id="ID"> 30101 <field name="NAME" type="TYPE"/> 30102 ... 30103 </union> 30104 30105 G.2.7 Registers 30106 --------------- 30107 30108 Each register is represented as an element with this form: 30109 30110 <reg name="NAME" 30111 bitsize="SIZE" 30112 [regnum="NUM"] 30113 [save-restore="SAVE-RESTORE"] 30114 [type="TYPE"] 30115 [group="GROUP"]/> 30116 30117 The components are as follows: 30118 30119 NAME 30120 The register's name; it must be unique within the target 30121 description. 30122 30123 BITSIZE 30124 The register's size, in bits. 30125 30126 REGNUM 30127 The register's number. If omitted, a register's number is one 30128 greater than that of the previous register (either in the current 30129 feature or in a preceeding feature); the first register in the 30130 target description defaults to zero. This register number is used 30131 to read or write the register; e.g. it is used in the remote `p' 30132 and `P' packets, and registers appear in the `g' and `G' packets 30133 in order of increasing register number. 30134 30135 SAVE-RESTORE 30136 Whether the register should be preserved across inferior function 30137 calls; this must be either `yes' or `no'. The default is `yes', 30138 which is appropriate for most registers except for some system 30139 control registers; this is not related to the target's ABI. 30140 30141 TYPE 30142 The type of the register. TYPE may be a predefined type, a type 30143 defined in the current feature, or one of the special types `int' 30144 and `float'. `int' is an integer type of the correct size for 30145 BITSIZE, and `float' is a floating point type (in the 30146 architecture's normal floating point format) of the correct size 30147 for BITSIZE. The default is `int'. 30148 30149 GROUP 30150 The register group to which this register belongs. GROUP must be 30151 either `general', `float', or `vector'. If no GROUP is specified, 30152 GDB will not display the register in `info registers'. 30153 30154 30155 30156 File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions 30157 30158 G.3 Predefined Target Types 30159 =========================== 30160 30161 Type definitions in the self-description can build up composite types 30162 from basic building blocks, but can not define fundamental types. 30163 Instead, standard identifiers are provided by GDB for the fundamental 30164 types. The currently supported types are: 30165 30166 `int8' 30167 `int16' 30168 `int32' 30169 `int64' 30170 `int128' 30171 Signed integer types holding the specified number of bits. 30172 30173 `uint8' 30174 `uint16' 30175 `uint32' 30176 `uint64' 30177 `uint128' 30178 Unsigned integer types holding the specified number of bits. 30179 30180 `code_ptr' 30181 `data_ptr' 30182 Pointers to unspecified code and data. The program counter and 30183 any dedicated return address register may be marked as code 30184 pointers; printing a code pointer converts it into a symbolic 30185 address. The stack pointer and any dedicated address registers 30186 may be marked as data pointers. 30187 30188 `ieee_single' 30189 Single precision IEEE floating point. 30190 30191 `ieee_double' 30192 Double precision IEEE floating point. 30193 30194 `arm_fpa_ext' 30195 The 12-byte extended precision format used by ARM FPA registers. 30196 30197 `i387_ext' 30198 The 10-byte extended precision format used by x87 registers. 30199 30200 `i386_eflags' 30201 32bit EFLAGS register used by x86. 30202 30203 `i386_mxcsr' 30204 32bit MXCSR register used by x86. 30205 30206 30207 30208 File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions 30209 30210 G.4 Standard Target Features 30211 ============================ 30212 30213 A target description must contain either no registers or all the 30214 target's registers. If the description contains no registers, then GDB 30215 will assume a default register layout, selected based on the 30216 architecture. If the description contains any registers, the default 30217 layout will not be used; the standard registers must be described in 30218 the target description, in such a way that GDB can recognize them. 30219 30220 This is accomplished by giving specific names to feature elements 30221 which contain standard registers. GDB will look for features with 30222 those names and verify that they contain the expected registers; if any 30223 known feature is missing required registers, or if any required feature 30224 is missing, GDB will reject the target description. You can add 30225 additional registers to any of the standard features -- GDB will 30226 display them just as if they were added to an unrecognized feature. 30227 30228 This section lists the known features and their expected contents. 30229 Sample XML documents for these features are included in the GDB source 30230 tree, in the directory `gdb/features'. 30231 30232 Names recognized by GDB should include the name of the company or 30233 organization which selected the name, and the overall architecture to 30234 which the feature applies; so e.g. the feature containing ARM core 30235 registers is named `org.gnu.gdb.arm.core'. 30236 30237 The names of registers are not case sensitive for the purpose of 30238 recognizing standard features, but GDB will only display registers 30239 using the capitalization used in the description. 30240 30241 * Menu: 30242 30243 * ARM Features:: 30244 * i386 Features:: 30245 * MIPS Features:: 30246 * M68K Features:: 30247 * PowerPC Features:: 30248 30249 30250 File: gdb.info, Node: ARM Features, Next: i386 Features, Up: Standard Target Features 30251 30252 G.4.1 ARM Features 30253 ------------------ 30254 30255 The `org.gnu.gdb.arm.core' feature is required for ARM targets. It 30256 should contain registers `r0' through `r13', `sp', `lr', `pc', and 30257 `cpsr'. 30258 30259 The `org.gnu.gdb.arm.fpa' feature is optional. If present, it 30260 should contain registers `f0' through `f7' and `fps'. 30261 30262 The `org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it 30263 should contain at least registers `wR0' through `wR15' and `wCGR0' 30264 through `wCGR3'. The `wCID', `wCon', `wCSSF', and `wCASF' registers 30265 are optional. 30266 30267 The `org.gnu.gdb.arm.vfp' feature is optional. If present, it 30268 should contain at least registers `d0' through `d15'. If they are 30269 present, `d16' through `d31' should also be included. GDB will 30270 synthesize the single-precision registers from halves of the 30271 double-precision registers. 30272 30273 The `org.gnu.gdb.arm.neon' feature is optional. It does not need to 30274 contain registers; it instructs GDB to display the VFP double-precision 30275 registers as vectors and to synthesize the quad-precision registers 30276 from pairs of double-precision registers. If this feature is present, 30277 `org.gnu.gdb.arm.vfp' must also be present and include 32 30278 double-precision registers. 30279 30280 30281 File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features 30282 30283 G.4.2 i386 Features 30284 ------------------- 30285 30286 The `org.gnu.gdb.i386.core' feature is required for i386/amd64 targets. 30287 It should describe the following registers: 30288 30289 - `eax' through `edi' plus `eip' for i386 30290 30291 - `rax' through `r15' plus `rip' for amd64 30292 30293 - `eflags', `cs', `ss', `ds', `es', `fs', `gs' 30294 30295 - `st0' through `st7' 30296 30297 - `fctrl', `fstat', `ftag', `fiseg', `fioff', `foseg', `fooff' and 30298 `fop' 30299 30300 The register sets may be different, depending on the target. 30301 30302 The `org.gnu.gdb.i386.sse' feature is required. It should describe 30303 registers: 30304 30305 - `xmm0' through `xmm7' for i386 30306 30307 - `xmm0' through `xmm15' for amd64 30308 30309 - `mxcsr' 30310 30311 The `org.gnu.gdb.i386.linux' feature is optional. It should 30312 describe a single register, `orig_eax'. 30313 30314 30315 File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features 30316 30317 G.4.3 MIPS Features 30318 ------------------- 30319 30320 The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It 30321 should contain registers `r0' through `r31', `lo', `hi', and `pc'. 30322 They may be 32-bit or 64-bit depending on the target. 30323 30324 The `org.gnu.gdb.mips.cp0' feature is also required. It should 30325 contain at least the `status', `badvaddr', and `cause' registers. They 30326 may be 32-bit or 64-bit depending on the target. 30327 30328 The `org.gnu.gdb.mips.fpu' feature is currently required, though it 30329 may be optional in a future version of GDB. It should contain 30330 registers `f0' through `f31', `fcsr', and `fir'. They may be 32-bit or 30331 64-bit depending on the target. 30332 30333 The `org.gnu.gdb.mips.linux' feature is optional. It should contain 30334 a single register, `restart', which is used by the Linux kernel to 30335 control restartable syscalls. 30336 30337 30338 File: gdb.info, Node: M68K Features, Next: PowerPC Features, Prev: MIPS Features, Up: Standard Target Features 30339 30340 G.4.4 M68K Features 30341 ------------------- 30342 30343 ``org.gnu.gdb.m68k.core'' 30344 ``org.gnu.gdb.coldfire.core'' 30345 ``org.gnu.gdb.fido.core'' 30346 One of those features must be always present. The feature that is 30347 present determines which flavor of m68k is used. The feature that 30348 is present should contain registers `d0' through `d7', `a0' 30349 through `a5', `fp', `sp', `ps' and `pc'. 30350 30351 ``org.gnu.gdb.coldfire.fp'' 30352 This feature is optional. If present, it should contain registers 30353 `fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'. 30354 30355 30356 File: gdb.info, Node: PowerPC Features, Prev: M68K Features, Up: Standard Target Features 30357 30358 G.4.5 PowerPC Features 30359 ---------------------- 30360 30361 The `org.gnu.gdb.power.core' feature is required for PowerPC targets. 30362 It should contain registers `r0' through `r31', `pc', `msr', `cr', 30363 `lr', `ctr', and `xer'. They may be 32-bit or 64-bit depending on the 30364 target. 30365 30366 The `org.gnu.gdb.power.fpu' feature is optional. It should contain 30367 registers `f0' through `f31' and `fpscr'. 30368 30369 The `org.gnu.gdb.power.altivec' feature is optional. It should 30370 contain registers `vr0' through `vr31', `vscr', and `vrsave'. 30371 30372 The `org.gnu.gdb.power.vsx' feature is optional. It should contain 30373 registers `vs0h' through `vs31h'. GDB will combine these registers 30374 with the floating point registers (`f0' through `f31') and the altivec 30375 registers (`vr0' through `vr31') to present the 128-bit wide registers 30376 `vs0' through `vs63', the set of vector registers for POWER7. 30377 30378 The `org.gnu.gdb.power.spe' feature is optional. It should contain 30379 registers `ev0h' through `ev31h', `acc', and `spefscr'. SPE targets 30380 should provide 32-bit registers in `org.gnu.gdb.power.core' and provide 30381 the upper halves in `ev0h' through `ev31h'. GDB will combine these to 30382 present registers `ev0' through `ev31' to the user. 30383 30384 30385 File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top 30386 30387 Appendix H Operating System Information 30388 *************************************** 30389 30390 * Menu: 30391 30392 * Process list:: 30393 30394 Users of GDB often wish to obtain information about the state of the 30395 operating system running on the target--for example the list of 30396 processes, or the list of open files. This section describes the 30397 mechanism that makes it possible. This mechanism is similar to the 30398 target features mechanism (*note Target Descriptions::), but focuses on 30399 a different aspect of target. 30400 30401 Operating system information is retrived from the target via the 30402 remote protocol, using `qXfer' requests (*note qXfer osdata read::). 30403 The object name in the request should be `osdata', and the ANNEX 30404 identifies the data to be fetched. 30405 30406 30407 File: gdb.info, Node: Process list, Up: Operating System Information 30408 30409 H.1 Process list 30410 ================ 30411 30412 When requesting the process list, the ANNEX field in the `qXfer' 30413 request should be `processes'. The returned data is an XML document. 30414 The formal syntax of this document is defined in 30415 `gdb/features/osdata.dtd'. 30416 30417 An example document is: 30418 30419 <?xml version="1.0"?> 30420 <!DOCTYPE target SYSTEM "osdata.dtd"> 30421 <osdata type="processes"> 30422 <item> 30423 <column name="pid">1</column> 30424 <column name="user">root</column> 30425 <column name="command">/sbin/init</column> 30426 <column name="cores">1,2,3</column> 30427 </item> 30428 </osdata> 30429 30430 Each item should include a column whose name is `pid'. The value of 30431 that column should identify the process on the target. The `user' and 30432 `command' columns are optional, and will be displayed by GDB. The 30433 `cores' column, if present, should contain a comma-separated list of 30434 cores that this process is running on. Target may provide additional 30435 columns, which GDB currently ignores. 30436 30437 30438 File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Trace File Format, Up: Top 30439 30440 Appendix I GNU GENERAL PUBLIC LICENSE 30441 ************************************* 30442 30443 Version 3, 29 June 2007 30444 30445 Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/' 30446 30447 Everyone is permitted to copy and distribute verbatim copies of this 30448 license document, but changing it is not allowed. 30449 30450 Preamble 30451 ======== 30452 30453 The GNU General Public License is a free, copyleft license for software 30454 and other kinds of works. 30455 30456 The licenses for most software and other practical works are designed 30457 to take away your freedom to share and change the works. By contrast, 30458 the GNU General Public License is intended to guarantee your freedom to 30459 share and change all versions of a program--to make sure it remains 30460 free software for all its users. We, the Free Software Foundation, use 30461 the GNU General Public License for most of our software; it applies 30462 also to any other work released this way by its authors. You can apply 30463 it to your programs, too. 30464 30465 When we speak of free software, we are referring to freedom, not 30466 price. Our General Public Licenses are designed to make sure that you 30467 have the freedom to distribute copies of free software (and charge for 30468 them if you wish), that you receive source code or can get it if you 30469 want it, that you can change the software or use pieces of it in new 30470 free programs, and that you know you can do these things. 30471 30472 To protect your rights, we need to prevent others from denying you 30473 these rights or asking you to surrender the rights. Therefore, you 30474 have certain responsibilities if you distribute copies of the software, 30475 or if you modify it: responsibilities to respect the freedom of others. 30476 30477 For example, if you distribute copies of such a program, whether 30478 gratis or for a fee, you must pass on to the recipients the same 30479 freedoms that you received. You must make sure that they, too, receive 30480 or can get the source code. And you must show them these terms so they 30481 know their rights. 30482 30483 Developers that use the GNU GPL protect your rights with two steps: 30484 (1) assert copyright on the software, and (2) offer you this License 30485 giving you legal permission to copy, distribute and/or modify it. 30486 30487 For the developers' and authors' protection, the GPL clearly explains 30488 that there is no warranty for this free software. For both users' and 30489 authors' sake, the GPL requires that modified versions be marked as 30490 changed, so that their problems will not be attributed erroneously to 30491 authors of previous versions. 30492 30493 Some devices are designed to deny users access to install or run 30494 modified versions of the software inside them, although the 30495 manufacturer can do so. This is fundamentally incompatible with the 30496 aim of protecting users' freedom to change the software. The 30497 systematic pattern of such abuse occurs in the area of products for 30498 individuals to use, which is precisely where it is most unacceptable. 30499 Therefore, we have designed this version of the GPL to prohibit the 30500 practice for those products. If such problems arise substantially in 30501 other domains, we stand ready to extend this provision to those domains 30502 in future versions of the GPL, as needed to protect the freedom of 30503 users. 30504 30505 Finally, every program is threatened constantly by software patents. 30506 States should not allow patents to restrict development and use of 30507 software on general-purpose computers, but in those that do, we wish to 30508 avoid the special danger that patents applied to a free program could 30509 make it effectively proprietary. To prevent this, the GPL assures that 30510 patents cannot be used to render the program non-free. 30511 30512 The precise terms and conditions for copying, distribution and 30513 modification follow. 30514 30515 TERMS AND CONDITIONS 30516 ==================== 30517 30518 0. Definitions. 30519 30520 "This License" refers to version 3 of the GNU General Public 30521 License. 30522 30523 "Copyright" also means copyright-like laws that apply to other 30524 kinds of works, such as semiconductor masks. 30525 30526 "The Program" refers to any copyrightable work licensed under this 30527 License. Each licensee is addressed as "you". "Licensees" and 30528 "recipients" may be individuals or organizations. 30529 30530 To "modify" a work means to copy from or adapt all or part of the 30531 work in a fashion requiring copyright permission, other than the 30532 making of an exact copy. The resulting work is called a "modified 30533 version" of the earlier work or a work "based on" the earlier work. 30534 30535 A "covered work" means either the unmodified Program or a work 30536 based on the Program. 30537 30538 To "propagate" a work means to do anything with it that, without 30539 permission, would make you directly or secondarily liable for 30540 infringement under applicable copyright law, except executing it 30541 on a computer or modifying a private copy. Propagation includes 30542 copying, distribution (with or without modification), making 30543 available to the public, and in some countries other activities as 30544 well. 30545 30546 To "convey" a work means any kind of propagation that enables other 30547 parties to make or receive copies. Mere interaction with a user 30548 through a computer network, with no transfer of a copy, is not 30549 conveying. 30550 30551 An interactive user interface displays "Appropriate Legal Notices" 30552 to the extent that it includes a convenient and prominently visible 30553 feature that (1) displays an appropriate copyright notice, and (2) 30554 tells the user that there is no warranty for the work (except to 30555 the extent that warranties are provided), that licensees may 30556 convey the work under this License, and how to view a copy of this 30557 License. If the interface presents a list of user commands or 30558 options, such as a menu, a prominent item in the list meets this 30559 criterion. 30560 30561 1. Source Code. 30562 30563 The "source code" for a work means the preferred form of the work 30564 for making modifications to it. "Object code" means any 30565 non-source form of a work. 30566 30567 A "Standard Interface" means an interface that either is an 30568 official standard defined by a recognized standards body, or, in 30569 the case of interfaces specified for a particular programming 30570 language, one that is widely used among developers working in that 30571 language. 30572 30573 The "System Libraries" of an executable work include anything, 30574 other than the work as a whole, that (a) is included in the normal 30575 form of packaging a Major Component, but which is not part of that 30576 Major Component, and (b) serves only to enable use of the work 30577 with that Major Component, or to implement a Standard Interface 30578 for which an implementation is available to the public in source 30579 code form. A "Major Component", in this context, means a major 30580 essential component (kernel, window system, and so on) of the 30581 specific operating system (if any) on which the executable work 30582 runs, or a compiler used to produce the work, or an object code 30583 interpreter used to run it. 30584 30585 The "Corresponding Source" for a work in object code form means all 30586 the source code needed to generate, install, and (for an executable 30587 work) run the object code and to modify the work, including 30588 scripts to control those activities. However, it does not include 30589 the work's System Libraries, or general-purpose tools or generally 30590 available free programs which are used unmodified in performing 30591 those activities but which are not part of the work. For example, 30592 Corresponding Source includes interface definition files 30593 associated with source files for the work, and the source code for 30594 shared libraries and dynamically linked subprograms that the work 30595 is specifically designed to require, such as by intimate data 30596 communication or control flow between those subprograms and other 30597 parts of the work. 30598 30599 The Corresponding Source need not include anything that users can 30600 regenerate automatically from other parts of the Corresponding 30601 Source. 30602 30603 The Corresponding Source for a work in source code form is that 30604 same work. 30605 30606 2. Basic Permissions. 30607 30608 All rights granted under this License are granted for the term of 30609 copyright on the Program, and are irrevocable provided the stated 30610 conditions are met. This License explicitly affirms your unlimited 30611 permission to run the unmodified Program. The output from running 30612 a covered work is covered by this License only if the output, 30613 given its content, constitutes a covered work. This License 30614 acknowledges your rights of fair use or other equivalent, as 30615 provided by copyright law. 30616 30617 You may make, run and propagate covered works that you do not 30618 convey, without conditions so long as your license otherwise 30619 remains in force. You may convey covered works to others for the 30620 sole purpose of having them make modifications exclusively for 30621 you, or provide you with facilities for running those works, 30622 provided that you comply with the terms of this License in 30623 conveying all material for which you do not control copyright. 30624 Those thus making or running the covered works for you must do so 30625 exclusively on your behalf, under your direction and control, on 30626 terms that prohibit them from making any copies of your 30627 copyrighted material outside their relationship with you. 30628 30629 Conveying under any other circumstances is permitted solely under 30630 the conditions stated below. Sublicensing is not allowed; section 30631 10 makes it unnecessary. 30632 30633 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 30634 30635 No covered work shall be deemed part of an effective technological 30636 measure under any applicable law fulfilling obligations under 30637 article 11 of the WIPO copyright treaty adopted on 20 December 30638 1996, or similar laws prohibiting or restricting circumvention of 30639 such measures. 30640 30641 When you convey a covered work, you waive any legal power to forbid 30642 circumvention of technological measures to the extent such 30643 circumvention is effected by exercising rights under this License 30644 with respect to the covered work, and you disclaim any intention 30645 to limit operation or modification of the work as a means of 30646 enforcing, against the work's users, your or third parties' legal 30647 rights to forbid circumvention of technological measures. 30648 30649 4. Conveying Verbatim Copies. 30650 30651 You may convey verbatim copies of the Program's source code as you 30652 receive it, in any medium, provided that you conspicuously and 30653 appropriately publish on each copy an appropriate copyright notice; 30654 keep intact all notices stating that this License and any 30655 non-permissive terms added in accord with section 7 apply to the 30656 code; keep intact all notices of the absence of any warranty; and 30657 give all recipients a copy of this License along with the Program. 30658 30659 You may charge any price or no price for each copy that you convey, 30660 and you may offer support or warranty protection for a fee. 30661 30662 5. Conveying Modified Source Versions. 30663 30664 You may convey a work based on the Program, or the modifications to 30665 produce it from the Program, in the form of source code under the 30666 terms of section 4, provided that you also meet all of these 30667 conditions: 30668 30669 a. The work must carry prominent notices stating that you 30670 modified it, and giving a relevant date. 30671 30672 b. The work must carry prominent notices stating that it is 30673 released under this License and any conditions added under 30674 section 7. This requirement modifies the requirement in 30675 section 4 to "keep intact all notices". 30676 30677 c. You must license the entire work, as a whole, under this 30678 License to anyone who comes into possession of a copy. This 30679 License will therefore apply, along with any applicable 30680 section 7 additional terms, to the whole of the work, and all 30681 its parts, regardless of how they are packaged. This License 30682 gives no permission to license the work in any other way, but 30683 it does not invalidate such permission if you have separately 30684 received it. 30685 30686 d. If the work has interactive user interfaces, each must display 30687 Appropriate Legal Notices; however, if the Program has 30688 interactive interfaces that do not display Appropriate Legal 30689 Notices, your work need not make them do so. 30690 30691 A compilation of a covered work with other separate and independent 30692 works, which are not by their nature extensions of the covered 30693 work, and which are not combined with it such as to form a larger 30694 program, in or on a volume of a storage or distribution medium, is 30695 called an "aggregate" if the compilation and its resulting 30696 copyright are not used to limit the access or legal rights of the 30697 compilation's users beyond what the individual works permit. 30698 Inclusion of a covered work in an aggregate does not cause this 30699 License to apply to the other parts of the aggregate. 30700 30701 6. Conveying Non-Source Forms. 30702 30703 You may convey a covered work in object code form under the terms 30704 of sections 4 and 5, provided that you also convey the 30705 machine-readable Corresponding Source under the terms of this 30706 License, in one of these ways: 30707 30708 a. Convey the object code in, or embodied in, a physical product 30709 (including a physical distribution medium), accompanied by the 30710 Corresponding Source fixed on a durable physical medium 30711 customarily used for software interchange. 30712 30713 b. Convey the object code in, or embodied in, a physical product 30714 (including a physical distribution medium), accompanied by a 30715 written offer, valid for at least three years and valid for 30716 as long as you offer spare parts or customer support for that 30717 product model, to give anyone who possesses the object code 30718 either (1) a copy of the Corresponding Source for all the 30719 software in the product that is covered by this License, on a 30720 durable physical medium customarily used for software 30721 interchange, for a price no more than your reasonable cost of 30722 physically performing this conveying of source, or (2) access 30723 to copy the Corresponding Source from a network server at no 30724 charge. 30725 30726 c. Convey individual copies of the object code with a copy of 30727 the written offer to provide the Corresponding Source. This 30728 alternative is allowed only occasionally and noncommercially, 30729 and only if you received the object code with such an offer, 30730 in accord with subsection 6b. 30731 30732 d. Convey the object code by offering access from a designated 30733 place (gratis or for a charge), and offer equivalent access 30734 to the Corresponding Source in the same way through the same 30735 place at no further charge. You need not require recipients 30736 to copy the Corresponding Source along with the object code. 30737 If the place to copy the object code is a network server, the 30738 Corresponding Source may be on a different server (operated 30739 by you or a third party) that supports equivalent copying 30740 facilities, provided you maintain clear directions next to 30741 the object code saying where to find the Corresponding Source. 30742 Regardless of what server hosts the Corresponding Source, you 30743 remain obligated to ensure that it is available for as long 30744 as needed to satisfy these requirements. 30745 30746 e. Convey the object code using peer-to-peer transmission, 30747 provided you inform other peers where the object code and 30748 Corresponding Source of the work are being offered to the 30749 general public at no charge under subsection 6d. 30750 30751 30752 A separable portion of the object code, whose source code is 30753 excluded from the Corresponding Source as a System Library, need 30754 not be included in conveying the object code work. 30755 30756 A "User Product" is either (1) a "consumer product", which means 30757 any tangible personal property which is normally used for personal, 30758 family, or household purposes, or (2) anything designed or sold for 30759 incorporation into a dwelling. In determining whether a product 30760 is a consumer product, doubtful cases shall be resolved in favor of 30761 coverage. For a particular product received by a particular user, 30762 "normally used" refers to a typical or common use of that class of 30763 product, regardless of the status of the particular user or of the 30764 way in which the particular user actually uses, or expects or is 30765 expected to use, the product. A product is a consumer product 30766 regardless of whether the product has substantial commercial, 30767 industrial or non-consumer uses, unless such uses represent the 30768 only significant mode of use of the product. 30769 30770 "Installation Information" for a User Product means any methods, 30771 procedures, authorization keys, or other information required to 30772 install and execute modified versions of a covered work in that 30773 User Product from a modified version of its Corresponding Source. 30774 The information must suffice to ensure that the continued 30775 functioning of the modified object code is in no case prevented or 30776 interfered with solely because modification has been made. 30777 30778 If you convey an object code work under this section in, or with, 30779 or specifically for use in, a User Product, and the conveying 30780 occurs as part of a transaction in which the right of possession 30781 and use of the User Product is transferred to the recipient in 30782 perpetuity or for a fixed term (regardless of how the transaction 30783 is characterized), the Corresponding Source conveyed under this 30784 section must be accompanied by the Installation Information. But 30785 this requirement does not apply if neither you nor any third party 30786 retains the ability to install modified object code on the User 30787 Product (for example, the work has been installed in ROM). 30788 30789 The requirement to provide Installation Information does not 30790 include a requirement to continue to provide support service, 30791 warranty, or updates for a work that has been modified or 30792 installed by the recipient, or for the User Product in which it 30793 has been modified or installed. Access to a network may be denied 30794 when the modification itself materially and adversely affects the 30795 operation of the network or violates the rules and protocols for 30796 communication across the network. 30797 30798 Corresponding Source conveyed, and Installation Information 30799 provided, in accord with this section must be in a format that is 30800 publicly documented (and with an implementation available to the 30801 public in source code form), and must require no special password 30802 or key for unpacking, reading or copying. 30803 30804 7. Additional Terms. 30805 30806 "Additional permissions" are terms that supplement the terms of 30807 this License by making exceptions from one or more of its 30808 conditions. Additional permissions that are applicable to the 30809 entire Program shall be treated as though they were included in 30810 this License, to the extent that they are valid under applicable 30811 law. If additional permissions apply only to part of the Program, 30812 that part may be used separately under those permissions, but the 30813 entire Program remains governed by this License without regard to 30814 the additional permissions. 30815 30816 When you convey a copy of a covered work, you may at your option 30817 remove any additional permissions from that copy, or from any part 30818 of it. (Additional permissions may be written to require their own 30819 removal in certain cases when you modify the work.) You may place 30820 additional permissions on material, added by you to a covered work, 30821 for which you have or can give appropriate copyright permission. 30822 30823 Notwithstanding any other provision of this License, for material 30824 you add to a covered work, you may (if authorized by the copyright 30825 holders of that material) supplement the terms of this License 30826 with terms: 30827 30828 a. Disclaiming warranty or limiting liability differently from 30829 the terms of sections 15 and 16 of this License; or 30830 30831 b. Requiring preservation of specified reasonable legal notices 30832 or author attributions in that material or in the Appropriate 30833 Legal Notices displayed by works containing it; or 30834 30835 c. Prohibiting misrepresentation of the origin of that material, 30836 or requiring that modified versions of such material be 30837 marked in reasonable ways as different from the original 30838 version; or 30839 30840 d. Limiting the use for publicity purposes of names of licensors 30841 or authors of the material; or 30842 30843 e. Declining to grant rights under trademark law for use of some 30844 trade names, trademarks, or service marks; or 30845 30846 f. Requiring indemnification of licensors and authors of that 30847 material by anyone who conveys the material (or modified 30848 versions of it) with contractual assumptions of liability to 30849 the recipient, for any liability that these contractual 30850 assumptions directly impose on those licensors and authors. 30851 30852 All other non-permissive additional terms are considered "further 30853 restrictions" within the meaning of section 10. If the Program as 30854 you received it, or any part of it, contains a notice stating that 30855 it is governed by this License along with a term that is a further 30856 restriction, you may remove that term. If a license document 30857 contains a further restriction but permits relicensing or 30858 conveying under this License, you may add to a covered work 30859 material governed by the terms of that license document, provided 30860 that the further restriction does not survive such relicensing or 30861 conveying. 30862 30863 If you add terms to a covered work in accord with this section, you 30864 must place, in the relevant source files, a statement of the 30865 additional terms that apply to those files, or a notice indicating 30866 where to find the applicable terms. 30867 30868 Additional terms, permissive or non-permissive, may be stated in 30869 the form of a separately written license, or stated as exceptions; 30870 the above requirements apply either way. 30871 30872 8. Termination. 30873 30874 You may not propagate or modify a covered work except as expressly 30875 provided under this License. Any attempt otherwise to propagate or 30876 modify it is void, and will automatically terminate your rights 30877 under this License (including any patent licenses granted under 30878 the third paragraph of section 11). 30879 30880 However, if you cease all violation of this License, then your 30881 license from a particular copyright holder is reinstated (a) 30882 provisionally, unless and until the copyright holder explicitly 30883 and finally terminates your license, and (b) permanently, if the 30884 copyright holder fails to notify you of the violation by some 30885 reasonable means prior to 60 days after the cessation. 30886 30887 Moreover, your license from a particular copyright holder is 30888 reinstated permanently if the copyright holder notifies you of the 30889 violation by some reasonable means, this is the first time you have 30890 received notice of violation of this License (for any work) from 30891 that copyright holder, and you cure the violation prior to 30 days 30892 after your receipt of the notice. 30893 30894 Termination of your rights under this section does not terminate 30895 the licenses of parties who have received copies or rights from 30896 you under this License. If your rights have been terminated and 30897 not permanently reinstated, you do not qualify to receive new 30898 licenses for the same material under section 10. 30899 30900 9. Acceptance Not Required for Having Copies. 30901 30902 You are not required to accept this License in order to receive or 30903 run a copy of the Program. Ancillary propagation of a covered work 30904 occurring solely as a consequence of using peer-to-peer 30905 transmission to receive a copy likewise does not require 30906 acceptance. However, nothing other than this License grants you 30907 permission to propagate or modify any covered work. These actions 30908 infringe copyright if you do not accept this License. Therefore, 30909 by modifying or propagating a covered work, you indicate your 30910 acceptance of this License to do so. 30911 30912 10. Automatic Licensing of Downstream Recipients. 30913 30914 Each time you convey a covered work, the recipient automatically 30915 receives a license from the original licensors, to run, modify and 30916 propagate that work, subject to this License. You are not 30917 responsible for enforcing compliance by third parties with this 30918 License. 30919 30920 An "entity transaction" is a transaction transferring control of an 30921 organization, or substantially all assets of one, or subdividing an 30922 organization, or merging organizations. If propagation of a 30923 covered work results from an entity transaction, each party to that 30924 transaction who receives a copy of the work also receives whatever 30925 licenses to the work the party's predecessor in interest had or 30926 could give under the previous paragraph, plus a right to 30927 possession of the Corresponding Source of the work from the 30928 predecessor in interest, if the predecessor has it or can get it 30929 with reasonable efforts. 30930 30931 You may not impose any further restrictions on the exercise of the 30932 rights granted or affirmed under this License. For example, you 30933 may not impose a license fee, royalty, or other charge for 30934 exercise of rights granted under this License, and you may not 30935 initiate litigation (including a cross-claim or counterclaim in a 30936 lawsuit) alleging that any patent claim is infringed by making, 30937 using, selling, offering for sale, or importing the Program or any 30938 portion of it. 30939 30940 11. Patents. 30941 30942 A "contributor" is a copyright holder who authorizes use under this 30943 License of the Program or a work on which the Program is based. 30944 The work thus licensed is called the contributor's "contributor 30945 version". 30946 30947 A contributor's "essential patent claims" are all patent claims 30948 owned or controlled by the contributor, whether already acquired or 30949 hereafter acquired, that would be infringed by some manner, 30950 permitted by this License, of making, using, or selling its 30951 contributor version, but do not include claims that would be 30952 infringed only as a consequence of further modification of the 30953 contributor version. For purposes of this definition, "control" 30954 includes the right to grant patent sublicenses in a manner 30955 consistent with the requirements of this License. 30956 30957 Each contributor grants you a non-exclusive, worldwide, 30958 royalty-free patent license under the contributor's essential 30959 patent claims, to make, use, sell, offer for sale, import and 30960 otherwise run, modify and propagate the contents of its 30961 contributor version. 30962 30963 In the following three paragraphs, a "patent license" is any 30964 express agreement or commitment, however denominated, not to 30965 enforce a patent (such as an express permission to practice a 30966 patent or covenant not to sue for patent infringement). To 30967 "grant" such a patent license to a party means to make such an 30968 agreement or commitment not to enforce a patent against the party. 30969 30970 If you convey a covered work, knowingly relying on a patent 30971 license, and the Corresponding Source of the work is not available 30972 for anyone to copy, free of charge and under the terms of this 30973 License, through a publicly available network server or other 30974 readily accessible means, then you must either (1) cause the 30975 Corresponding Source to be so available, or (2) arrange to deprive 30976 yourself of the benefit of the patent license for this particular 30977 work, or (3) arrange, in a manner consistent with the requirements 30978 of this License, to extend the patent license to downstream 30979 recipients. "Knowingly relying" means you have actual knowledge 30980 that, but for the patent license, your conveying the covered work 30981 in a country, or your recipient's use of the covered work in a 30982 country, would infringe one or more identifiable patents in that 30983 country that you have reason to believe are valid. 30984 30985 If, pursuant to or in connection with a single transaction or 30986 arrangement, you convey, or propagate by procuring conveyance of, a 30987 covered work, and grant a patent license to some of the parties 30988 receiving the covered work authorizing them to use, propagate, 30989 modify or convey a specific copy of the covered work, then the 30990 patent license you grant is automatically extended to all 30991 recipients of the covered work and works based on it. 30992 30993 A patent license is "discriminatory" if it does not include within 30994 the scope of its coverage, prohibits the exercise of, or is 30995 conditioned on the non-exercise of one or more of the rights that 30996 are specifically granted under this License. You may not convey a 30997 covered work if you are a party to an arrangement with a third 30998 party that is in the business of distributing software, under 30999 which you make payment to the third party based on the extent of 31000 your activity of conveying the work, and under which the third 31001 party grants, to any of the parties who would receive the covered 31002 work from you, a discriminatory patent license (a) in connection 31003 with copies of the covered work conveyed by you (or copies made 31004 from those copies), or (b) primarily for and in connection with 31005 specific products or compilations that contain the covered work, 31006 unless you entered into that arrangement, or that patent license 31007 was granted, prior to 28 March 2007. 31008 31009 Nothing in this License shall be construed as excluding or limiting 31010 any implied license or other defenses to infringement that may 31011 otherwise be available to you under applicable patent law. 31012 31013 12. No Surrender of Others' Freedom. 31014 31015 If conditions are imposed on you (whether by court order, 31016 agreement or otherwise) that contradict the conditions of this 31017 License, they do not excuse you from the conditions of this 31018 License. If you cannot convey a covered work so as to satisfy 31019 simultaneously your obligations under this License and any other 31020 pertinent obligations, then as a consequence you may not convey it 31021 at all. For example, if you agree to terms that obligate you to 31022 collect a royalty for further conveying from those to whom you 31023 convey the Program, the only way you could satisfy both those 31024 terms and this License would be to refrain entirely from conveying 31025 the Program. 31026 31027 13. Use with the GNU Affero General Public License. 31028 31029 Notwithstanding any other provision of this License, you have 31030 permission to link or combine any covered work with a work licensed 31031 under version 3 of the GNU Affero General Public License into a 31032 single combined work, and to convey the resulting work. The terms 31033 of this License will continue to apply to the part which is the 31034 covered work, but the special requirements of the GNU Affero 31035 General Public License, section 13, concerning interaction through 31036 a network will apply to the combination as such. 31037 31038 14. Revised Versions of this License. 31039 31040 The Free Software Foundation may publish revised and/or new 31041 versions of the GNU General Public License from time to time. 31042 Such new versions will be similar in spirit to the present 31043 version, but may differ in detail to address new problems or 31044 concerns. 31045 31046 Each version is given a distinguishing version number. If the 31047 Program specifies that a certain numbered version of the GNU 31048 General Public License "or any later version" applies to it, you 31049 have the option of following the terms and conditions either of 31050 that numbered version or of any later version published by the 31051 Free Software Foundation. If the Program does not specify a 31052 version number of the GNU General Public License, you may choose 31053 any version ever published by the Free Software Foundation. 31054 31055 If the Program specifies that a proxy can decide which future 31056 versions of the GNU General Public License can be used, that 31057 proxy's public statement of acceptance of a version permanently 31058 authorizes you to choose that version for the Program. 31059 31060 Later license versions may give you additional or different 31061 permissions. However, no additional obligations are imposed on any 31062 author or copyright holder as a result of your choosing to follow a 31063 later version. 31064 31065 15. Disclaimer of Warranty. 31066 31067 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 31068 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE 31069 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" 31070 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 31071 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 31072 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE 31073 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. 31074 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 31075 NECESSARY SERVICING, REPAIR OR CORRECTION. 31076 31077 16. Limitation of Liability. 31078 31079 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 31080 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES 31081 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU 31082 FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR 31083 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE 31084 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA 31085 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 31086 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 31087 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF 31088 THE POSSIBILITY OF SUCH DAMAGES. 31089 31090 17. Interpretation of Sections 15 and 16. 31091 31092 If the disclaimer of warranty and limitation of liability provided 31093 above cannot be given local legal effect according to their terms, 31094 reviewing courts shall apply local law that most closely 31095 approximates an absolute waiver of all civil liability in 31096 connection with the Program, unless a warranty or assumption of 31097 liability accompanies a copy of the Program in return for a fee. 31098 31099 31100 END OF TERMS AND CONDITIONS 31101 =========================== 31102 31103 How to Apply These Terms to Your New Programs 31104 ============================================= 31105 31106 If you develop a new program, and you want it to be of the greatest 31107 possible use to the public, the best way to achieve this is to make it 31108 free software which everyone can redistribute and change under these 31109 terms. 31110 31111 To do so, attach the following notices to the program. It is safest 31112 to attach them to the start of each source file to most effectively 31113 state the exclusion of warranty; and each file should have at least the 31114 "copyright" line and a pointer to where the full notice is found. 31115 31116 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. 31117 Copyright (C) YEAR NAME OF AUTHOR 31118 31119 This program is free software: you can redistribute it and/or modify 31120 it under the terms of the GNU General Public License as published by 31121 the Free Software Foundation, either version 3 of the License, or (at 31122 your option) any later version. 31123 31124 This program is distributed in the hope that it will be useful, but 31125 WITHOUT ANY WARRANTY; without even the implied warranty of 31126 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 31127 General Public License for more details. 31128 31129 You should have received a copy of the GNU General Public License 31130 along with this program. If not, see `http://www.gnu.org/licenses/'. 31131 31132 Also add information on how to contact you by electronic and paper 31133 mail. 31134 31135 If the program does terminal interaction, make it output a short 31136 notice like this when it starts in an interactive mode: 31137 31138 PROGRAM Copyright (C) YEAR NAME OF AUTHOR 31139 This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 31140 This is free software, and you are welcome to redistribute it 31141 under certain conditions; type `show c' for details. 31142 31143 The hypothetical commands `show w' and `show c' should show the 31144 appropriate parts of the General Public License. Of course, your 31145 program's commands might be different; for a GUI interface, you would 31146 use an "about box". 31147 31148 You should also get your employer (if you work as a programmer) or 31149 school, if any, to sign a "copyright disclaimer" for the program, if 31150 necessary. For more information on this, and how to apply and follow 31151 the GNU GPL, see `http://www.gnu.org/licenses/'. 31152 31153 The GNU General Public License does not permit incorporating your 31154 program into proprietary programs. If your program is a subroutine 31155 library, you may consider it more useful to permit linking proprietary 31156 applications with the library. If this is what you want to do, use the 31157 GNU Lesser General Public License instead of this License. But first, 31158 please read `http://www.gnu.org/philosophy/why-not-lgpl.html'. 31159 31160 31161 File: gdb.info, Node: GNU Free Documentation License, Next: Index, Prev: Copying, Up: Top 31162 31163 Appendix J GNU Free Documentation License 31164 ***************************************** 31165 31166 Version 1.2, November 2002 31167 31168 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 31169 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 31170 31171 Everyone is permitted to copy and distribute verbatim copies 31172 of this license document, but changing it is not allowed. 31173 31174 0. PREAMBLE 31175 31176 The purpose of this License is to make a manual, textbook, or other 31177 functional and useful document "free" in the sense of freedom: to 31178 assure everyone the effective freedom to copy and redistribute it, 31179 with or without modifying it, either commercially or 31180 noncommercially. Secondarily, this License preserves for the 31181 author and publisher a way to get credit for their work, while not 31182 being considered responsible for modifications made by others. 31183 31184 This License is a kind of "copyleft", which means that derivative 31185 works of the document must themselves be free in the same sense. 31186 It complements the GNU General Public License, which is a copyleft 31187 license designed for free software. 31188 31189 We have designed this License in order to use it for manuals for 31190 free software, because free software needs free documentation: a 31191 free program should come with manuals providing the same freedoms 31192 that the software does. But this License is not limited to 31193 software manuals; it can be used for any textual work, regardless 31194 of subject matter or whether it is published as a printed book. 31195 We recommend this License principally for works whose purpose is 31196 instruction or reference. 31197 31198 1. APPLICABILITY AND DEFINITIONS 31199 31200 This License applies to any manual or other work, in any medium, 31201 that contains a notice placed by the copyright holder saying it 31202 can be distributed under the terms of this License. Such a notice 31203 grants a world-wide, royalty-free license, unlimited in duration, 31204 to use that work under the conditions stated herein. The 31205 "Document", below, refers to any such manual or work. Any member 31206 of the public is a licensee, and is addressed as "you". You 31207 accept the license if you copy, modify or distribute the work in a 31208 way requiring permission under copyright law. 31209 31210 A "Modified Version" of the Document means any work containing the 31211 Document or a portion of it, either copied verbatim, or with 31212 modifications and/or translated into another language. 31213 31214 A "Secondary Section" is a named appendix or a front-matter section 31215 of the Document that deals exclusively with the relationship of the 31216 publishers or authors of the Document to the Document's overall 31217 subject (or to related matters) and contains nothing that could 31218 fall directly within that overall subject. (Thus, if the Document 31219 is in part a textbook of mathematics, a Secondary Section may not 31220 explain any mathematics.) The relationship could be a matter of 31221 historical connection with the subject or with related matters, or 31222 of legal, commercial, philosophical, ethical or political position 31223 regarding them. 31224 31225 The "Invariant Sections" are certain Secondary Sections whose 31226 titles are designated, as being those of Invariant Sections, in 31227 the notice that says that the Document is released under this 31228 License. If a section does not fit the above definition of 31229 Secondary then it is not allowed to be designated as Invariant. 31230 The Document may contain zero Invariant Sections. If the Document 31231 does not identify any Invariant Sections then there are none. 31232 31233 The "Cover Texts" are certain short passages of text that are 31234 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 31235 that says that the Document is released under this License. A 31236 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 31237 be at most 25 words. 31238 31239 A "Transparent" copy of the Document means a machine-readable copy, 31240 represented in a format whose specification is available to the 31241 general public, that is suitable for revising the document 31242 straightforwardly with generic text editors or (for images 31243 composed of pixels) generic paint programs or (for drawings) some 31244 widely available drawing editor, and that is suitable for input to 31245 text formatters or for automatic translation to a variety of 31246 formats suitable for input to text formatters. A copy made in an 31247 otherwise Transparent file format whose markup, or absence of 31248 markup, has been arranged to thwart or discourage subsequent 31249 modification by readers is not Transparent. An image format is 31250 not Transparent if used for any substantial amount of text. A 31251 copy that is not "Transparent" is called "Opaque". 31252 31253 Examples of suitable formats for Transparent copies include plain 31254 ASCII without markup, Texinfo input format, LaTeX input format, 31255 SGML or XML using a publicly available DTD, and 31256 standard-conforming simple HTML, PostScript or PDF designed for 31257 human modification. Examples of transparent image formats include 31258 PNG, XCF and JPG. Opaque formats include proprietary formats that 31259 can be read and edited only by proprietary word processors, SGML or 31260 XML for which the DTD and/or processing tools are not generally 31261 available, and the machine-generated HTML, PostScript or PDF 31262 produced by some word processors for output purposes only. 31263 31264 The "Title Page" means, for a printed book, the title page itself, 31265 plus such following pages as are needed to hold, legibly, the 31266 material this License requires to appear in the title page. For 31267 works in formats which do not have any title page as such, "Title 31268 Page" means the text near the most prominent appearance of the 31269 work's title, preceding the beginning of the body of the text. 31270 31271 A section "Entitled XYZ" means a named subunit of the Document 31272 whose title either is precisely XYZ or contains XYZ in parentheses 31273 following text that translates XYZ in another language. (Here XYZ 31274 stands for a specific section name mentioned below, such as 31275 "Acknowledgements", "Dedications", "Endorsements", or "History".) 31276 To "Preserve the Title" of such a section when you modify the 31277 Document means that it remains a section "Entitled XYZ" according 31278 to this definition. 31279 31280 The Document may include Warranty Disclaimers next to the notice 31281 which states that this License applies to the Document. These 31282 Warranty Disclaimers are considered to be included by reference in 31283 this License, but only as regards disclaiming warranties: any other 31284 implication that these Warranty Disclaimers may have is void and 31285 has no effect on the meaning of this License. 31286 31287 2. VERBATIM COPYING 31288 31289 You may copy and distribute the Document in any medium, either 31290 commercially or noncommercially, provided that this License, the 31291 copyright notices, and the license notice saying this License 31292 applies to the Document are reproduced in all copies, and that you 31293 add no other conditions whatsoever to those of this License. You 31294 may not use technical measures to obstruct or control the reading 31295 or further copying of the copies you make or distribute. However, 31296 you may accept compensation in exchange for copies. If you 31297 distribute a large enough number of copies you must also follow 31298 the conditions in section 3. 31299 31300 You may also lend copies, under the same conditions stated above, 31301 and you may publicly display copies. 31302 31303 3. COPYING IN QUANTITY 31304 31305 If you publish printed copies (or copies in media that commonly 31306 have printed covers) of the Document, numbering more than 100, and 31307 the Document's license notice requires Cover Texts, you must 31308 enclose the copies in covers that carry, clearly and legibly, all 31309 these Cover Texts: Front-Cover Texts on the front cover, and 31310 Back-Cover Texts on the back cover. Both covers must also clearly 31311 and legibly identify you as the publisher of these copies. The 31312 front cover must present the full title with all words of the 31313 title equally prominent and visible. You may add other material 31314 on the covers in addition. Copying with changes limited to the 31315 covers, as long as they preserve the title of the Document and 31316 satisfy these conditions, can be treated as verbatim copying in 31317 other respects. 31318 31319 If the required texts for either cover are too voluminous to fit 31320 legibly, you should put the first ones listed (as many as fit 31321 reasonably) on the actual cover, and continue the rest onto 31322 adjacent pages. 31323 31324 If you publish or distribute Opaque copies of the Document 31325 numbering more than 100, you must either include a 31326 machine-readable Transparent copy along with each Opaque copy, or 31327 state in or with each Opaque copy a computer-network location from 31328 which the general network-using public has access to download 31329 using public-standard network protocols a complete Transparent 31330 copy of the Document, free of added material. If you use the 31331 latter option, you must take reasonably prudent steps, when you 31332 begin distribution of Opaque copies in quantity, to ensure that 31333 this Transparent copy will remain thus accessible at the stated 31334 location until at least one year after the last time you 31335 distribute an Opaque copy (directly or through your agents or 31336 retailers) of that edition to the public. 31337 31338 It is requested, but not required, that you contact the authors of 31339 the Document well before redistributing any large number of 31340 copies, to give them a chance to provide you with an updated 31341 version of the Document. 31342 31343 4. MODIFICATIONS 31344 31345 You may copy and distribute a Modified Version of the Document 31346 under the conditions of sections 2 and 3 above, provided that you 31347 release the Modified Version under precisely this License, with 31348 the Modified Version filling the role of the Document, thus 31349 licensing distribution and modification of the Modified Version to 31350 whoever possesses a copy of it. In addition, you must do these 31351 things in the Modified Version: 31352 31353 A. Use in the Title Page (and on the covers, if any) a title 31354 distinct from that of the Document, and from those of 31355 previous versions (which should, if there were any, be listed 31356 in the History section of the Document). You may use the 31357 same title as a previous version if the original publisher of 31358 that version gives permission. 31359 31360 B. List on the Title Page, as authors, one or more persons or 31361 entities responsible for authorship of the modifications in 31362 the Modified Version, together with at least five of the 31363 principal authors of the Document (all of its principal 31364 authors, if it has fewer than five), unless they release you 31365 from this requirement. 31366 31367 C. State on the Title page the name of the publisher of the 31368 Modified Version, as the publisher. 31369 31370 D. Preserve all the copyright notices of the Document. 31371 31372 E. Add an appropriate copyright notice for your modifications 31373 adjacent to the other copyright notices. 31374 31375 F. Include, immediately after the copyright notices, a license 31376 notice giving the public permission to use the Modified 31377 Version under the terms of this License, in the form shown in 31378 the Addendum below. 31379 31380 G. Preserve in that license notice the full lists of Invariant 31381 Sections and required Cover Texts given in the Document's 31382 license notice. 31383 31384 H. Include an unaltered copy of this License. 31385 31386 I. Preserve the section Entitled "History", Preserve its Title, 31387 and add to it an item stating at least the title, year, new 31388 authors, and publisher of the Modified Version as given on 31389 the Title Page. If there is no section Entitled "History" in 31390 the Document, create one stating the title, year, authors, 31391 and publisher of the Document as given on its Title Page, 31392 then add an item describing the Modified Version as stated in 31393 the previous sentence. 31394 31395 J. Preserve the network location, if any, given in the Document 31396 for public access to a Transparent copy of the Document, and 31397 likewise the network locations given in the Document for 31398 previous versions it was based on. These may be placed in 31399 the "History" section. You may omit a network location for a 31400 work that was published at least four years before the 31401 Document itself, or if the original publisher of the version 31402 it refers to gives permission. 31403 31404 K. For any section Entitled "Acknowledgements" or "Dedications", 31405 Preserve the Title of the section, and preserve in the 31406 section all the substance and tone of each of the contributor 31407 acknowledgements and/or dedications given therein. 31408 31409 L. Preserve all the Invariant Sections of the Document, 31410 unaltered in their text and in their titles. Section numbers 31411 or the equivalent are not considered part of the section 31412 titles. 31413 31414 M. Delete any section Entitled "Endorsements". Such a section 31415 may not be included in the Modified Version. 31416 31417 N. Do not retitle any existing section to be Entitled 31418 "Endorsements" or to conflict in title with any Invariant 31419 Section. 31420 31421 O. Preserve any Warranty Disclaimers. 31422 31423 If the Modified Version includes new front-matter sections or 31424 appendices that qualify as Secondary Sections and contain no 31425 material copied from the Document, you may at your option 31426 designate some or all of these sections as invariant. To do this, 31427 add their titles to the list of Invariant Sections in the Modified 31428 Version's license notice. These titles must be distinct from any 31429 other section titles. 31430 31431 You may add a section Entitled "Endorsements", provided it contains 31432 nothing but endorsements of your Modified Version by various 31433 parties--for example, statements of peer review or that the text 31434 has been approved by an organization as the authoritative 31435 definition of a standard. 31436 31437 You may add a passage of up to five words as a Front-Cover Text, 31438 and a passage of up to 25 words as a Back-Cover Text, to the end 31439 of the list of Cover Texts in the Modified Version. Only one 31440 passage of Front-Cover Text and one of Back-Cover Text may be 31441 added by (or through arrangements made by) any one entity. If the 31442 Document already includes a cover text for the same cover, 31443 previously added by you or by arrangement made by the same entity 31444 you are acting on behalf of, you may not add another; but you may 31445 replace the old one, on explicit permission from the previous 31446 publisher that added the old one. 31447 31448 The author(s) and publisher(s) of the Document do not by this 31449 License give permission to use their names for publicity for or to 31450 assert or imply endorsement of any Modified Version. 31451 31452 5. COMBINING DOCUMENTS 31453 31454 You may combine the Document with other documents released under 31455 this License, under the terms defined in section 4 above for 31456 modified versions, provided that you include in the combination 31457 all of the Invariant Sections of all of the original documents, 31458 unmodified, and list them all as Invariant Sections of your 31459 combined work in its license notice, and that you preserve all 31460 their Warranty Disclaimers. 31461 31462 The combined work need only contain one copy of this License, and 31463 multiple identical Invariant Sections may be replaced with a single 31464 copy. If there are multiple Invariant Sections with the same name 31465 but different contents, make the title of each such section unique 31466 by adding at the end of it, in parentheses, the name of the 31467 original author or publisher of that section if known, or else a 31468 unique number. Make the same adjustment to the section titles in 31469 the list of Invariant Sections in the license notice of the 31470 combined work. 31471 31472 In the combination, you must combine any sections Entitled 31473 "History" in the various original documents, forming one section 31474 Entitled "History"; likewise combine any sections Entitled 31475 "Acknowledgements", and any sections Entitled "Dedications". You 31476 must delete all sections Entitled "Endorsements." 31477 31478 6. COLLECTIONS OF DOCUMENTS 31479 31480 You may make a collection consisting of the Document and other 31481 documents released under this License, and replace the individual 31482 copies of this License in the various documents with a single copy 31483 that is included in the collection, provided that you follow the 31484 rules of this License for verbatim copying of each of the 31485 documents in all other respects. 31486 31487 You may extract a single document from such a collection, and 31488 distribute it individually under this License, provided you insert 31489 a copy of this License into the extracted document, and follow 31490 this License in all other respects regarding verbatim copying of 31491 that document. 31492 31493 7. AGGREGATION WITH INDEPENDENT WORKS 31494 31495 A compilation of the Document or its derivatives with other 31496 separate and independent documents or works, in or on a volume of 31497 a storage or distribution medium, is called an "aggregate" if the 31498 copyright resulting from the compilation is not used to limit the 31499 legal rights of the compilation's users beyond what the individual 31500 works permit. When the Document is included in an aggregate, this 31501 License does not apply to the other works in the aggregate which 31502 are not themselves derivative works of the Document. 31503 31504 If the Cover Text requirement of section 3 is applicable to these 31505 copies of the Document, then if the Document is less than one half 31506 of the entire aggregate, the Document's Cover Texts may be placed 31507 on covers that bracket the Document within the aggregate, or the 31508 electronic equivalent of covers if the Document is in electronic 31509 form. Otherwise they must appear on printed covers that bracket 31510 the whole aggregate. 31511 31512 8. TRANSLATION 31513 31514 Translation is considered a kind of modification, so you may 31515 distribute translations of the Document under the terms of section 31516 4. Replacing Invariant Sections with translations requires special 31517 permission from their copyright holders, but you may include 31518 translations of some or all Invariant Sections in addition to the 31519 original versions of these Invariant Sections. You may include a 31520 translation of this License, and all the license notices in the 31521 Document, and any Warranty Disclaimers, provided that you also 31522 include the original English version of this License and the 31523 original versions of those notices and disclaimers. In case of a 31524 disagreement between the translation and the original version of 31525 this License or a notice or disclaimer, the original version will 31526 prevail. 31527 31528 If a section in the Document is Entitled "Acknowledgements", 31529 "Dedications", or "History", the requirement (section 4) to 31530 Preserve its Title (section 1) will typically require changing the 31531 actual title. 31532 31533 9. TERMINATION 31534 31535 You may not copy, modify, sublicense, or distribute the Document 31536 except as expressly provided for under this License. Any other 31537 attempt to copy, modify, sublicense or distribute the Document is 31538 void, and will automatically terminate your rights under this 31539 License. However, parties who have received copies, or rights, 31540 from you under this License will not have their licenses 31541 terminated so long as such parties remain in full compliance. 31542 31543 10. FUTURE REVISIONS OF THIS LICENSE 31544 31545 The Free Software Foundation may publish new, revised versions of 31546 the GNU Free Documentation License from time to time. Such new 31547 versions will be similar in spirit to the present version, but may 31548 differ in detail to address new problems or concerns. See 31549 `http://www.gnu.org/copyleft/'. 31550 31551 Each version of the License is given a distinguishing version 31552 number. If the Document specifies that a particular numbered 31553 version of this License "or any later version" applies to it, you 31554 have the option of following the terms and conditions either of 31555 that specified version or of any later version that has been 31556 published (not as a draft) by the Free Software Foundation. If 31557 the Document does not specify a version number of this License, 31558 you may choose any version ever published (not as a draft) by the 31559 Free Software Foundation. 31560 31561 J.1 ADDENDUM: How to use this License for your documents 31562 ======================================================== 31563 31564 To use this License in a document you have written, include a copy of 31565 the License in the document and put the following copyright and license 31566 notices just after the title page: 31567 31568 Copyright (C) YEAR YOUR NAME. 31569 Permission is granted to copy, distribute and/or modify this document 31570 under the terms of the GNU Free Documentation License, Version 1.2 31571 or any later version published by the Free Software Foundation; 31572 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 31573 Texts. A copy of the license is included in the section entitled ``GNU 31574 Free Documentation License''. 31575 31576 If you have Invariant Sections, Front-Cover Texts and Back-Cover 31577 Texts, replace the "with...Texts." line with this: 31578 31579 with the Invariant Sections being LIST THEIR TITLES, with 31580 the Front-Cover Texts being LIST, and with the Back-Cover Texts 31581 being LIST. 31582 31583 If you have Invariant Sections without Cover Texts, or some other 31584 combination of the three, merge those two alternatives to suit the 31585 situation. 31586 31587 If your document contains nontrivial examples of program code, we 31588 recommend releasing these examples in parallel under your choice of 31589 free software license, such as the GNU General Public License, to 31590 permit their use in free software. 31591 31592 31593 File: gdb.info, Node: Index, Prev: GNU Free Documentation License, Up: Top 31594 31595 Index 31596 ***** 31597 31598 [index] 31599 * Menu: 31600 31601 * ! packet: Packets. (line 49) 31602 * "No symbol "foo" in current context": Variables. (line 74) 31603 * # (a comment): Command Syntax. (line 38) 31604 * # in Modula-2: GDB/M2. (line 18) 31605 * $: Value History. (line 13) 31606 * $$: Value History. (line 13) 31607 * $_ and info breakpoints: Set Breaks. (line 117) 31608 * $_ and info line: Machine Code. (line 30) 31609 * $_, $__, and value history: Memory. (line 101) 31610 * $_, convenience variable: Convenience Vars. (line 64) 31611 * $__, convenience variable: Convenience Vars. (line 73) 31612 * $_exitcode, convenience variable: Convenience Vars. (line 79) 31613 * $_siginfo, convenience variable: Convenience Vars. (line 83) 31614 * $bpnum, convenience variable: Set Breaks. (line 6) 31615 * $cdir, convenience variable: Source Path. (line 108) 31616 * $cwd, convenience variable: Source Path. (line 108) 31617 * $tpnum: Create and Delete Tracepoints. 31618 (line 50) 31619 * $trace_file: Tracepoint Variables. 31620 (line 16) 31621 * $trace_frame: Tracepoint Variables. 31622 (line 6) 31623 * $trace_func: Tracepoint Variables. 31624 (line 19) 31625 * $trace_line: Tracepoint Variables. 31626 (line 13) 31627 * $tracepoint: Tracepoint Variables. 31628 (line 10) 31629 * --annotate: Mode Options. (line 101) 31630 * --args: Mode Options. (line 114) 31631 * --batch: Mode Options. (line 23) 31632 * --batch-silent: Mode Options. (line 39) 31633 * --baud: Mode Options. (line 120) 31634 * --cd: Mode Options. (line 80) 31635 * --command: File Options. (line 51) 31636 * --core: File Options. (line 43) 31637 * --directory: File Options. (line 67) 31638 * --epoch: Mode Options. (line 96) 31639 * --eval-command: File Options. (line 57) 31640 * --exec: File Options. (line 35) 31641 * --fullname: Mode Options. (line 85) 31642 * --interpreter: Mode Options. (line 141) 31643 * --nowindows: Mode Options. (line 70) 31644 * --nx: Mode Options. (line 11) 31645 * --pid: File Options. (line 47) 31646 * --quiet: Mode Options. (line 19) 31647 * --readnow: File Options. (line 71) 31648 * --return-child-result: Mode Options. (line 51) 31649 * --se: File Options. (line 39) 31650 * --silent: Mode Options. (line 19) 31651 * --statistics: Mode Options. (line 158) 31652 * --symbols: File Options. (line 31) 31653 * --tty: Mode Options. (line 129) 31654 * --tui: Mode Options. (line 132) 31655 * --version: Mode Options. (line 162) 31656 * --windows: Mode Options. (line 76) 31657 * --with-gdb-datadir: Data Files. (line 19) 31658 * --with-relocated-sources: Source Path. (line 89) 31659 * --with-sysroot: Files. (line 393) 31660 * --write: Mode Options. (line 153) 31661 * -b: Mode Options. (line 120) 31662 * -break-after: GDB/MI Breakpoint Commands. 31663 (line 11) 31664 * -break-commands: GDB/MI Breakpoint Commands. 31665 (line 55) 31666 * -break-condition: GDB/MI Breakpoint Commands. 31667 (line 88) 31668 * -break-delete: GDB/MI Breakpoint Commands. 31669 (line 125) 31670 * -break-disable: GDB/MI Breakpoint Commands. 31671 (line 159) 31672 * -break-enable: GDB/MI Breakpoint Commands. 31673 (line 195) 31674 * -break-info: GDB/MI Breakpoint Commands. 31675 (line 230) 31676 * -break-insert: GDB/MI Breakpoint Commands. 31677 (line 250) 31678 * -break-list: GDB/MI Breakpoint Commands. 31679 (line 351) 31680 * -break-watch: GDB/MI Breakpoint Commands. 31681 (line 426) 31682 * -c: File Options. (line 43) 31683 * -d: File Options. (line 67) 31684 * -data-disassemble: GDB/MI Data Manipulation. 31685 (line 12) 31686 * -data-evaluate-expression: GDB/MI Data Manipulation. 31687 (line 140) 31688 * -data-list-changed-registers: GDB/MI Data Manipulation. 31689 (line 178) 31690 * -data-list-register-names: GDB/MI Data Manipulation. 31691 (line 214) 31692 * -data-list-register-values: GDB/MI Data Manipulation. 31693 (line 254) 31694 * -data-read-memory: GDB/MI Data Manipulation. 31695 (line 344) 31696 * -e: File Options. (line 35) 31697 * -enable-pretty-printing: GDB/MI Variable Objects. 31698 (line 116) 31699 * -enable-timings: GDB/MI Miscellaneous Commands. 31700 (line 348) 31701 * -environment-cd: GDB/MI Program Context. 31702 (line 33) 31703 * -environment-directory: GDB/MI Program Context. 31704 (line 56) 31705 * -environment-path: GDB/MI Program Context. 31706 (line 100) 31707 * -environment-pwd: GDB/MI Program Context. 31708 (line 141) 31709 * -ex: File Options. (line 57) 31710 * -exec-arguments: GDB/MI Program Context. 31711 (line 9) 31712 * -exec-continue: GDB/MI Program Execution. 31713 (line 13) 31714 * -exec-finish: GDB/MI Program Execution. 31715 (line 56) 31716 * -exec-interrupt: GDB/MI Program Execution. 31717 (line 99) 31718 * -exec-jump: GDB/MI Program Execution. 31719 (line 149) 31720 * -exec-next: GDB/MI Program Execution. 31721 (line 173) 31722 * -exec-next-instruction: GDB/MI Program Execution. 31723 (line 204) 31724 * -exec-return: GDB/MI Program Execution. 31725 (line 240) 31726 * -exec-run: GDB/MI Program Execution. 31727 (line 283) 31728 * -exec-step: GDB/MI Program Execution. 31729 (line 343) 31730 * -exec-step-instruction: GDB/MI Program Execution. 31731 (line 385) 31732 * -exec-until: GDB/MI Program Execution. 31733 (line 426) 31734 * -f: Mode Options. (line 85) 31735 * -file-exec-and-symbols: GDB/MI File Commands. 31736 (line 12) 31737 * -file-exec-file: GDB/MI File Commands. 31738 (line 40) 31739 * -file-list-exec-source-file: GDB/MI File Commands. 31740 (line 67) 31741 * -file-list-exec-source-files: GDB/MI File Commands. 31742 (line 93) 31743 * -file-symbol-file: GDB/MI File Commands. 31744 (line 123) 31745 * -gdb-exit: GDB/MI Miscellaneous Commands. 31746 (line 9) 31747 * -gdb-set: GDB/MI Miscellaneous Commands. 31748 (line 31) 31749 * -gdb-show: GDB/MI Miscellaneous Commands. 31750 (line 54) 31751 * -gdb-version: GDB/MI Miscellaneous Commands. 31752 (line 77) 31753 * -inferior-tty-set: GDB/MI Miscellaneous Commands. 31754 (line 299) 31755 * -inferior-tty-show: GDB/MI Miscellaneous Commands. 31756 (line 322) 31757 * -interpreter-exec: GDB/MI Miscellaneous Commands. 31758 (line 273) 31759 * -l: Mode Options. (line 124) 31760 * -list-features: GDB/MI Miscellaneous Commands. 31761 (line 111) 31762 * -list-target-features: GDB/MI Miscellaneous Commands. 31763 (line 150) 31764 * -list-thread-groups: GDB/MI Miscellaneous Commands. 31765 (line 172) 31766 * -n: Mode Options. (line 11) 31767 * -nw: Mode Options. (line 70) 31768 * -p: File Options. (line 47) 31769 * -q: Mode Options. (line 19) 31770 * -r: File Options. (line 71) 31771 * -s: File Options. (line 31) 31772 * -stack-info-depth: GDB/MI Stack Manipulation. 31773 (line 35) 31774 * -stack-info-frame: GDB/MI Stack Manipulation. 31775 (line 9) 31776 * -stack-list-arguments: GDB/MI Stack Manipulation. 31777 (line 73) 31778 * -stack-list-frames: GDB/MI Stack Manipulation. 31779 (line 162) 31780 * -stack-list-locals: GDB/MI Stack Manipulation. 31781 (line 258) 31782 * -stack-list-variables: GDB/MI Stack Manipulation. 31783 (line 298) 31784 * -stack-select-frame: GDB/MI Stack Manipulation. 31785 (line 321) 31786 * -symbol-list-lines: GDB/MI Symbol Query. (line 9) 31787 * -t: Mode Options. (line 129) 31788 * -target-attach: GDB/MI Target Manipulation. 31789 (line 9) 31790 * -target-detach: GDB/MI Target Manipulation. 31791 (line 36) 31792 * -target-disconnect: GDB/MI Target Manipulation. 31793 (line 61) 31794 * -target-download: GDB/MI Target Manipulation. 31795 (line 85) 31796 * -target-file-delete: GDB/MI File Transfer Commands. 31797 (line 57) 31798 * -target-file-get: GDB/MI File Transfer Commands. 31799 (line 33) 31800 * -target-file-put: GDB/MI File Transfer Commands. 31801 (line 9) 31802 * -target-select: GDB/MI Target Manipulation. 31803 (line 198) 31804 * -thread-info: GDB/MI Thread Commands. 31805 (line 9) 31806 * -thread-list-ids: GDB/MI Thread Commands. 31807 (line 50) 31808 * -thread-select: GDB/MI Thread Commands. 31809 (line 78) 31810 * -var-assign: GDB/MI Variable Objects. 31811 (line 475) 31812 * -var-create: GDB/MI Variable Objects. 31813 (line 134) 31814 * -var-delete: GDB/MI Variable Objects. 31815 (line 220) 31816 * -var-evaluate-expression: GDB/MI Variable Objects. 31817 (line 454) 31818 * -var-info-expression: GDB/MI Variable Objects. 31819 (line 392) 31820 * -var-info-num-children: GDB/MI Variable Objects. 31821 (line 269) 31822 * -var-info-path-expression: GDB/MI Variable Objects. 31823 (line 416) 31824 * -var-info-type: GDB/MI Variable Objects. 31825 (line 379) 31826 * -var-list-children: GDB/MI Variable Objects. 31827 (line 285) 31828 * -var-set-format: GDB/MI Variable Objects. 31829 (line 233) 31830 * -var-set-frozen: GDB/MI Variable Objects. 31831 (line 613) 31832 * -var-set-update-range: GDB/MI Variable Objects. 31833 (line 639) 31834 * -var-set-visualizer: GDB/MI Variable Objects. 31835 (line 662) 31836 * -var-show-attributes: GDB/MI Variable Objects. 31837 (line 440) 31838 * -var-show-format: GDB/MI Variable Objects. 31839 (line 256) 31840 * -var-update: GDB/MI Variable Objects. 31841 (line 499) 31842 * -w: Mode Options. (line 76) 31843 * -x: File Options. (line 51) 31844 * ., Modula-2 scope operator: M2 Scope. (line 6) 31845 * .build-id directory: Separate Debug Files. 31846 (line 6) 31847 * .debug subdirectories: Separate Debug Files. 31848 (line 6) 31849 * .gdbinit: Startup. (line 45) 31850 * .gnu_debuglink sections: Separate Debug Files. 31851 (line 78) 31852 * .note.gnu.build-id sections: Separate Debug Files. 31853 (line 96) 31854 * .o files, reading symbols from: Files. (line 132) 31855 * /proc: SVR4 Process Information. 31856 (line 6) 31857 * <architecture>: Target Description Format. 31858 (line 73) 31859 * <compatible>: Target Description Format. 31860 (line 96) 31861 * <feature>: Target Description Format. 31862 (line 120) 31863 * <osabi>: Target Description Format. 31864 (line 83) 31865 * <reg>: Target Description Format. 31866 (line 167) 31867 * <union>: Target Description Format. 31868 (line 154) 31869 * <vector>: Target Description Format. 31870 (line 147) 31871 * ? packet: Packets. (line 58) 31872 * @, referencing memory as an array: Arrays. (line 6) 31873 * ^connected: GDB/MI Result Records. 31874 (line 22) 31875 * ^done: GDB/MI Result Records. 31876 (line 9) 31877 * ^error: GDB/MI Result Records. 31878 (line 25) 31879 * ^exit: GDB/MI Result Records. 31880 (line 29) 31881 * ^running: GDB/MI Result Records. 31882 (line 14) 31883 * __init__ on Command: Commands In Python. (line 12) 31884 * __init__ on Function: Functions In Python. (line 11) 31885 * _NSPrintForDebugger, and printing Objective-C objects: The Print Command with Objective-C. 31886 (line 11) 31887 * A packet: Packets. (line 65) 31888 * abbreviation: Command Syntax. (line 13) 31889 * abort (C-g): Miscellaneous Commands. 31890 (line 10) 31891 * accept-line (Newline or Return): Commands For History. 31892 (line 6) 31893 * acknowledgment, for GDB remote: Packet Acknowledgment. 31894 (line 6) 31895 * actions: Tracepoint Actions. (line 6) 31896 * active targets: Active Targets. (line 6) 31897 * Ada: Ada. (line 6) 31898 * Ada exception catching: Set Catchpoints. (line 19) 31899 * Ada mode, general: Ada Mode Intro. (line 6) 31900 * Ada task switching: Ada Tasks. (line 115) 31901 * Ada tasking and core file debugging: Ada Tasks and Core Files. 31902 (line 6) 31903 * Ada, deviations from: Additions to Ada. (line 6) 31904 * Ada, omissions from: Omissions from Ada. (line 6) 31905 * Ada, problems: Ada Glitches. (line 6) 31906 * Ada, tasking: Ada Tasks. (line 6) 31907 * add new commands for external monitor: Connecting. (line 105) 31908 * add-inferior: Inferiors and Programs. 31909 (line 60) 31910 * add-shared-symbol-files: Files. (line 172) 31911 * add-symbol-file: Files. (line 113) 31912 * add-symbol-file-from-memory: Files. (line 162) 31913 * address <1>: Lazy Strings In Python. 31914 (line 27) 31915 * address: Values From Inferior. 31916 (line 31) 31917 * address of a symbol: Symbols. (line 44) 31918 * address size for remote targets: Remote Configuration. 31919 (line 12) 31920 * ADP (Angel Debugger Protocol) logging: ARM. (line 89) 31921 * advance LOCATION: Continuing and Stepping. 31922 (line 181) 31923 * aggregates (Ada): Omissions from Ada. (line 44) 31924 * AIX threads: Debugging Output. (line 28) 31925 * alignment of remote memory accesses: Packets. (line 215) 31926 * all-stop mode: All-Stop Mode. (line 6) 31927 * Alpha stack: MIPS. (line 6) 31928 * ambiguous expressions: Ambiguous Expressions. 31929 (line 6) 31930 * AMD 29K register stack: A29K. (line 6) 31931 * annotations: Annotations Overview. 31932 (line 6) 31933 * annotations for errors, warnings and interrupts: Errors. (line 6) 31934 * annotations for invalidation messages: Invalidation. (line 6) 31935 * annotations for prompts: Prompting. (line 6) 31936 * annotations for running programs: Annotations for Running. 31937 (line 6) 31938 * annotations for source display: Source Annotations. (line 6) 31939 * append: Dump/Restore Files. (line 35) 31940 * append data to a file: Dump/Restore Files. (line 6) 31941 * apply command to several threads: Threads. (line 150) 31942 * apropos: Help. (line 62) 31943 * architecture debugging info: Debugging Output. (line 18) 31944 * argument count in user-defined commands: Define. (line 25) 31945 * arguments (to your program): Arguments. (line 6) 31946 * arguments, to gdbserver: Server. (line 34) 31947 * arguments, to user-defined commands: Define. (line 6) 31948 * ARM 32-bit mode: ARM. (line 25) 31949 * ARM RDI: ARM. (line 6) 31950 * array aggregates (Ada): Omissions from Ada. (line 44) 31951 * arrays: Arrays. (line 6) 31952 * arrays in expressions: Expressions. (line 14) 31953 * artificial array: Arrays. (line 6) 31954 * assembly instructions: Machine Code. (line 36) 31955 * assf: Files. (line 172) 31956 * assignment: Assignment. (line 6) 31957 * async output in GDB/MI: GDB/MI Output Syntax. 31958 (line 98) 31959 * async records in GDB/MI: GDB/MI Async Records. 31960 (line 6) 31961 * asynchronous execution: Background Execution. 31962 (line 6) 31963 * asynchronous execution, and process record and replay: Process Record and Replay. 31964 (line 52) 31965 * AT&T disassembly flavor: Machine Code. (line 107) 31966 * attach: Attach. (line 6) 31967 * attach to a program by name: Server. (line 79) 31968 * attach&: Background Execution. 31969 (line 38) 31970 * auto-loading, Python: Auto-loading. (line 6) 31971 * auto-retry, for remote TCP target: Remote Configuration. 31972 (line 108) 31973 * automatic display: Auto Display. (line 6) 31974 * automatic hardware breakpoints: Set Breaks. (line 273) 31975 * automatic overlay debugging: Automatic Overlay Debugging. 31976 (line 6) 31977 * automatic thread selection: All-Stop Mode. (line 28) 31978 * auxiliary vector: OS Information. (line 21) 31979 * AVR: AVR. (line 6) 31980 * awatch: Set Watchpoints. (line 60) 31981 * b (break): Set Breaks. (line 6) 31982 * B packet: Packets. (line 92) 31983 * b packet: Packets. (line 77) 31984 * background execution: Background Execution. 31985 (line 6) 31986 * backtrace: Backtrace. (line 11) 31987 * backtrace beyond main function: Backtrace. (line 93) 31988 * backtrace limit: Backtrace. (line 129) 31989 * backward-char (C-b): Commands For Moving. (line 15) 31990 * backward-delete-char (Rubout): Commands For Text. (line 11) 31991 * backward-kill-line (C-x Rubout): Commands For Killing. 31992 (line 9) 31993 * backward-kill-word (M-<DEL>): Commands For Killing. 31994 (line 24) 31995 * backward-word (M-b): Commands For Moving. (line 22) 31996 * baud rate for remote targets: Remote Configuration. 31997 (line 21) 31998 * bc packet: Packets. (line 97) 31999 * bcache statistics: Maintenance Commands. 32000 (line 215) 32001 * beginning-of-history (M-<): Commands For History. 32002 (line 19) 32003 * beginning-of-line (C-a): Commands For Moving. (line 6) 32004 * bell-style: Readline Init File Syntax. 32005 (line 35) 32006 * bind-tty-special-chars: Readline Init File Syntax. 32007 (line 42) 32008 * bits in remote address: Remote Configuration. 32009 (line 12) 32010 * bookmark: Checkpoint/Restart. (line 6) 32011 * break: Set Breaks. (line 6) 32012 * break ... task TASKNO (Ada): Ada Tasks. (line 135) 32013 * break ... thread THREADNO: Thread-Specific Breakpoints. 32014 (line 10) 32015 * break in overloaded functions: Debugging C Plus Plus. 32016 (line 9) 32017 * break on a system call.: Set Catchpoints. (line 48) 32018 * break on fork/exec: Set Catchpoints. (line 43) 32019 * BREAK signal instead of Ctrl-C: Remote Configuration. 32020 (line 29) 32021 * break, and Objective-C: Method Names in Commands. 32022 (line 9) 32023 * breakpoint address adjusted: Breakpoint-related Warnings. 32024 (line 6) 32025 * breakpoint annotation: Annotations for Running. 32026 (line 47) 32027 * breakpoint commands: Break Commands. (line 6) 32028 * breakpoint commands for GDB/MI: GDB/MI Breakpoint Commands. 32029 (line 6) 32030 * breakpoint conditions: Conditions. (line 6) 32031 * breakpoint numbers: Breakpoints. (line 41) 32032 * breakpoint on events: Breakpoints. (line 33) 32033 * breakpoint on memory address: Breakpoints. (line 20) 32034 * breakpoint on variable modification: Breakpoints. (line 20) 32035 * breakpoint ranges: Breakpoints. (line 48) 32036 * breakpoint subroutine, remote: Stub Contents. (line 31) 32037 * breakpointing Ada elaboration code: Stopping Before Main Program. 32038 (line 6) 32039 * breakpoints: Breakpoints. (line 6) 32040 * breakpoints and tasks, in Ada: Ada Tasks. (line 135) 32041 * breakpoints and threads: Thread-Specific Breakpoints. 32042 (line 10) 32043 * breakpoints in functions matching a regexp: Set Breaks. (line 92) 32044 * breakpoints in overlays: Overlay Commands. (line 93) 32045 * breakpoints, multiple locations: Set Breaks. (line 179) 32046 * breakpoints-invalid annotation: Invalidation. (line 13) 32047 * bs packet: Packets. (line 103) 32048 * bt (backtrace): Backtrace. (line 11) 32049 * bug criteria: Bug Criteria. (line 6) 32050 * bug reports: Bug Reporting. (line 6) 32051 * bugs in GDB: GDB Bugs. (line 6) 32052 * build ID sections: Separate Debug Files. 32053 (line 96) 32054 * build ID, and separate debugging files: Separate Debug Files. 32055 (line 6) 32056 * building GDB, requirements for: Requirements. (line 6) 32057 * built-in simulator target: Target Commands. (line 73) 32058 * c (continue): Continuing and Stepping. 32059 (line 15) 32060 * c (SingleKey TUI key): TUI Single Key Mode. (line 10) 32061 * C and C++: C. (line 6) 32062 * C and C++ checks: C Checks. (line 6) 32063 * C and C++ constants: C Constants. (line 6) 32064 * C and C++ defaults: C Defaults. (line 6) 32065 * C and C++ operators: C Operators. (line 6) 32066 * c packet: Packets. (line 110) 32067 * C packet: Packets. (line 116) 32068 * C++: C. (line 10) 32069 * C++ compilers: C Plus Plus Expressions. 32070 (line 8) 32071 * C++ exception handling: Debugging C Plus Plus. 32072 (line 20) 32073 * C++ overload debugging info: Debugging Output. (line 108) 32074 * C++ scope resolution: Variables. (line 54) 32075 * C++ symbol decoding style: Print Settings. (line 296) 32076 * C++ symbol display: Debugging C Plus Plus. 32077 (line 29) 32078 * C-L: TUI Keys. (line 65) 32079 * C-x 1: TUI Keys. (line 19) 32080 * C-x 2: TUI Keys. (line 26) 32081 * C-x A: TUI Keys. (line 12) 32082 * C-x a: TUI Keys. (line 11) 32083 * C-x C-a: TUI Keys. (line 10) 32084 * C-x o: TUI Keys. (line 34) 32085 * C-x s: TUI Keys. (line 41) 32086 * caching data of remote targets: Caching Remote Data. (line 6) 32087 * call: Calling. (line 10) 32088 * call dummy stack unwinding: Calling. (line 35) 32089 * call dummy stack unwinding on unhandled exception.: Calling. 32090 (line 46) 32091 * call overloaded functions: C Plus Plus Expressions. 32092 (line 27) 32093 * call stack: Stack. (line 9) 32094 * call stack traces: Backtrace. (line 6) 32095 * call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) 32096 * calling functions: Calling. (line 6) 32097 * calling make: Shell Commands. (line 19) 32098 * capitalize-word (M-c): Commands For Text. (line 49) 32099 * case sensitivity in symbol names: Symbols. (line 27) 32100 * case-insensitive symbol names: Symbols. (line 27) 32101 * cast on Value: Values From Inferior. 32102 (line 47) 32103 * casts, in expressions: Expressions. (line 28) 32104 * casts, to view memory: Expressions. (line 43) 32105 * catch: Set Catchpoints. (line 10) 32106 * catch Ada exceptions: Set Catchpoints. (line 19) 32107 * catch exceptions, list active handlers: Frame Info. (line 60) 32108 * catchpoints: Breakpoints. (line 33) 32109 * catchpoints, setting: Set Catchpoints. (line 6) 32110 * cd: Working Directory. (line 16) 32111 * cdir: Source Path. (line 108) 32112 * Cell Broadband Engine: SPU. (line 6) 32113 * change working directory: Working Directory. (line 16) 32114 * character sets: Character Sets. (line 6) 32115 * character-search (C-]): Miscellaneous Commands. 32116 (line 41) 32117 * character-search-backward (M-C-]): Miscellaneous Commands. 32118 (line 46) 32119 * charset: Character Sets. (line 6) 32120 * checkpoint: Checkpoint/Restart. (line 26) 32121 * checkpoints and process id: Checkpoint/Restart. (line 80) 32122 * checks, range: Type Checking. (line 65) 32123 * checks, type: Checks. (line 31) 32124 * checksum, for GDB remote: Overview. (line 20) 32125 * children on pretty printer: Pretty Printing. (line 35) 32126 * choosing target byte order: Byte Order. (line 6) 32127 * clear: Delete Breaks. (line 21) 32128 * clear, and Objective-C: Method Names in Commands. 32129 (line 9) 32130 * clear-screen (C-l): Commands For Moving. (line 26) 32131 * clearing breakpoints, watchpoints, catchpoints: Delete Breaks. 32132 (line 6) 32133 * clone-inferior: Inferiors and Programs. 32134 (line 67) 32135 * close, file-i/o system call: close. (line 6) 32136 * closest symbol and offset for an address: Symbols. (line 54) 32137 * code: Types In Python. (line 21) 32138 * code address and its source line: Machine Code. (line 25) 32139 * collect (tracepoints): Tracepoint Actions. (line 45) 32140 * collected data discarded: Starting and Stopping Trace Experiments. 32141 (line 6) 32142 * colon, doubled as scope operator: M2 Scope. (line 6) 32143 * colon-colon, context for variables/functions: Variables. (line 44) 32144 * colon-colon, in Modula-2: M2 Scope. (line 6) 32145 * command editing: Readline Bare Essentials. 32146 (line 6) 32147 * command files: Command Files. (line 6) 32148 * command history: Command History. (line 6) 32149 * command hooks: Hooks. (line 6) 32150 * command interpreters: Interpreters. (line 6) 32151 * command line editing: Editing. (line 6) 32152 * command scripts, debugging: Messages/Warnings. (line 65) 32153 * command tracing: Messages/Warnings. (line 60) 32154 * COMMAND_BREAKPOINTS: Commands In Python. (line 135) 32155 * COMMAND_DATA: Commands In Python. (line 105) 32156 * COMMAND_FILES: Commands In Python. (line 116) 32157 * COMMAND_MAINTENANCE: Commands In Python. (line 153) 32158 * COMMAND_NONE: Commands In Python. (line 95) 32159 * COMMAND_OBSCURE: Commands In Python. (line 147) 32160 * COMMAND_RUNNING: Commands In Python. (line 99) 32161 * COMMAND_STACK: Commands In Python. (line 110) 32162 * COMMAND_STATUS: Commands In Python. (line 129) 32163 * COMMAND_SUPPORT: Commands In Python. (line 122) 32164 * COMMAND_TRACEPOINTS: Commands In Python. (line 141) 32165 * commands: Break Commands. (line 11) 32166 * commands annotation: Prompting. (line 27) 32167 * commands for C++: Debugging C Plus Plus. 32168 (line 6) 32169 * commands in python: Commands In Python. (line 6) 32170 * commands to access python: Python Commands. (line 6) 32171 * comment: Command Syntax. (line 38) 32172 * comment-begin: Readline Init File Syntax. 32173 (line 47) 32174 * COMMON blocks, Fortran: Special Fortran Commands. 32175 (line 9) 32176 * common targets: Target Commands. (line 46) 32177 * compare-sections: Memory. (line 121) 32178 * compatibility, GDB/MI and CLI: GDB/MI Compatibility with CLI. 32179 (line 6) 32180 * compilation directory: Source Path. (line 108) 32181 * compiling, on Sparclet: Sparclet. (line 16) 32182 * complete: Help. (line 76) 32183 * complete (<TAB>): Commands For Completion. 32184 (line 6) 32185 * complete on Command: Commands In Python. (line 63) 32186 * COMPLETE_COMMAND: Commands In Python. (line 174) 32187 * COMPLETE_FILENAME: Commands In Python. (line 167) 32188 * COMPLETE_LOCATION: Commands In Python. (line 170) 32189 * COMPLETE_NONE: Commands In Python. (line 164) 32190 * COMPLETE_SYMBOL: Commands In Python. (line 178) 32191 * completion: Completion. (line 6) 32192 * completion of Python commands: Commands In Python. (line 62) 32193 * completion of quoted strings: Completion. (line 57) 32194 * completion of structure field names: Completion. (line 96) 32195 * completion of union field names: Completion. (line 96) 32196 * completion-query-items: Readline Init File Syntax. 32197 (line 57) 32198 * compressed debug sections: Requirements. (line 39) 32199 * condition: Conditions. (line 45) 32200 * conditional breakpoints: Conditions. (line 6) 32201 * conditional tracepoints: Tracepoint Conditions. 32202 (line 6) 32203 * configuring GDB: Running Configure. (line 6) 32204 * confirmation: Messages/Warnings. (line 50) 32205 * connection timeout, for remote TCP target: Remote Configuration. 32206 (line 123) 32207 * console i/o as part of file-i/o: Console I/O. (line 6) 32208 * console interpreter: Interpreters. (line 21) 32209 * console output in GDB/MI: GDB/MI Output Syntax. 32210 (line 106) 32211 * const on Type: Types In Python. (line 79) 32212 * constants, in file-i/o protocol: Constants. (line 6) 32213 * continue: Continuing and Stepping. 32214 (line 15) 32215 * continue&: Background Execution. 32216 (line 53) 32217 * continuing: Continuing and Stepping. 32218 (line 6) 32219 * continuing threads: Thread Stops. (line 6) 32220 * control C, and remote debugging: Bootstrapping. (line 25) 32221 * controlling terminal: Input/Output. (line 23) 32222 * convenience functions: Convenience Vars. (line 92) 32223 * convenience functions in python: Functions In Python. (line 6) 32224 * convenience variables: Convenience Vars. (line 6) 32225 * convenience variables for tracepoints: Tracepoint Variables. 32226 (line 6) 32227 * convenience variables, and trace state variables: Trace State Variables. 32228 (line 17) 32229 * convenience variables, initializing: Convenience Vars. (line 41) 32230 * convert-meta: Readline Init File Syntax. 32231 (line 67) 32232 * copy-backward-word (): Commands For Killing. 32233 (line 49) 32234 * copy-forward-word (): Commands For Killing. 32235 (line 54) 32236 * copy-region-as-kill (): Commands For Killing. 32237 (line 45) 32238 * core dump file: Files. (line 6) 32239 * core dump file target: Target Commands. (line 54) 32240 * core-file: Files. (line 97) 32241 * crash of debugger: Bug Criteria. (line 9) 32242 * CRC algorithm definition: Separate Debug Files. 32243 (line 140) 32244 * CRC of memory block, remote request: General Query Packets. 32245 (line 52) 32246 * CRIS: CRIS. (line 6) 32247 * CRIS mode: CRIS. (line 26) 32248 * CRIS version: CRIS. (line 10) 32249 * Ctrl-BREAK, MS-Windows: Cygwin Native. (line 9) 32250 * ctrl-c message, in file-i/o protocol: The Ctrl-C Message. (line 6) 32251 * Ctrl-o (operate-and-get-next): Command Syntax. (line 42) 32252 * current Ada task ID: Ada Tasks. (line 105) 32253 * current directory: Source Path. (line 108) 32254 * current stack frame: Frames. (line 45) 32255 * current thread: Threads. (line 45) 32256 * current thread, remote request: General Query Packets. 32257 (line 41) 32258 * current_objfile: Objfiles In Python. (line 16) 32259 * cwd: Source Path. (line 108) 32260 * Cygwin DLL, debugging: Cygwin Native. (line 37) 32261 * Cygwin-specific commands: Cygwin Native. (line 6) 32262 * d (delete): Delete Breaks. (line 41) 32263 * d (SingleKey TUI key): TUI Single Key Mode. (line 13) 32264 * D packet: Packets. (line 129) 32265 * d packet: Packets. (line 122) 32266 * Darwin: Darwin. (line 6) 32267 * data breakpoints: Breakpoints. (line 20) 32268 * data manipulation, in GDB/MI: GDB/MI Data Manipulation. 32269 (line 6) 32270 * dead names, GNU Hurd: Hurd Native. (line 85) 32271 * debug expression parser: Debugging Output. (line 114) 32272 * debug formats and C++: C Plus Plus Expressions. 32273 (line 8) 32274 * debug link sections: Separate Debug Files. 32275 (line 78) 32276 * debug remote protocol: Debugging Output. (line 123) 32277 * debug_chaos: M32R/D. (line 50) 32278 * debugger crash: Bug Criteria. (line 9) 32279 * debugging C++ programs: C Plus Plus Expressions. 32280 (line 8) 32281 * debugging information directory, global: Separate Debug Files. 32282 (line 6) 32283 * debugging information in separate files: Separate Debug Files. 32284 (line 6) 32285 * debugging multiple processes: Forks. (line 52) 32286 * debugging multithreaded programs (on HP-UX): Threads. (line 89) 32287 * debugging optimized code: Optimized Code. (line 6) 32288 * debugging stub, example: Remote Stub. (line 6) 32289 * debugging target: Targets. (line 6) 32290 * debugging the Cygwin DLL: Cygwin Native. (line 37) 32291 * decimal floating point format: Decimal Floating Point. 32292 (line 6) 32293 * default collection action: Tracepoint Actions. (line 89) 32294 * default data directory: Data Files. (line 19) 32295 * default source path substitution: Source Path. (line 89) 32296 * default system root: Files. (line 393) 32297 * define: Define. (line 37) 32298 * define trace state variable, remote request: Tracepoint Packets. 32299 (line 90) 32300 * defining macros interactively: Macros. (line 52) 32301 * definition, showing a macro's: Macros. (line 47) 32302 * delete: Delete Breaks. (line 41) 32303 * delete breakpoints: Delete Breaks. (line 41) 32304 * delete checkpoint CHECKPOINT-ID: Checkpoint/Restart. (line 56) 32305 * delete display: Auto Display. (line 45) 32306 * delete mem: Memory Region Attributes. 32307 (line 34) 32308 * delete tracepoint: Create and Delete Tracepoints. 32309 (line 53) 32310 * delete tvariable: Trace State Variables. 32311 (line 42) 32312 * delete-char (C-d): Commands For Text. (line 6) 32313 * delete-char-or-list (): Commands For Completion. 32314 (line 30) 32315 * delete-horizontal-space (): Commands For Killing. 32316 (line 37) 32317 * deleting breakpoints, watchpoints, catchpoints: Delete Breaks. 32318 (line 6) 32319 * deliver a signal to a program: Signaling. (line 6) 32320 * demangling C++ names: Print Settings. (line 277) 32321 * deprecated commands: Maintenance Commands. 32322 (line 90) 32323 * dereference on Value: Values From Inferior. 32324 (line 53) 32325 * derived type of an object, printing: Print Settings. (line 329) 32326 * descriptor tables display: DJGPP Native. (line 24) 32327 * detach: Attach. (line 36) 32328 * detach (remote): Connecting. (line 91) 32329 * detach from task, GNU Hurd: Hurd Native. (line 60) 32330 * detach from thread, GNU Hurd: Hurd Native. (line 110) 32331 * detach inferior INFNO: Inferiors and Programs. 32332 (line 97) 32333 * digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6) 32334 * dir: Source Path. (line 39) 32335 * direct memory access (DMA) on MS-DOS: DJGPP Native. (line 75) 32336 * directories for source files: Source Path. (line 6) 32337 * directory: Source Path. (line 39) 32338 * directory, compilation: Source Path. (line 108) 32339 * directory, current: Source Path. (line 108) 32340 * dis (disable): Disabling. (line 38) 32341 * disable: Disabling. (line 38) 32342 * disable display: Auto Display. (line 52) 32343 * disable mem: Memory Region Attributes. 32344 (line 38) 32345 * disable tracepoint: Enable and Disable Tracepoints. 32346 (line 9) 32347 * disable-completion: Readline Init File Syntax. 32348 (line 73) 32349 * disassemble: Machine Code. (line 36) 32350 * disconnect: Connecting. (line 98) 32351 * disconnected tracing: Starting and Stopping Trace Experiments. 32352 (line 38) 32353 * displaced stepping debugging info: Debugging Output. (line 42) 32354 * displaced stepping support: Maintenance Commands. 32355 (line 56) 32356 * displaced stepping, and process record and replay: Process Record and Replay. 32357 (line 47) 32358 * display: Auto Display. (line 23) 32359 * display command history: Command History. (line 78) 32360 * display derived types: Print Settings. (line 329) 32361 * display disabled out of scope: Auto Display. (line 74) 32362 * display GDB copyright: Help. (line 136) 32363 * display of expressions: Auto Display. (line 6) 32364 * display remote monitor communications: Target Commands. (line 108) 32365 * display remote packets: Debugging Output. (line 123) 32366 * display_hint on pretty printer: Pretty Printing. (line 48) 32367 * DJGPP debugging: DJGPP Native. (line 6) 32368 * dll-symbols: Cygwin Native. (line 33) 32369 * DLLs with no debugging symbols: Non-debug DLL Symbols. 32370 (line 6) 32371 * do (down): Selection. (line 40) 32372 * do not print frame argument values: Print Settings. (line 135) 32373 * do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. 32374 (line 14) 32375 * document: Define. (line 49) 32376 * documentation: Formatting Documentation. 32377 (line 22) 32378 * don't repeat command: Define. (line 61) 32379 * don't repeat Python command: Commands In Python. (line 43) 32380 * dont-repeat: Define. (line 61) 32381 * dont_repeat on Command: Commands In Python. (line 44) 32382 * DOS serial data link, remote debugging: DJGPP Native. (line 121) 32383 * DOS serial port status: DJGPP Native. (line 142) 32384 * down: Selection. (line 40) 32385 * Down: TUI Keys. (line 56) 32386 * down-silently: Selection. (line 64) 32387 * downcase-word (M-l): Commands For Text. (line 45) 32388 * download server address (M32R): M32R/D. (line 27) 32389 * download to Sparclet: Sparclet Download. (line 6) 32390 * download to VxWorks: VxWorks Download. (line 6) 32391 * DPMI: DJGPP Native. (line 6) 32392 * dump: Dump/Restore Files. (line 13) 32393 * dump all data collected at tracepoint: tdump. (line 6) 32394 * dump core from inferior: Core File Generation. 32395 (line 6) 32396 * dump data to a file: Dump/Restore Files. (line 6) 32397 * dump-functions (): Miscellaneous Commands. 32398 (line 61) 32399 * dump-macros (): Miscellaneous Commands. 32400 (line 73) 32401 * dump-variables (): Miscellaneous Commands. 32402 (line 67) 32403 * dump/restore files: Dump/Restore Files. (line 6) 32404 * DWARF 2 compilation units cache: Maintenance Commands. 32405 (line 251) 32406 * DWARF-2 CFI and CRIS: CRIS. (line 18) 32407 * DWARF2 DIEs: Debugging Output. (line 35) 32408 * dynamic linking: Files. (line 113) 32409 * dynamic varobj: GDB/MI Variable Objects. 32410 (line 164) 32411 * e (edit): Edit. (line 6) 32412 * echo: Output. (line 12) 32413 * edit: Edit. (line 6) 32414 * editing: Editing. (line 15) 32415 * editing command lines: Readline Bare Essentials. 32416 (line 6) 32417 * editing source files: Edit. (line 6) 32418 * editing-mode: Readline Init File Syntax. 32419 (line 78) 32420 * eight-bit characters in strings: Print Settings. (line 222) 32421 * elaboration phase: Starting. (line 90) 32422 * else: Command Files. (line 59) 32423 * Emacs: Emacs. (line 6) 32424 * empty response, for unsupported packets: Overview. (line 96) 32425 * enable: Disabling. (line 45) 32426 * enable display: Auto Display. (line 57) 32427 * enable mem: Memory Region Attributes. 32428 (line 42) 32429 * enable tracepoint: Enable and Disable Tracepoints. 32430 (line 15) 32431 * enable-keypad: Readline Init File Syntax. 32432 (line 84) 32433 * enable/disable a breakpoint: Disabling. (line 6) 32434 * encoding: Lazy Strings In Python. 32435 (line 37) 32436 * end (breakpoint commands): Break Commands. (line 11) 32437 * end (if/else/while commands): Command Files. (line 88) 32438 * end (user-defined commands): Define. (line 49) 32439 * end-kbd-macro (C-x )): Keyboard Macros. (line 9) 32440 * end-of-history (M->): Commands For History. 32441 (line 22) 32442 * end-of-line (C-e): Commands For Moving. (line 9) 32443 * entering numbers: Numbers. (line 6) 32444 * environment (of your program): Environment. (line 6) 32445 * errno values, in file-i/o protocol: Errno Values. (line 6) 32446 * error annotation: Errors. (line 10) 32447 * error on valid input: Bug Criteria. (line 12) 32448 * error-begin annotation: Errors. (line 22) 32449 * event debugging info: Debugging Output. (line 50) 32450 * event designators: Event Designators. (line 6) 32451 * event handling: Set Catchpoints. (line 6) 32452 * examine process image: SVR4 Process Information. 32453 (line 6) 32454 * examining data: Data. (line 6) 32455 * examining memory: Memory. (line 9) 32456 * exception handlers: Set Catchpoints. (line 6) 32457 * exception handlers, how to list: Frame Info. (line 60) 32458 * exceptionHandler: Bootstrapping. (line 38) 32459 * exceptions, python: Exception Handling. (line 6) 32460 * exchange-point-and-mark (C-x C-x): Miscellaneous Commands. 32461 (line 36) 32462 * exec-file: Files. (line 39) 32463 * executable file: Files. (line 16) 32464 * executable file target: Target Commands. (line 50) 32465 * executable file, for remote target: Remote Configuration. 32466 (line 79) 32467 * execute: Basic Python. (line 12) 32468 * execute commands from a file: Command Files. (line 17) 32469 * execute forward or backward in time: Reverse Execution. (line 87) 32470 * execute remote command, remote request: General Query Packets. 32471 (line 239) 32472 * execution, foreground, background and asynchronous: Background Execution. 32473 (line 6) 32474 * exited annotation: Annotations for Running. 32475 (line 18) 32476 * exiting GDB: Quitting GDB. (line 6) 32477 * expand macro once: Macros. (line 38) 32478 * expand-tilde: Readline Init File Syntax. 32479 (line 89) 32480 * expanding preprocessor macros: Macros. (line 29) 32481 * expression debugging info: Debugging Output. (line 57) 32482 * expression parser, debugging info: Debugging Output. (line 114) 32483 * expressions: Expressions. (line 6) 32484 * expressions in Ada: Ada. (line 11) 32485 * expressions in C or C++: C. (line 6) 32486 * expressions in C++: C Plus Plus Expressions. 32487 (line 6) 32488 * expressions in Modula-2: Modula-2. (line 12) 32489 * extend GDB for remote targets: Connecting. (line 105) 32490 * extending GDB: Extending GDB. (line 6) 32491 * extra signal information: Signals. (line 102) 32492 * f (frame): Selection. (line 11) 32493 * f (SingleKey TUI key): TUI Single Key Mode. (line 16) 32494 * F packet: Packets. (line 146) 32495 * F reply packet: The F Reply Packet. (line 6) 32496 * F request packet: The F Request Packet. 32497 (line 6) 32498 * fast tracepoints: Set Tracepoints. (line 25) 32499 * fatal signal: Bug Criteria. (line 9) 32500 * fatal signals: Signals. (line 15) 32501 * FDL, GNU Free Documentation License: GNU Free Documentation License. 32502 (line 6) 32503 * features of the remote protocol: General Query Packets. 32504 (line 299) 32505 * fg (resume foreground execution): Continuing and Stepping. 32506 (line 15) 32507 * fields on Type: Types In Python. (line 38) 32508 * file: Files. (line 16) 32509 * file transfer: File Transfer. (line 6) 32510 * file transfer, remote protocol: Host I/O Packets. (line 6) 32511 * file-i/o examples: File-I/O Examples. (line 6) 32512 * file-i/o overview: File-I/O Overview. (line 6) 32513 * File-I/O remote protocol extension: File-I/O Remote Protocol Extension. 32514 (line 6) 32515 * file-i/o reply packet: The F Reply Packet. (line 6) 32516 * file-i/o request packet: The F Request Packet. 32517 (line 6) 32518 * filename: Objfiles In Python. (line 29) 32519 * fin (finish): Continuing and Stepping. 32520 (line 110) 32521 * find: Searching Memory. (line 9) 32522 * find downloadable SREC files (M32R): M32R/D. (line 15) 32523 * find trace snapshot: tfind. (line 6) 32524 * finish: Continuing and Stepping. 32525 (line 110) 32526 * finish&: Background Execution. 32527 (line 56) 32528 * flinching: Messages/Warnings. (line 50) 32529 * float promotion: ABI. (line 29) 32530 * floating point: Floating Point Hardware. 32531 (line 6) 32532 * floating point registers: Registers. (line 15) 32533 * floating point, MIPS remote: MIPS Embedded. (line 60) 32534 * flush: Basic Python. (line 60) 32535 * flush_i_cache: Bootstrapping. (line 60) 32536 * flushregs: Maintenance Commands. 32537 (line 207) 32538 * focus: TUI Commands. (line 34) 32539 * focus of debugging: Threads. (line 45) 32540 * foo: Symbol Errors. (line 50) 32541 * foreground execution: Background Execution. 32542 (line 6) 32543 * fork, debugging programs which call: Forks. (line 6) 32544 * format options: Print Settings. (line 6) 32545 * formatted output: Output Formats. (line 6) 32546 * Fortran: Summary. (line 35) 32547 * Fortran Defaults: Fortran Defaults. (line 6) 32548 * Fortran operators and expressions: Fortran Operators. (line 6) 32549 * Fortran-specific support in GDB: Fortran. (line 6) 32550 * forward-backward-delete-char (): Commands For Text. (line 15) 32551 * forward-char (C-f): Commands For Moving. (line 12) 32552 * forward-search: Search. (line 9) 32553 * forward-search-history (C-s): Commands For History. 32554 (line 30) 32555 * forward-word (M-f): Commands For Moving. (line 18) 32556 * FR-V shared-library debugging: Debugging Output. (line 141) 32557 * frame debugging info: Debugging Output. (line 65) 32558 * frame number: Frames. (line 28) 32559 * frame pointer: Frames. (line 21) 32560 * frame pointer register: Registers. (line 26) 32561 * frame, command: Frames. (line 45) 32562 * frame, definition: Frames. (line 6) 32563 * frame, selecting: Selection. (line 11) 32564 * frame_stop_reason_string: Frames In Python. (line 26) 32565 * frameless execution: Frames. (line 34) 32566 * frames in python: Frames In Python. (line 6) 32567 * frames-invalid annotation: Invalidation. (line 9) 32568 * free memory information (MS-DOS): DJGPP Native. (line 19) 32569 * fstat, file-i/o system call: stat/fstat. (line 6) 32570 * ftrace: Create and Delete Tracepoints. 32571 (line 40) 32572 * Fujitsu: Remote Stub. (line 69) 32573 * full symbol tables, listing GDB's internal: Symbols. (line 278) 32574 * Function: Functions In Python. (line 6) 32575 * function call arguments, optimized out: Backtrace. (line 71) 32576 * function entry/exit, wrong values of variables: Variables. (line 58) 32577 * functions without line info, and stepping: Continuing and Stepping. 32578 (line 93) 32579 * g packet: Packets. (line 151) 32580 * G packet: Packets. (line 167) 32581 * g++, GNU C++ compiler: C. (line 10) 32582 * garbled pointers: DJGPP Native. (line 42) 32583 * GCC and C++: C Plus Plus Expressions. 32584 (line 8) 32585 * gcore: Core File Generation. 32586 (line 18) 32587 * GDB bugs, reporting: Bug Reporting. (line 6) 32588 * GDB internal error: Maintenance Commands. 32589 (line 124) 32590 * gdb module: Basic Python. (line 6) 32591 * GDB reference card: Formatting Documentation. 32592 (line 6) 32593 * GDB startup: Startup. (line 6) 32594 * GDB version number: Help. (line 126) 32595 * gdb.COMMAND_BREAKPOINTS: Commands In Python. (line 135) 32596 * gdb.COMMAND_DATA: Commands In Python. (line 105) 32597 * gdb.COMMAND_FILES: Commands In Python. (line 116) 32598 * gdb.COMMAND_MAINTENANCE: Commands In Python. (line 153) 32599 * gdb.COMMAND_NONE: Commands In Python. (line 95) 32600 * gdb.COMMAND_OBSCURE: Commands In Python. (line 147) 32601 * gdb.COMMAND_RUNNING: Commands In Python. (line 99) 32602 * gdb.COMMAND_STACK: Commands In Python. (line 110) 32603 * gdb.COMMAND_STATUS: Commands In Python. (line 129) 32604 * gdb.COMMAND_SUPPORT: Commands In Python. (line 122) 32605 * gdb.COMMAND_TRACEPOINTS: Commands In Python. (line 141) 32606 * gdb.COMPLETE_COMMAND: Commands In Python. (line 174) 32607 * gdb.COMPLETE_FILENAME: Commands In Python. (line 167) 32608 * gdb.COMPLETE_LOCATION: Commands In Python. (line 170) 32609 * gdb.COMPLETE_NONE: Commands In Python. (line 164) 32610 * gdb.COMPLETE_SYMBOL: Commands In Python. (line 178) 32611 * gdb.current_objfile: Objfiles In Python. (line 15) 32612 * gdb.execute: Basic Python. (line 11) 32613 * gdb.flush: Basic Python. (line 59) 32614 * gdb.Function: Functions In Python. (line 6) 32615 * gdb.history: Basic Python. (line 31) 32616 * gdb.ini: Startup. (line 45) 32617 * gdb.LazyString: Lazy Strings In Python. 32618 (line 6) 32619 * gdb.lookup_type: Types In Python. (line 11) 32620 * gdb.Objfile: Objfiles In Python. (line 6) 32621 * gdb.objfiles: Objfiles In Python. (line 21) 32622 * gdb.parameter: Basic Python. (line 21) 32623 * gdb.parse_and_eval: Basic Python. (line 43) 32624 * gdb.selected_frame: Frames In Python. (line 21) 32625 * gdb.Type: Types In Python. (line 6) 32626 * gdb.TYPE_CODE_ARRAY: Types In Python. (line 142) 32627 * gdb.TYPE_CODE_BITSTRING: Types In Python. (line 180) 32628 * gdb.TYPE_CODE_BOOL: Types In Python. (line 201) 32629 * gdb.TYPE_CODE_CHAR: Types In Python. (line 198) 32630 * gdb.TYPE_CODE_COMPLEX: Types In Python. (line 204) 32631 * gdb.TYPE_CODE_DECFLOAT: Types In Python. (line 213) 32632 * gdb.TYPE_CODE_ENUM: Types In Python. (line 151) 32633 * gdb.TYPE_CODE_ERROR: Types In Python. (line 183) 32634 * gdb.TYPE_CODE_FLAGS: Types In Python. (line 154) 32635 * gdb.TYPE_CODE_FLT: Types In Python. (line 163) 32636 * gdb.TYPE_CODE_FUNC: Types In Python. (line 157) 32637 * gdb.TYPE_CODE_INT: Types In Python. (line 160) 32638 * gdb.TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 216) 32639 * gdb.TYPE_CODE_MEMBERPTR: Types In Python. (line 192) 32640 * gdb.TYPE_CODE_METHOD: Types In Python. (line 186) 32641 * gdb.TYPE_CODE_METHODPTR: Types In Python. (line 189) 32642 * gdb.TYPE_CODE_NAMESPACE: Types In Python. (line 210) 32643 * gdb.TYPE_CODE_PTR: Types In Python. (line 139) 32644 * gdb.TYPE_CODE_RANGE: Types In Python. (line 172) 32645 * gdb.TYPE_CODE_REF: Types In Python. (line 195) 32646 * gdb.TYPE_CODE_SET: Types In Python. (line 169) 32647 * gdb.TYPE_CODE_STRING: Types In Python. (line 175) 32648 * gdb.TYPE_CODE_STRUCT: Types In Python. (line 145) 32649 * gdb.TYPE_CODE_TYPEDEF: Types In Python. (line 207) 32650 * gdb.TYPE_CODE_UNION: Types In Python. (line 148) 32651 * gdb.TYPE_CODE_VOID: Types In Python. (line 166) 32652 * gdb.Value: Values From Inferior. 32653 (line 6) 32654 * gdb.write: Basic Python. (line 54) 32655 * GDB/MI development: GDB/MI Development and Front Ends. 32656 (line 6) 32657 * GDB/MI General Design: GDB/MI General Design. 32658 (line 6) 32659 * GDB/MI, async records: GDB/MI Async Records. 32660 (line 6) 32661 * GDB/MI, breakpoint commands: GDB/MI Breakpoint Commands. 32662 (line 6) 32663 * GDB/MI, compatibility with CLI: GDB/MI Compatibility with CLI. 32664 (line 6) 32665 * GDB/MI, data manipulation: GDB/MI Data Manipulation. 32666 (line 6) 32667 * GDB/MI, input syntax: GDB/MI Input Syntax. (line 6) 32668 * GDB/MI, its purpose: GDB/MI. (line 9) 32669 * GDB/MI, output syntax: GDB/MI Output Syntax. 32670 (line 6) 32671 * GDB/MI, result records: GDB/MI Result Records. 32672 (line 6) 32673 * GDB/MI, simple examples: GDB/MI Simple Examples. 32674 (line 6) 32675 * GDB/MI, stream records: GDB/MI Stream Records. 32676 (line 6) 32677 * gdbarch debugging info: Debugging Output. (line 18) 32678 * GDBHISTFILE, environment variable: Command History. (line 26) 32679 * gdbserver: Server. (line 6) 32680 * gdbserver, multiple processes: Server. (line 91) 32681 * gdbserver, search path for libthread_db: Server. (line 188) 32682 * GDT: DJGPP Native. (line 24) 32683 * generate-core-file: Core File Generation. 32684 (line 18) 32685 * get thread-local storage address, remote request: General Query Packets. 32686 (line 101) 32687 * getDebugChar: Bootstrapping. (line 14) 32688 * gettimeofday, file-i/o system call: gettimeofday. (line 6) 32689 * global debugging information directory: Separate Debug Files. 32690 (line 6) 32691 * GNU C++: C. (line 10) 32692 * GNU Emacs: Emacs. (line 6) 32693 * GNU Hurd debugging: Hurd Native. (line 6) 32694 * GNU/Hurd debug messages: Debugging Output. (line 72) 32695 * GNU/Linux LWP async debug messages: Debugging Output. (line 94) 32696 * GNU/Linux LWP debug messages: Debugging Output. (line 87) 32697 * gnu_debuglink_crc32: Separate Debug Files. 32698 (line 164) 32699 * h (help): Help. (line 9) 32700 * H packet: Packets. (line 178) 32701 * handle: Signals. (line 45) 32702 * handle_exception: Stub Contents. (line 15) 32703 * handling signals: Signals. (line 27) 32704 * hardware breakpoints: Set Breaks. (line 62) 32705 * hardware debug registers: Maintenance Commands. 32706 (line 277) 32707 * hardware watchpoints: Set Watchpoints. (line 31) 32708 * hash mark while downloading: Target Commands. (line 99) 32709 * hbreak: Set Breaks. (line 62) 32710 * help: Help. (line 6) 32711 * help function: Convenience Vars. (line 98) 32712 * help target: Target Commands. (line 19) 32713 * help user-defined: Define. (line 66) 32714 * heuristic-fence-post (Alpha, MIPS): MIPS. (line 14) 32715 * history: Basic Python. (line 32) 32716 * history events: Event Designators. (line 7) 32717 * history expansion: History Interaction. (line 6) 32718 * history expansion, turn on/off: Command History. (line 53) 32719 * history file: Command History. (line 26) 32720 * history number: Value History. (line 13) 32721 * history of values printed by GDB: Value History. (line 6) 32722 * history size: Command History. (line 45) 32723 * history substitution: Command History. (line 26) 32724 * history-preserve-point: Readline Init File Syntax. 32725 (line 93) 32726 * history-search-backward (): Commands For History. 32727 (line 50) 32728 * history-search-forward (): Commands For History. 32729 (line 45) 32730 * HISTSIZE, environment variable: Command History. (line 45) 32731 * hook: Hooks. (line 6) 32732 * hookpost: Hooks. (line 11) 32733 * hooks, for commands: Hooks. (line 6) 32734 * hooks, post-command: Hooks. (line 11) 32735 * hooks, pre-command: Hooks. (line 6) 32736 * horizontal-scroll-mode: Readline Init File Syntax. 32737 (line 98) 32738 * host character set: Character Sets. (line 6) 32739 * Host I/O, remote protocol: Host I/O Packets. (line 6) 32740 * how many arguments (user-defined commands): Define. (line 25) 32741 * HPPA support: HPPA. (line 6) 32742 * htrace: OpenRISC 1000. (line 69) 32743 * hwatch: OpenRISC 1000. (line 59) 32744 * i (info): Help. (line 99) 32745 * i packet: Packets. (line 192) 32746 * I packet: Packets. (line 197) 32747 * i/o: Input/Output. (line 6) 32748 * I/O registers (Atmel AVR): AVR. (line 10) 32749 * i386: Remote Stub. (line 57) 32750 * i386-stub.c: Remote Stub. (line 57) 32751 * IDT: DJGPP Native. (line 24) 32752 * if: Command Files. (line 59) 32753 * ignore: Conditions. (line 77) 32754 * ignore count (of breakpoint): Conditions. (line 66) 32755 * INCLUDE_RDB: VxWorks. (line 33) 32756 * incomplete type: Symbols. (line 107) 32757 * indentation in structure display: Print Settings. (line 198) 32758 * inferior: Inferiors and Programs. 32759 (line 13) 32760 * inferior debugging info: Debugging Output. (line 78) 32761 * inferior functions, calling: Calling. (line 6) 32762 * inferior INFNO: Inferiors and Programs. 32763 (line 49) 32764 * inferior tty: Input/Output. (line 44) 32765 * infinite recursion in user-defined commands: Define. (line 76) 32766 * info: Help. (line 99) 32767 * info address: Symbols. (line 44) 32768 * info all-registers: Registers. (line 15) 32769 * info args: Frame Info. (line 51) 32770 * info auxv: OS Information. (line 33) 32771 * info breakpoints: Set Breaks. (line 117) 32772 * info catch: Frame Info. (line 60) 32773 * info checkpoints: Checkpoint/Restart. (line 31) 32774 * info classes: Symbols. (line 205) 32775 * info common: Special Fortran Commands. 32776 (line 9) 32777 * info copying: Help. (line 136) 32778 * info dcache: Caching Remote Data. (line 34) 32779 * info display: Auto Display. (line 66) 32780 * info dll: Cygwin Native. (line 30) 32781 * info dos: DJGPP Native. (line 15) 32782 * info extensions: Show. (line 34) 32783 * info f (info frame): Frame Info. (line 17) 32784 * info files: Files. (line 191) 32785 * info float: Floating Point Hardware. 32786 (line 9) 32787 * info for known object files: Maintenance Commands. 32788 (line 210) 32789 * info frame: Frame Info. (line 17) 32790 * info frame, show the source language: Show. (line 15) 32791 * info functions: Symbols. (line 184) 32792 * info handle: Signals. (line 33) 32793 * info inferiors: Inferiors and Programs. 32794 (line 25) 32795 * info io_registers, AVR: AVR. (line 10) 32796 * info line: Machine Code. (line 14) 32797 * info line, and Objective-C: Method Names in Commands. 32798 (line 9) 32799 * info locals: Frame Info. (line 55) 32800 * info macro: Macros. (line 47) 32801 * info mem: Memory Region Attributes. 32802 (line 45) 32803 * info meminfo: SVR4 Process Information. 32804 (line 78) 32805 * info or1k spr: OpenRISC 1000. (line 20) 32806 * info os processes: OS Information. (line 47) 32807 * info pidlist: SVR4 Process Information. 32808 (line 74) 32809 * info proc: SVR4 Process Information. 32810 (line 16) 32811 * info program: Stopping. (line 18) 32812 * info record: Process Record and Replay. 32813 (line 114) 32814 * info registers: Registers. (line 11) 32815 * info scope: Symbols. (line 138) 32816 * info selectors: Symbols. (line 211) 32817 * info serial: DJGPP Native. (line 142) 32818 * info set: Help. (line 119) 32819 * info share: Files. (line 326) 32820 * info sharedlibrary: Files. (line 326) 32821 * info signals: Signals. (line 33) 32822 * info source: Symbols. (line 159) 32823 * info source, show the source language: Show. (line 21) 32824 * info sources: Symbols. (line 178) 32825 * info spu: SPU. (line 10) 32826 * info stack: Backtrace. (line 34) 32827 * info symbol: Symbols. (line 54) 32828 * info target: Files. (line 191) 32829 * info task TASKNO: Ada Tasks. (line 89) 32830 * info tasks: Ada Tasks. (line 9) 32831 * info terminal: Input/Output. (line 12) 32832 * info threads: Threads. (line 66) 32833 * info threads (HP-UX): Threads. (line 103) 32834 * info tp: Listing Tracepoints. (line 6) 32835 * info tracepoints: Listing Tracepoints. (line 6) 32836 * info tvariables: Trace State Variables. 32837 (line 37) 32838 * info types: Symbols. (line 124) 32839 * info udot: OS Information. (line 16) 32840 * info variables: Symbols. (line 196) 32841 * info vector: Vector Unit. (line 9) 32842 * info w32: Cygwin Native. (line 19) 32843 * info warranty: Help. (line 140) 32844 * info watchpoints [N]: Set Watchpoints. (line 64) 32845 * info win: TUI Commands. (line 12) 32846 * information about tracepoints: Listing Tracepoints. (line 6) 32847 * inheritance: Debugging C Plus Plus. 32848 (line 25) 32849 * init file: Startup. (line 11) 32850 * init file name: Startup. (line 45) 32851 * init-if-undefined: Convenience Vars. (line 41) 32852 * initial frame: Frames. (line 12) 32853 * initialization file, readline: Readline Init File. (line 6) 32854 * inline functions, debugging: Inline Functions. (line 6) 32855 * innermost frame: Frames. (line 12) 32856 * input syntax for GDB/MI: GDB/MI Input Syntax. (line 6) 32857 * input-meta: Readline Init File Syntax. 32858 (line 105) 32859 * insert-comment (M-#): Miscellaneous Commands. 32860 (line 51) 32861 * insert-completions (M-*): Commands For Completion. 32862 (line 14) 32863 * inspect: Data. (line 6) 32864 * installation: Installing GDB. (line 6) 32865 * instructions, assembly: Machine Code. (line 36) 32866 * integral datatypes, in file-i/o protocol: Integral Datatypes. 32867 (line 6) 32868 * Intel: Remote Stub. (line 57) 32869 * Intel disassembly flavor: Machine Code. (line 107) 32870 * interaction, readline: Readline Interaction. 32871 (line 6) 32872 * internal commands: Maintenance Commands. 32873 (line 6) 32874 * internal errors, control of GDB behavior: Maintenance Commands. 32875 (line 124) 32876 * internal GDB breakpoints: Set Breaks. (line 322) 32877 * interpreter-exec: Interpreters. (line 43) 32878 * interrupt <1>: Quitting GDB. (line 13) 32879 * interrupt: Background Execution. 32880 (line 73) 32881 * interrupt debuggee on MS-Windows: Cygwin Native. (line 9) 32882 * interrupt remote programs: Remote Configuration. 32883 (line 85) 32884 * interrupting remote programs: Connecting. (line 78) 32885 * interrupting remote targets: Bootstrapping. (line 25) 32886 * interrupts (remote protocol): Interrupts. (line 6) 32887 * invalid input: Bug Criteria. (line 16) 32888 * invoke another interpreter: Interpreters. (line 37) 32889 * invoke on Command: Commands In Python. (line 50) 32890 * invoke on Function: Functions In Python. (line 21) 32891 * is_optimized_out: Values From Inferior. 32892 (line 36) 32893 * is_valid on Frame: Frames In Python. (line 33) 32894 * isatty, file-i/o system call: isatty. (line 6) 32895 * isearch-terminators: Readline Init File Syntax. 32896 (line 112) 32897 * JIT compilation interface: JIT Interface. (line 6) 32898 * jump: Jumping. (line 10) 32899 * jump, and Objective-C: Method Names in Commands. 32900 (line 9) 32901 * just-in-time compilation: JIT Interface. (line 6) 32902 * k packet: Packets. (line 201) 32903 * kernel crash dump: BSD libkvm Interface. 32904 (line 6) 32905 * kernel memory image: BSD libkvm Interface. 32906 (line 6) 32907 * keymap: Readline Init File Syntax. 32908 (line 119) 32909 * kill: Kill Process. (line 6) 32910 * kill inferior INFNO: Inferiors and Programs. 32911 (line 101) 32912 * kill ring: Readline Killing Commands. 32913 (line 19) 32914 * kill-line (C-k): Commands For Killing. 32915 (line 6) 32916 * kill-region (): Commands For Killing. 32917 (line 41) 32918 * kill-whole-line (): Commands For Killing. 32919 (line 15) 32920 * kill-word (M-d): Commands For Killing. 32921 (line 19) 32922 * killing text: Readline Killing Commands. 32923 (line 6) 32924 * kvm: BSD libkvm Interface. 32925 (line 24) 32926 * l (list): List. (line 6) 32927 * languages: Languages. (line 6) 32928 * last tracepoint number: Create and Delete Tracepoints. 32929 (line 50) 32930 * latest breakpoint: Set Breaks. (line 6) 32931 * layout: TUI Commands. (line 15) 32932 * lazy strings in python: Lazy Strings In Python. 32933 (line 6) 32934 * lazy_string on Value: Values From Inferior. 32935 (line 102) 32936 * LDT: DJGPP Native. (line 24) 32937 * leaving GDB: Quitting GDB. (line 6) 32938 * Left: TUI Keys. (line 59) 32939 * length: Lazy Strings In Python. 32940 (line 31) 32941 * libkvm: BSD libkvm Interface. 32942 (line 6) 32943 * library list format, remote protocol: Library List Format. (line 6) 32944 * limit hardware breakpoints and watchpoints: Remote Configuration. 32945 (line 72) 32946 * limit on number of printed array elements: Print Settings. (line 123) 32947 * limits, in file-i/o protocol: Limits. (line 6) 32948 * linespec: Specify Location. (line 6) 32949 * Linux lightweight processes: Debugging Output. (line 87) 32950 * list: List. (line 6) 32951 * list active threads, remote request: General Query Packets. 32952 (line 73) 32953 * list of supported file-i/o calls: List of Supported Calls. 32954 (line 6) 32955 * list output in GDB/MI: GDB/MI Output Syntax. 32956 (line 117) 32957 * list, and Objective-C: Method Names in Commands. 32958 (line 9) 32959 * list, how many lines to display: List. (line 30) 32960 * listing GDB's internal symbol tables: Symbols. (line 278) 32961 * listing machine instructions: Machine Code. (line 36) 32962 * listing mapped overlays: Overlay Commands. (line 60) 32963 * load address, overlay's: How Overlays Work. (line 6) 32964 * load FILENAME: Target Commands. (line 115) 32965 * load shared library: Files. (line 323) 32966 * load symbols from memory: Files. (line 162) 32967 * local variables: Symbols. (line 138) 32968 * locate address: Output Formats. (line 35) 32969 * lock scheduler: All-Stop Mode. (line 37) 32970 * log output in GDB/MI: GDB/MI Output Syntax. 32971 (line 113) 32972 * logging file name: Logging Output. (line 13) 32973 * logging GDB output: Logging Output. (line 6) 32974 * lookup_type: Types In Python. (line 12) 32975 * loop_break: Command Files. (line 78) 32976 * loop_continue: Command Files. (line 82) 32977 * lseek flags, in file-i/o protocol: Lseek Flags. (line 6) 32978 * lseek, file-i/o system call: lseek. (line 6) 32979 * m packet: Packets. (line 208) 32980 * M packet: Packets. (line 228) 32981 * M32-EVA target board address: M32R/D. (line 21) 32982 * M32R/Chaos debugging: M32R/D. (line 50) 32983 * m680x0: Remote Stub. (line 60) 32984 * m68k-stub.c: Remote Stub. (line 60) 32985 * machine instructions: Machine Code. (line 36) 32986 * macro define: Macros. (line 52) 32987 * macro definition, showing: Macros. (line 47) 32988 * macro exp1: Macros. (line 36) 32989 * macro expand: Macros. (line 29) 32990 * macro expansion, showing the results of preprocessor: Macros. 32991 (line 29) 32992 * macro list: Macros. (line 73) 32993 * macro undef: Macros. (line 67) 32994 * macros, example of debugging with: Macros. (line 76) 32995 * macros, user-defined: Macros. (line 52) 32996 * mailing lists: GDB/MI Development and Front Ends. 32997 (line 35) 32998 * maint agent: Maintenance Commands. 32999 (line 12) 33000 * maint agent-eval: Maintenance Commands. 33001 (line 12) 33002 * maint check-symtabs: Maintenance Commands. 33003 (line 78) 33004 * maint cplus first_component: Maintenance Commands. 33005 (line 81) 33006 * maint cplus namespace: Maintenance Commands. 33007 (line 84) 33008 * maint demangle: Maintenance Commands. 33009 (line 87) 33010 * maint deprecate: Maintenance Commands. 33011 (line 90) 33012 * maint dump-me: Maintenance Commands. 33013 (line 98) 33014 * maint info breakpoints: Maintenance Commands. 33015 (line 25) 33016 * maint info program-spaces: Inferiors and Programs. 33017 (line 134) 33018 * maint info psymtabs: Symbols. (line 278) 33019 * maint info sections: Files. (line 200) 33020 * maint info sol-threads: Threads. (line 133) 33021 * maint info symtabs: Symbols. (line 278) 33022 * maint internal-error: Maintenance Commands. 33023 (line 103) 33024 * maint internal-warning: Maintenance Commands. 33025 (line 103) 33026 * maint packet: Maintenance Commands. 33027 (line 143) 33028 * maint print architecture: Maintenance Commands. 33029 (line 149) 33030 * maint print c-tdesc: Maintenance Commands. 33031 (line 153) 33032 * maint print cooked-registers: Maintenance Commands. 33033 (line 176) 33034 * maint print dummy-frames: Maintenance Commands. 33035 (line 158) 33036 * maint print objfiles: Maintenance Commands. 33037 (line 210) 33038 * maint print psymbols: Symbols. (line 259) 33039 * maint print raw-registers: Maintenance Commands. 33040 (line 176) 33041 * maint print reggroups: Maintenance Commands. 33042 (line 191) 33043 * maint print register-groups: Maintenance Commands. 33044 (line 176) 33045 * maint print registers: Maintenance Commands. 33046 (line 176) 33047 * maint print statistics: Maintenance Commands. 33048 (line 215) 33049 * maint print symbols: Symbols. (line 259) 33050 * maint print target-stack: Maintenance Commands. 33051 (line 228) 33052 * maint print type: Maintenance Commands. 33053 (line 240) 33054 * maint print unwind, HPPA: HPPA. (line 17) 33055 * maint set dwarf2 max-cache-age: Maintenance Commands. 33056 (line 247) 33057 * maint set internal-error: Maintenance Commands. 33058 (line 124) 33059 * maint set internal-warning: Maintenance Commands. 33060 (line 124) 33061 * maint set profile: Maintenance Commands. 33062 (line 261) 33063 * maint set python auto-load: Auto-loading. (line 34) 33064 * maint set python print-stack: Python Commands. (line 31) 33065 * maint set show-debug-regs: Maintenance Commands. 33066 (line 277) 33067 * maint show dwarf2 max-cache-age: Maintenance Commands. 33068 (line 247) 33069 * maint show internal-error: Maintenance Commands. 33070 (line 124) 33071 * maint show internal-warning: Maintenance Commands. 33072 (line 124) 33073 * maint show profile: Maintenance Commands. 33074 (line 261) 33075 * maint show show-debug-regs: Maintenance Commands. 33076 (line 277) 33077 * maint space: Maintenance Commands. 33078 (line 285) 33079 * maint time: Maintenance Commands. 33080 (line 292) 33081 * maint translate-address: Maintenance Commands. 33082 (line 303) 33083 * maint undeprecate: Maintenance Commands. 33084 (line 90) 33085 * maintenance commands: Maintenance Commands. 33086 (line 6) 33087 * make: Shell Commands. (line 19) 33088 * manual overlay debugging: Overlay Commands. (line 23) 33089 * map an overlay: Overlay Commands. (line 30) 33090 * mapinfo list, QNX Neutrino: SVR4 Process Information. 33091 (line 78) 33092 * mapped address: How Overlays Work. (line 6) 33093 * mapped overlays: How Overlays Work. (line 6) 33094 * mark-modified-lines: Readline Init File Syntax. 33095 (line 132) 33096 * mark-symlinked-directories: Readline Init File Syntax. 33097 (line 137) 33098 * match-hidden-files: Readline Init File Syntax. 33099 (line 142) 33100 * maximum value for offset of closest symbol: Print Settings. (line 70) 33101 * mem: Memory Region Attributes. 33102 (line 22) 33103 * member functions: C Plus Plus Expressions. 33104 (line 18) 33105 * memory address space mappings: SVR4 Process Information. 33106 (line 32) 33107 * memory map format: Memory Map Format. (line 6) 33108 * memory region attributes: Memory Region Attributes. 33109 (line 6) 33110 * memory tracing: Breakpoints. (line 20) 33111 * memory transfer, in file-i/o protocol: Memory Transfer. (line 6) 33112 * memory used by commands: Maintenance Commands. 33113 (line 285) 33114 * memory used for symbol tables: Files. (line 311) 33115 * memory, alignment and size of remote accesses: Packets. (line 215) 33116 * memory, viewing as typed object: Expressions. (line 43) 33117 * memset: Bootstrapping. (line 70) 33118 * menu-complete (): Commands For Completion. 33119 (line 18) 33120 * meta-flag: Readline Init File Syntax. 33121 (line 105) 33122 * mi interpreter: Interpreters. (line 26) 33123 * mi1 interpreter: Interpreters. (line 34) 33124 * mi2 interpreter: Interpreters. (line 31) 33125 * minimal language: Unsupported Languages. 33126 (line 6) 33127 * Minimal symbols and DLLs: Non-debug DLL Symbols. 33128 (line 6) 33129 * MIPS addresses, masking: MIPS. (line 61) 33130 * MIPS boards: MIPS Embedded. (line 6) 33131 * MIPS remote floating point: MIPS Embedded. (line 60) 33132 * MIPS stack: MIPS. (line 6) 33133 * miscellaneous settings: Other Misc Settings. (line 6) 33134 * MMX registers (x86): Registers. (line 71) 33135 * mode_t values, in file-i/o protocol: mode_t Values. (line 6) 33136 * Modula-2: Summary. (line 27) 33137 * Modula-2 built-ins: Built-In Func/Proc. (line 6) 33138 * Modula-2 checks: M2 Checks. (line 6) 33139 * Modula-2 constants: Built-In Func/Proc. (line 112) 33140 * Modula-2 defaults: M2 Defaults. (line 6) 33141 * Modula-2 operators: M2 Operators. (line 6) 33142 * Modula-2 types: M2 Types. (line 6) 33143 * Modula-2, deviations from: Deviations. (line 6) 33144 * Modula-2, GDB support: Modula-2. (line 6) 33145 * monitor: Connecting. (line 105) 33146 * monitor commands, for gdbserver: Server. (line 171) 33147 * Motorola 680x0: Remote Stub. (line 60) 33148 * MS Windows debugging: Cygwin Native. (line 6) 33149 * MS-DOS system info: DJGPP Native. (line 19) 33150 * MS-DOS-specific commands: DJGPP Native. (line 6) 33151 * multiple locations, breakpoints: Set Breaks. (line 179) 33152 * multiple processes: Forks. (line 6) 33153 * multiple processes with gdbserver: Server. (line 91) 33154 * multiple targets: Active Targets. (line 6) 33155 * multiple threads: Threads. (line 6) 33156 * multiple threads, backtrace: Backtrace. (line 37) 33157 * multiple-symbols menu: Ambiguous Expressions. 33158 (line 51) 33159 * multiprocess extensions, in remote protocol: General Query Packets. 33160 (line 475) 33161 * n (next): Continuing and Stepping. 33162 (line 78) 33163 * n (SingleKey TUI key): TUI Single Key Mode. (line 19) 33164 * name on Frame: Frames In Python. (line 40) 33165 * names of symbols: Symbols. (line 14) 33166 * namespace in C++: C Plus Plus Expressions. 33167 (line 22) 33168 * native Cygwin debugging: Cygwin Native. (line 6) 33169 * native DJGPP debugging: DJGPP Native. (line 6) 33170 * negative breakpoint numbers: Set Breaks. (line 322) 33171 * NetROM ROM emulator target: Target Commands. (line 88) 33172 * New SYSTAG message: Threads. (line 51) 33173 * New SYSTAG message, on HP-UX: Threads. (line 93) 33174 * newer on Frame: Frames In Python. (line 61) 33175 * next: Continuing and Stepping. 33176 (line 78) 33177 * next&: Background Execution. 33178 (line 47) 33179 * next-history (C-n): Commands For History. 33180 (line 16) 33181 * nexti: Continuing and Stepping. 33182 (line 203) 33183 * nexti&: Background Execution. 33184 (line 50) 33185 * ni (nexti): Continuing and Stepping. 33186 (line 203) 33187 * non-incremental-forward-search-history (M-n): Commands For History. 33188 (line 40) 33189 * non-incremental-reverse-search-history (M-p): Commands For History. 33190 (line 35) 33191 * non-member C++ functions, set breakpoint in: Set Breaks. (line 108) 33192 * non-stop mode: Non-Stop Mode. (line 6) 33193 * non-stop mode, and breakpoint always-inserted: Set Breaks. (line 315) 33194 * non-stop mode, and process record and replay: Process Record and Replay. 33195 (line 52) 33196 * non-stop mode, and set displaced-stepping: Maintenance Commands. 33197 (line 73) 33198 * non-stop mode, remote request: General Query Packets. 33199 (line 191) 33200 * noninvasive task options: Hurd Native. (line 73) 33201 * nosharedlibrary: Files. (line 341) 33202 * notation, readline: Readline Bare Essentials. 33203 (line 6) 33204 * notational conventions, for GDB/MI: GDB/MI. (line 25) 33205 * notification packets: Notification Packets. 33206 (line 6) 33207 * notify output in GDB/MI: GDB/MI Output Syntax. 33208 (line 102) 33209 * NULL elements in arrays: Print Settings. (line 189) 33210 * number of array elements to print: Print Settings. (line 123) 33211 * number representation: Numbers. (line 6) 33212 * numbers for breakpoints: Breakpoints. (line 41) 33213 * object files, relocatable, reading symbols from: Files. (line 132) 33214 * Objective-C: Objective-C. (line 6) 33215 * Objective-C, classes and selectors: Symbols. (line 205) 33216 * Objective-C, print objects: The Print Command with Objective-C. 33217 (line 6) 33218 * Objfile: Objfiles In Python. (line 6) 33219 * objfiles: Objfiles In Python. (line 22) 33220 * objfiles in python: Objfiles In Python. (line 6) 33221 * observer debugging info: Debugging Output. (line 101) 33222 * octal escapes in strings: Print Settings. (line 222) 33223 * older on Frame: Frames In Python. (line 58) 33224 * online documentation: Help. (line 6) 33225 * opaque data types: Symbols. (line 241) 33226 * open flags, in file-i/o protocol: Open Flags. (line 6) 33227 * open, file-i/o system call: open. (line 6) 33228 * OpenRISC 1000: OpenRISC 1000. (line 6) 33229 * OpenRISC 1000 htrace: OpenRISC 1000. (line 58) 33230 * operating system information: Operating System Information. 33231 (line 6) 33232 * operating system information, process list: Process list. (line 6) 33233 * optimized code, debugging: Optimized Code. (line 6) 33234 * optimized code, wrong values of variables: Variables. (line 58) 33235 * optimized out value in Python: Values From Inferior. 33236 (line 35) 33237 * optional debugging messages: Debugging Output. (line 6) 33238 * optional warnings: Messages/Warnings. (line 6) 33239 * or1k boards: OpenRISC 1000. (line 6) 33240 * or1ksim: OpenRISC 1000. (line 16) 33241 * OS ABI: ABI. (line 11) 33242 * OS information: OS Information. (line 6) 33243 * out-of-line single-stepping: Maintenance Commands. 33244 (line 56) 33245 * outermost frame: Frames. (line 12) 33246 * output: Output. (line 35) 33247 * output formats: Output Formats. (line 6) 33248 * output syntax of GDB/MI: GDB/MI Output Syntax. 33249 (line 6) 33250 * output-meta: Readline Init File Syntax. 33251 (line 149) 33252 * overlay: Overlay Commands. (line 17) 33253 * overlay area: How Overlays Work. (line 6) 33254 * overlay example program: Overlay Sample Program. 33255 (line 6) 33256 * overlays: Overlays. (line 6) 33257 * overlays, setting breakpoints in: Overlay Commands. (line 93) 33258 * overload-choice annotation: Prompting. (line 32) 33259 * overloaded functions, calling: C Plus Plus Expressions. 33260 (line 27) 33261 * overloaded functions, overload resolution: Debugging C Plus Plus. 33262 (line 48) 33263 * overloading in C++: Debugging C Plus Plus. 33264 (line 15) 33265 * overwrite-mode (): Commands For Text. (line 53) 33266 * p packet: Packets. (line 241) 33267 * P packet: Packets. (line 256) 33268 * packet acknowledgment, for GDB remote: Packet Acknowledgment. 33269 (line 6) 33270 * packet size, remote protocol: General Query Packets. 33271 (line 414) 33272 * packets, notification: Notification Packets. 33273 (line 6) 33274 * packets, reporting on stdout: Debugging Output. (line 123) 33275 * packets, tracepoint: Tracepoint Packets. (line 6) 33276 * page tables display (MS-DOS): DJGPP Native. (line 56) 33277 * page-completions: Readline Init File Syntax. 33278 (line 154) 33279 * parameter: Basic Python. (line 22) 33280 * parse_and_eval: Basic Python. (line 44) 33281 * partial symbol dump: Symbols. (line 259) 33282 * partial symbol tables, listing GDB's internal: Symbols. (line 278) 33283 * Pascal: Summary. (line 30) 33284 * Pascal objects, static members display: Print Settings. (line 353) 33285 * Pascal support in GDB, limitations: Pascal. (line 6) 33286 * pass signals to inferior, remote request: General Query Packets. 33287 (line 211) 33288 * passcount: Tracepoint Passcounts. 33289 (line 6) 33290 * patching binaries: Patching. (line 6) 33291 * patching object files: Files. (line 26) 33292 * path: Environment. (line 14) 33293 * pause current task (GNU Hurd): Hurd Native. (line 49) 33294 * pause current thread (GNU Hurd): Hurd Native. (line 91) 33295 * pauses in output: Screen Size. (line 6) 33296 * pc on Frame: Frames In Python. (line 55) 33297 * pending breakpoints: Set Breaks. (line 221) 33298 * PgDn: TUI Keys. (line 50) 33299 * PgUp: TUI Keys. (line 47) 33300 * physical address from linear address: DJGPP Native. (line 81) 33301 * pipe, target remote to: Connecting. (line 60) 33302 * pipes: Starting. (line 62) 33303 * pmon, MIPS remote: MIPS Embedded. (line 132) 33304 * po (print-object): The Print Command with Objective-C. 33305 (line 6) 33306 * pointer on Type: Types In Python. (line 102) 33307 * pointer values, in file-i/o protocol: Pointer Values. (line 6) 33308 * pointer, finding referent: Print Settings. (line 79) 33309 * port rights, GNU Hurd: Hurd Native. (line 85) 33310 * port sets, GNU Hurd: Hurd Native. (line 85) 33311 * possible-completions (M-?): Commands For Completion. 33312 (line 11) 33313 * post-commands annotation: Prompting. (line 27) 33314 * post-overload-choice annotation: Prompting. (line 32) 33315 * post-prompt annotation: Prompting. (line 24) 33316 * post-prompt-for-continue annotation: Prompting. (line 40) 33317 * post-query annotation: Prompting. (line 36) 33318 * PowerPC architecture: PowerPC. (line 6) 33319 * pre-commands annotation: Prompting. (line 27) 33320 * pre-overload-choice annotation: Prompting. (line 32) 33321 * pre-prompt annotation: Prompting. (line 24) 33322 * pre-prompt-for-continue annotation: Prompting. (line 40) 33323 * pre-query annotation: Prompting. (line 36) 33324 * prefix for data files: Data Files. (line 6) 33325 * prefix for shared library file names: Files. (line 374) 33326 * prefix-meta (<ESC>): Miscellaneous Commands. 33327 (line 18) 33328 * premature return from system calls: Interrupted System Calls. 33329 (line 6) 33330 * preprocessor macro expansion, showing the results of: Macros. 33331 (line 29) 33332 * pretty print arrays: Print Settings. (line 98) 33333 * pretty print C++ virtual function tables: Print Settings. (line 364) 33334 * pretty_printers: Objfiles In Python. (line 32) 33335 * previous-history (C-p): Commands For History. 33336 (line 12) 33337 * print: Data. (line 6) 33338 * print all frame argument values: Print Settings. (line 135) 33339 * print an Objective-C object description: The Print Command with Objective-C. 33340 (line 11) 33341 * print array indexes: Print Settings. (line 108) 33342 * print frame argument values for scalars only: Print Settings. 33343 (line 135) 33344 * print messages on inferior start and exit: Inferiors and Programs. 33345 (line 113) 33346 * print messages on thread start and exit: Threads. (line 159) 33347 * print settings: Print Settings. (line 6) 33348 * print structures in indented form: Print Settings. (line 198) 33349 * print-object: The Print Command with Objective-C. 33350 (line 6) 33351 * print/don't print memory addresses: Print Settings. (line 13) 33352 * printf: Output. (line 46) 33353 * printing byte arrays: Output Formats. (line 60) 33354 * printing data: Data. (line 6) 33355 * printing frame argument values: Print Settings. (line 135) 33356 * printing strings: Output Formats. (line 60) 33357 * proc-trace-entry: SVR4 Process Information. 33358 (line 70) 33359 * proc-trace-exit: SVR4 Process Information. 33360 (line 70) 33361 * proc-untrace-entry: SVR4 Process Information. 33362 (line 70) 33363 * proc-untrace-exit: SVR4 Process Information. 33364 (line 70) 33365 * process detailed status information: SVR4 Process Information. 33366 (line 40) 33367 * process ID: SVR4 Process Information. 33368 (line 16) 33369 * process info via /proc: SVR4 Process Information. 33370 (line 6) 33371 * process list, QNX Neutrino: SVR4 Process Information. 33372 (line 74) 33373 * process record and replay: Process Record and Replay. 33374 (line 6) 33375 * process status register: Registers. (line 26) 33376 * processes, multiple: Forks. (line 6) 33377 * procfs API calls: SVR4 Process Information. 33378 (line 53) 33379 * profiling GDB: Maintenance Commands. 33380 (line 261) 33381 * program counter register: Registers. (line 26) 33382 * program entry point: Backtrace. (line 93) 33383 * programming in python: Python API. (line 6) 33384 * prompt: Prompt. (line 6) 33385 * prompt annotation: Prompting. (line 24) 33386 * prompt-for-continue annotation: Prompting. (line 40) 33387 * protocol basics, file-i/o: Protocol Basics. (line 6) 33388 * protocol, GDB remote serial: Overview. (line 14) 33389 * protocol-specific representation of datatypes, in file-i/o protocol: Protocol-specific Representation of Datatypes. 33390 (line 6) 33391 * ptrace system call: OS Information. (line 9) 33392 * ptype: Symbols. (line 85) 33393 * putDebugChar: Bootstrapping. (line 20) 33394 * pwd: Working Directory. (line 19) 33395 * python: Python Commands. (line 9) 33396 * python api: Python API. (line 6) 33397 * python commands <1>: Commands In Python. (line 6) 33398 * python commands: Python Commands. (line 6) 33399 * python convenience functions: Functions In Python. (line 6) 33400 * python exceptions: Exception Handling. (line 6) 33401 * python functions: Basic Python. (line 6) 33402 * python module: Basic Python. (line 6) 33403 * python pagination: Python API. (line 6) 33404 * python scripting: Python. (line 6) 33405 * python stdout: Python API. (line 6) 33406 * Python, working with types: Types In Python. (line 6) 33407 * python, working with values from inferior: Values From Inferior. 33408 (line 6) 33409 * q (quit): Quitting GDB. (line 6) 33410 * q (SingleKey TUI key): TUI Single Key Mode. (line 22) 33411 * q packet: Packets. (line 269) 33412 * Q packet: Packets. (line 269) 33413 * qAttached packet: General Query Packets. 33414 (line 748) 33415 * qC packet: General Query Packets. 33416 (line 41) 33417 * qCRC packet: General Query Packets. 33418 (line 52) 33419 * qfThreadInfo packet: General Query Packets. 33420 (line 73) 33421 * qGetTLSAddr packet: General Query Packets. 33422 (line 101) 33423 * QNonStop packet: General Query Packets. 33424 (line 191) 33425 * QNX Neutrino: Neutrino. (line 6) 33426 * qOffsets packet: General Query Packets. 33427 (line 153) 33428 * qP packet: General Query Packets. 33429 (line 180) 33430 * QPassSignals packet: General Query Packets. 33431 (line 211) 33432 * qRcmd packet: General Query Packets. 33433 (line 239) 33434 * qSearch:memory packet: General Query Packets. 33435 (line 264) 33436 * QStartNoAckMode packet: General Query Packets. 33437 (line 284) 33438 * qsThreadInfo packet: General Query Packets. 33439 (line 73) 33440 * qSupported packet: General Query Packets. 33441 (line 299) 33442 * qSymbol packet: General Query Packets. 33443 (line 505) 33444 * QTDV packet: Tracepoint Packets. (line 90) 33445 * qThreadExtraInfo packet: General Query Packets. 33446 (line 547) 33447 * qTV packet: Tracepoint Packets. (line 174) 33448 * query annotation: Prompting. (line 36) 33449 * query attached, remote request: General Query Packets. 33450 (line 748) 33451 * quit [EXPRESSION]: Quitting GDB. (line 6) 33452 * quit annotation: Errors. (line 6) 33453 * quoted-insert (C-q or C-v): Commands For Text. (line 20) 33454 * quotes in commands: Completion. (line 57) 33455 * quoting Ada internal identifiers: Additions to Ada. (line 76) 33456 * quoting names: Symbols. (line 14) 33457 * qXfer packet: General Query Packets. 33458 (line 580) 33459 * r (run): Starting. (line 6) 33460 * r (SingleKey TUI key): TUI Single Key Mode. (line 25) 33461 * R packet: Packets. (line 278) 33462 * r packet: Packets. (line 273) 33463 * raise exceptions: Set Catchpoints. (line 197) 33464 * range checking: Type Checking. (line 65) 33465 * range on Type: Types In Python. (line 92) 33466 * ranges of breakpoints: Breakpoints. (line 48) 33467 * raw printing: Output Formats. (line 70) 33468 * rbreak: Set Breaks. (line 92) 33469 * rc (reverse-continue): Reverse Execution. (line 30) 33470 * RDI heartbeat: ARM. (line 112) 33471 * rdilogenable: ARM. (line 95) 33472 * rdilogfile: ARM. (line 89) 33473 * re-read-init-file (C-x C-r): Miscellaneous Commands. 33474 (line 6) 33475 * read special object, remote request: General Query Packets. 33476 (line 580) 33477 * read, file-i/o system call: read. (line 6) 33478 * read-only sections: Files. (line 258) 33479 * read_var on Frame: Frames In Python. (line 64) 33480 * reading symbols from relocatable object files: Files. (line 132) 33481 * reading symbols immediately: Files. (line 90) 33482 * readline: Editing. (line 6) 33483 * readnow: Files. (line 90) 33484 * rec: Process Record and Replay. 33485 (line 38) 33486 * rec del: Process Record and Replay. 33487 (line 132) 33488 * rec s: Process Record and Replay. 33489 (line 57) 33490 * receive rights, GNU Hurd: Hurd Native. (line 85) 33491 * recent tracepoint number: Create and Delete Tracepoints. 33492 (line 50) 33493 * record: Process Record and Replay. 33494 (line 38) 33495 * record aggregates (Ada): Omissions from Ada. (line 44) 33496 * record delete: Process Record and Replay. 33497 (line 132) 33498 * record mode: Process Record and Replay. 33499 (line 19) 33500 * record serial communications on file: Remote Configuration. 33501 (line 57) 33502 * record stop: Process Record and Replay. 33503 (line 57) 33504 * recording a session script: Bug Reporting. (line 104) 33505 * recording inferior's execution and replaying it: Process Record and Replay. 33506 (line 6) 33507 * redirection: Input/Output. (line 6) 33508 * redraw-current-line (): Commands For Moving. (line 30) 33509 * reference card: Formatting Documentation. 33510 (line 6) 33511 * reference declarations: C Plus Plus Expressions. 33512 (line 51) 33513 * reference on Type: Types In Python. (line 98) 33514 * refresh: TUI Commands. (line 52) 33515 * register stack, AMD29K: A29K. (line 6) 33516 * registers: Registers. (line 6) 33517 * regs, Super-H: Super-H. (line 9) 33518 * regular expression: Set Breaks. (line 92) 33519 * reloading symbols: Symbols. (line 217) 33520 * reloading the overlay table: Overlay Commands. (line 52) 33521 * relocatable object files, reading symbols from: Files. (line 132) 33522 * remote connection without stubs: Server. (line 6) 33523 * remote debugging: Remote Debugging. (line 6) 33524 * remote delete: File Transfer. (line 23) 33525 * remote get: File Transfer. (line 19) 33526 * remote memory comparison: Memory. (line 115) 33527 * remote monitor prompt: MIPS Embedded. (line 107) 33528 * remote packets, enabling and disabling: Remote Configuration. 33529 (line 132) 33530 * remote programs, interrupting: Connecting. (line 78) 33531 * remote protocol debugging: Debugging Output. (line 123) 33532 * remote protocol, binary data: Overview. (line 61) 33533 * remote protocol, field separator: Overview. (line 53) 33534 * remote put: File Transfer. (line 15) 33535 * remote query requests: General Query Packets. 33536 (line 6) 33537 * remote serial debugging summary: Debug Session. (line 6) 33538 * remote serial debugging, overview: Remote Stub. (line 14) 33539 * remote serial protocol: Overview. (line 14) 33540 * remote serial stub: Stub Contents. (line 6) 33541 * remote serial stub list: Remote Stub. (line 54) 33542 * remote serial stub, initialization: Stub Contents. (line 10) 33543 * remote serial stub, main routine: Stub Contents. (line 15) 33544 * remote stub, example: Remote Stub. (line 6) 33545 * remote stub, support routines: Bootstrapping. (line 6) 33546 * remote target: Target Commands. (line 58) 33547 * remote target, file transfer: File Transfer. (line 6) 33548 * remote target, limit break- and watchpoints: Remote Configuration. 33549 (line 72) 33550 * remote timeout: Remote Configuration. 33551 (line 65) 33552 * remotetimeout: Sparclet. (line 12) 33553 * remove actions from a tracepoint: Tracepoint Actions. (line 17) 33554 * remove-inferior: Inferiors and Programs. 33555 (line 86) 33556 * rename, file-i/o system call: rename. (line 6) 33557 * Renesas: Remote Stub. (line 63) 33558 * repeated array elements: Print Settings. (line 176) 33559 * repeating command sequences: Command Syntax. (line 42) 33560 * repeating commands: Command Syntax. (line 21) 33561 * replay log events, remote reply: Stop Reply Packets. (line 61) 33562 * replay mode: Process Record and Replay. 33563 (line 10) 33564 * reporting bugs in GDB: GDB Bugs. (line 6) 33565 * reprint the last value: Data. (line 21) 33566 * reset SDI connection, M32R: M32R/D. (line 44) 33567 * response time, MIPS debugging: MIPS. (line 10) 33568 * restart: Checkpoint/Restart. (line 6) 33569 * restart CHECKPOINT-ID: Checkpoint/Restart. (line 44) 33570 * restore: Dump/Restore Files. (line 41) 33571 * restore data from a file: Dump/Restore Files. (line 6) 33572 * result records in GDB/MI: GDB/MI Result Records. 33573 (line 6) 33574 * resume threads of multiple processes simultaneously: All-Stop Mode. 33575 (line 53) 33576 * resuming execution: Continuing and Stepping. 33577 (line 6) 33578 * RET (repeat last command): Command Syntax. (line 21) 33579 * retransmit-timeout, MIPS protocol: MIPS Embedded. (line 83) 33580 * return: Returning. (line 6) 33581 * returning from a function: Returning. (line 6) 33582 * reverse execution: Reverse Execution. (line 6) 33583 * reverse-continue: Reverse Execution. (line 30) 33584 * reverse-finish: Reverse Execution. (line 77) 33585 * reverse-next: Reverse Execution. (line 60) 33586 * reverse-nexti: Reverse Execution. (line 69) 33587 * reverse-search: Search. (line 16) 33588 * reverse-search-history (C-r): Commands For History. 33589 (line 26) 33590 * reverse-step: Reverse Execution. (line 37) 33591 * reverse-stepi: Reverse Execution. (line 52) 33592 * revert-line (M-r): Miscellaneous Commands. 33593 (line 25) 33594 * rewind program state: Checkpoint/Restart. (line 6) 33595 * Right: TUI Keys. (line 62) 33596 * rn (reverse-next): Reverse Execution. (line 60) 33597 * rni (reverse-nexti): Reverse Execution. (line 69) 33598 * ROM at zero address, RDI: ARM. (line 102) 33599 * rs (step): Reverse Execution. (line 37) 33600 * rsi (reverse-stepi): Reverse Execution. (line 52) 33601 * run: Starting. (line 6) 33602 * run to main procedure: Starting. (line 79) 33603 * run until specified location: Continuing and Stepping. 33604 (line 118) 33605 * run&: Background Execution. 33606 (line 34) 33607 * running: Starting. (line 6) 33608 * running and debugging Sparclet programs: Sparclet Execution. 33609 (line 6) 33610 * running programs backward: Reverse Execution. (line 6) 33611 * running VxWorks tasks: VxWorks Attach. (line 6) 33612 * running, on Sparclet: Sparclet. (line 28) 33613 * rwatch: Set Watchpoints. (line 56) 33614 * s (SingleKey TUI key): TUI Single Key Mode. (line 28) 33615 * s (step): Continuing and Stepping. 33616 (line 46) 33617 * S packet: Packets. (line 291) 33618 * s packet: Packets. (line 285) 33619 * save command history: Command History. (line 36) 33620 * save GDB output to a file: Logging Output. (line 6) 33621 * save tracepoints for future sessions: save-tracepoints. (line 6) 33622 * save-tracepoints: save-tracepoints. (line 6) 33623 * scheduler locking mode: All-Stop Mode. (line 37) 33624 * scope: M2 Scope. (line 6) 33625 * scripting commands: Command Files. (line 6) 33626 * scripting with python: Python. (line 6) 33627 * sdireset: M32R/D. (line 44) 33628 * sdistatus: M32R/D. (line 47) 33629 * SDS protocol: PowerPC Embedded. (line 34) 33630 * sds, a command: PowerPC Embedded. (line 45) 33631 * search: Search. (line 9) 33632 * search path for libthread_db: Threads. (line 180) 33633 * searching memory: Searching Memory. (line 6) 33634 * searching memory, in remote debugging: General Query Packets. 33635 (line 264) 33636 * searching source files: Search. (line 6) 33637 * section: Files. (line 182) 33638 * section offsets, remote request: General Query Packets. 33639 (line 153) 33640 * segment descriptor tables: DJGPP Native. (line 24) 33641 * select Ctrl-C, BREAK or BREAK-g: Remote Configuration. 33642 (line 85) 33643 * select trace snapshot: tfind. (line 6) 33644 * select-frame: Frames. (line 51) 33645 * selected frame: Stack. (line 19) 33646 * selected_frame: Frames In Python. (line 22) 33647 * selecting frame silently: Frames. (line 51) 33648 * self-insert (a, b, A, 1, !, ...): Commands For Text. (line 27) 33649 * send command to remote monitor: Connecting. (line 105) 33650 * send command to simulator: Embedded Processors. (line 9) 33651 * send interrupt-sequence on start: Remote Configuration. 33652 (line 98) 33653 * send PMON command: MIPS Embedded. (line 132) 33654 * send rights, GNU Hurd: Hurd Native. (line 85) 33655 * sending files to remote systems: File Transfer. (line 6) 33656 * separate debugging information files: Separate Debug Files. 33657 (line 6) 33658 * sequence-id, for GDB remote: Overview. (line 29) 33659 * serial connections, debugging: Debugging Output. (line 123) 33660 * serial line, target remote: Connecting. (line 18) 33661 * serial protocol, GDB remote: Overview. (line 14) 33662 * server prefix: Server Prefix. (line 6) 33663 * server, command prefix: Command History. (line 20) 33664 * set: Help. (line 107) 33665 * set ABI for MIPS: MIPS. (line 32) 33666 * set ada trust-PAD-over-XVS: Ada Glitches. (line 48) 33667 * set annotate: Annotations Overview. 33668 (line 29) 33669 * set architecture: Targets. (line 21) 33670 * set args: Arguments. (line 21) 33671 * set arm: ARM. (line 18) 33672 * set auto-solib-add: Files. (line 303) 33673 * set backtrace: Backtrace. (line 104) 33674 * set board-address: M32R/D. (line 21) 33675 * set breakpoint always-inserted: Set Breaks. (line 303) 33676 * set breakpoint auto-hw: Set Breaks. (line 283) 33677 * set breakpoint pending: Set Breaks. (line 252) 33678 * set breakpoints in many functions: Set Breaks. (line 92) 33679 * set breakpoints on all functions: Set Breaks. (line 112) 33680 * set can-use-hw-watchpoints: Set Watchpoints. (line 83) 33681 * set case-sensitive: Symbols. (line 27) 33682 * set charset: Character Sets. (line 46) 33683 * set check range: Range Checking. (line 34) 33684 * set check type: Type Checking. (line 42) 33685 * set coerce-float-to-double: ABI. (line 41) 33686 * set com1base: DJGPP Native. (line 125) 33687 * set com1irq: DJGPP Native. (line 125) 33688 * set com2base: DJGPP Native. (line 125) 33689 * set com2irq: DJGPP Native. (line 125) 33690 * set com3base: DJGPP Native. (line 125) 33691 * set com3irq: DJGPP Native. (line 125) 33692 * set com4base: DJGPP Native. (line 125) 33693 * set com4irq: DJGPP Native. (line 125) 33694 * set complaints: Messages/Warnings. (line 29) 33695 * set confirm: Messages/Warnings. (line 50) 33696 * set cp-abi: ABI. (line 53) 33697 * set cygwin-exceptions: Cygwin Native. (line 37) 33698 * set data-directory: Data Files. (line 12) 33699 * set debug: Debugging Output. (line 18) 33700 * set debug darwin: Darwin. (line 9) 33701 * set debug hppa: HPPA. (line 10) 33702 * set debug mach-o: Darwin. (line 16) 33703 * set debug mips: MIPS. (line 81) 33704 * set debug monitor: Target Commands. (line 108) 33705 * set debug nto-debug: Neutrino. (line 9) 33706 * set debug-file-directory: Separate Debug Files. 33707 (line 68) 33708 * set debugevents: Cygwin Native. (line 66) 33709 * set debugexceptions: Cygwin Native. (line 77) 33710 * set debugexec: Cygwin Native. (line 73) 33711 * set debugmemory: Cygwin Native. (line 81) 33712 * set default-collect: Tracepoint Actions. (line 89) 33713 * set demangle-style: Print Settings. (line 296) 33714 * set detach-on-fork: Forks. (line 55) 33715 * set disable-randomization: Starting. (line 136) 33716 * set disassemble-next-line: Machine Code. (line 119) 33717 * set disassembly-flavor: Machine Code. (line 107) 33718 * set disconnected-tracing: Starting and Stopping Trace Experiments. 33719 (line 48) 33720 * set displaced-stepping: Maintenance Commands. 33721 (line 56) 33722 * set download-path: M32R/D. (line 15) 33723 * set editing: Editing. (line 15) 33724 * set endian: Byte Order. (line 13) 33725 * set environment: Environment. (line 39) 33726 * set exceptions, Hurd command: Hurd Native. (line 40) 33727 * set exec-direction: Reverse Execution. (line 83) 33728 * set exec-done-display: Debugging Output. (line 11) 33729 * set exec-wrapper: Starting. (line 111) 33730 * set extension-language: Show. (line 30) 33731 * set fast tracepoint: Create and Delete Tracepoints. 33732 (line 40) 33733 * set follow-exec-mode: Forks. (line 101) 33734 * set follow-fork-mode: Forks. (line 35) 33735 * set gnutarget: Target Commands. (line 28) 33736 * set hash, for remote monitors: Target Commands. (line 99) 33737 * set height: Screen Size. (line 21) 33738 * set history expansion: Command History. (line 65) 33739 * set history filename: Command History. (line 26) 33740 * set history save: Command History. (line 36) 33741 * set history size: Command History. (line 45) 33742 * set host-charset: Character Sets. (line 33) 33743 * set inferior controlling terminal: Input/Output. (line 44) 33744 * set inferior-tty: Input/Output. (line 49) 33745 * set input-radix: Numbers. (line 14) 33746 * set interactive-mode: Other Misc Settings. (line 6) 33747 * set language: Manually. (line 9) 33748 * set libthread-db-search-path: Threads. (line 180) 33749 * set listsize: List. (line 33) 33750 * set logging: Logging Output. (line 9) 33751 * set mach-exceptions: Darwin. (line 27) 33752 * set max-user-call-depth: Define. (line 76) 33753 * set mem inaccessible-by-default: Memory Region Attributes. 33754 (line 130) 33755 * set mips abi: MIPS. (line 32) 33756 * set mips mask-address: MIPS. (line 61) 33757 * set mipsfpu: MIPS Embedded. (line 60) 33758 * set monitor-prompt, MIPS remote: MIPS Embedded. (line 107) 33759 * set monitor-warnings, MIPS remote: MIPS Embedded. (line 123) 33760 * set multiple-symbols: Ambiguous Expressions. 33761 (line 50) 33762 * set new-console: Cygwin Native. (line 49) 33763 * set new-group: Cygwin Native. (line 58) 33764 * set non-stop: Non-Stop Mode. (line 38) 33765 * set opaque-type-resolution: Symbols. (line 241) 33766 * set osabi: ABI. (line 11) 33767 * set output-radix: Numbers. (line 31) 33768 * set overload-resolution: Debugging C Plus Plus. 33769 (line 48) 33770 * set pagination: Screen Size. (line 38) 33771 * set powerpc: PowerPC Embedded. (line 8) 33772 * set print: Print Settings. (line 11) 33773 * set print frame-arguments: Print Settings. (line 135) 33774 * set print inferior-events: Inferiors and Programs. 33775 (line 113) 33776 * set print thread-events: Threads. (line 159) 33777 * set processor: Targets. (line 31) 33778 * set procfs-file: SVR4 Process Information. 33779 (line 59) 33780 * set procfs-trace: SVR4 Process Information. 33781 (line 53) 33782 * set prompt: Prompt. (line 16) 33783 * set radix: Numbers. (line 44) 33784 * set rdiheartbeat: ARM. (line 112) 33785 * set rdiromatzero: ARM. (line 102) 33786 * set record insn-number-max: Process Record and Replay. 33787 (line 80) 33788 * set record stop-at-limit: Process Record and Replay. 33789 (line 100) 33790 * set remote: Remote Configuration. 33791 (line 6) 33792 * set remote system-call-allowed: system. (line 38) 33793 * set remote-mips64-transfers-32bit-regs: MIPS. (line 71) 33794 * set remotecache: Caching Remote Data. (line 18) 33795 * set remoteflow: Remote Configuration. 33796 (line 41) 33797 * set retransmit-timeout: MIPS Embedded. (line 83) 33798 * set rstack_high_address: A29K. (line 6) 33799 * set schedule-multiple: All-Stop Mode. (line 66) 33800 * set script-extension: Extending GDB. (line 19) 33801 * set sdstimeout: PowerPC Embedded. (line 38) 33802 * set server-address: M32R/D. (line 27) 33803 * set sh calling-convention: Super-H. (line 12) 33804 * set shell: Cygwin Native. (line 85) 33805 * set signal-thread: Hurd Native. (line 21) 33806 * set signals, Hurd command: Hurd Native. (line 11) 33807 * set sigs, Hurd command: Hurd Native. (line 11) 33808 * set sigthread: Hurd Native. (line 21) 33809 * set solib-absolute-prefix: Files. (line 374) 33810 * set solib-search-path: Files. (line 402) 33811 * set spu: SPU. (line 39) 33812 * set stack-cache: Caching Remote Data. (line 26) 33813 * set step-mode: Continuing and Stepping. 33814 (line 92) 33815 * set stop-on-solib-events: Files. (line 351) 33816 * set stopped, Hurd command: Hurd Native. (line 32) 33817 * set struct-convention: i386. (line 7) 33818 * set substitute-path: Source Path. (line 123) 33819 * set symbol-reloading: Symbols. (line 224) 33820 * set syn-garbage-limit, MIPS remote: MIPS Embedded. (line 98) 33821 * set sysroot: Files. (line 374) 33822 * set target-async: Background Execution. 33823 (line 17) 33824 * set target-charset: Character Sets. (line 28) 33825 * set target-wide-charset: Character Sets. (line 61) 33826 * set task, Hurd commands: Hurd Native. (line 49) 33827 * set tcp: Remote Configuration. 33828 (line 107) 33829 * set tdesc filename: Retrieving Descriptions. 33830 (line 18) 33831 * set thread, Hurd command: Hurd Native. (line 91) 33832 * set timeout: MIPS Embedded. (line 83) 33833 * set trace-commands: Messages/Warnings. (line 65) 33834 * set tracepoint: Create and Delete Tracepoints. 33835 (line 6) 33836 * set trust-readonly-sections: Files. (line 258) 33837 * set tui active-border-mode: TUI Configuration. (line 24) 33838 * set tui border-kind: TUI Configuration. (line 9) 33839 * set tui border-mode: TUI Configuration. (line 23) 33840 * set unwind-on-terminating-exception: Calling. (line 46) 33841 * set unwindonsignal: Calling. (line 35) 33842 * set variable: Assignment. (line 16) 33843 * set verbose: Messages/Warnings. (line 15) 33844 * set watchdog: Maintenance Commands. 33845 (line 321) 33846 * set width: Screen Size. (line 21) 33847 * set write: Patching. (line 15) 33848 * set-mark (C-@): Miscellaneous Commands. 33849 (line 32) 33850 * set_debug_traps: Stub Contents. (line 10) 33851 * setting variables: Assignment. (line 6) 33852 * setting watchpoints: Set Watchpoints. (line 6) 33853 * SH: Remote Stub. (line 63) 33854 * sh-stub.c: Remote Stub. (line 63) 33855 * share: Files. (line 332) 33856 * shared libraries: Files. (line 281) 33857 * shared library events, remote reply: Stop Reply Packets. (line 56) 33858 * sharedlibrary: Files. (line 332) 33859 * shell: Shell Commands. (line 10) 33860 * shell escape: Shell Commands. (line 10) 33861 * show: Help. (line 112) 33862 * show ada trust-PAD-over-XVS: Ada Glitches. (line 48) 33863 * show all convenience functions: Convenience Vars. (line 98) 33864 * show all user variables: Convenience Vars. (line 37) 33865 * show annotate: Annotations Overview. 33866 (line 34) 33867 * show architecture: Targets. (line 21) 33868 * show args: Arguments. (line 28) 33869 * show arm: ARM. (line 22) 33870 * show auto-solib-add: Files. (line 320) 33871 * show backtrace: Backtrace. (line 111) 33872 * show board-address: M32R/D. (line 24) 33873 * show breakpoint always-inserted: Set Breaks. (line 303) 33874 * show breakpoint auto-hw: Set Breaks. (line 283) 33875 * show breakpoint pending: Set Breaks. (line 252) 33876 * show can-use-hw-watchpoints: Set Watchpoints. (line 86) 33877 * show case-sensitive: Symbols. (line 40) 33878 * show charset: Character Sets. (line 52) 33879 * show check range: Range Checking. (line 34) 33880 * show check type: Type Checking. (line 42) 33881 * show coerce-float-to-double: ABI. (line 50) 33882 * show com1base: DJGPP Native. (line 137) 33883 * show com1irq: DJGPP Native. (line 137) 33884 * show com2base: DJGPP Native. (line 137) 33885 * show com2irq: DJGPP Native. (line 137) 33886 * show com3base: DJGPP Native. (line 137) 33887 * show com3irq: DJGPP Native. (line 137) 33888 * show com4base: DJGPP Native. (line 137) 33889 * show com4irq: DJGPP Native. (line 137) 33890 * show commands: Command History. (line 78) 33891 * show complaints: Messages/Warnings. (line 35) 33892 * show confirm: Messages/Warnings. (line 56) 33893 * show convenience: Convenience Vars. (line 37) 33894 * show copying: Help. (line 136) 33895 * show cp-abi: ABI. (line 53) 33896 * show cygwin-exceptions: Cygwin Native. (line 45) 33897 * show data-directory: Data Files. (line 16) 33898 * show debug: Debugging Output. (line 22) 33899 * show debug darwin: Darwin. (line 13) 33900 * show debug mach-o: Darwin. (line 23) 33901 * show debug mips: MIPS. (line 85) 33902 * show debug monitor: Target Commands. (line 112) 33903 * show debug nto-debug: Neutrino. (line 13) 33904 * show debug-file-directory: Separate Debug Files. 33905 (line 73) 33906 * show default-collect: Tracepoint Actions. (line 98) 33907 * show detach-on-fork: Forks. (line 71) 33908 * show directories: Source Path. (line 120) 33909 * show disassemble-next-line: Machine Code. (line 119) 33910 * show disassembly-flavor: Machine Code. (line 116) 33911 * show disconnected-tracing: Starting and Stopping Trace Experiments. 33912 (line 55) 33913 * show displaced-stepping: Maintenance Commands. 33914 (line 56) 33915 * show download-path: M32R/D. (line 18) 33916 * show editing: Editing. (line 22) 33917 * show environment: Environment. (line 33) 33918 * show exceptions, Hurd command: Hurd Native. (line 46) 33919 * show exec-done-display: Debugging Output. (line 14) 33920 * show follow-fork-mode: Forks. (line 49) 33921 * show gnutarget: Target Commands. (line 40) 33922 * show hash, for remote monitors: Target Commands. (line 105) 33923 * show height: Screen Size. (line 21) 33924 * show history: Command History. (line 70) 33925 * show host-charset: Character Sets. (line 55) 33926 * show inferior-tty: Input/Output. (line 52) 33927 * show input-radix: Numbers. (line 36) 33928 * show interactive-mode: Other Misc Settings. (line 17) 33929 * show language: Show. (line 10) 33930 * show last commands: Command History. (line 78) 33931 * show libthread-db-search-path: Threads. (line 204) 33932 * show listsize: List. (line 37) 33933 * show logging: Logging Output. (line 26) 33934 * show mach-exceptions: Darwin. (line 34) 33935 * show max-user-call-depth: Define. (line 76) 33936 * show mem inaccessible-by-default: Memory Region Attributes. 33937 (line 136) 33938 * show mips abi: MIPS. (line 54) 33939 * show mips mask-address: MIPS. (line 67) 33940 * show mipsfpu: MIPS Embedded. (line 60) 33941 * show monitor-prompt, MIPS remote: MIPS Embedded. (line 119) 33942 * show monitor-warnings, MIPS remote: MIPS Embedded. (line 129) 33943 * show multiple-symbols: Ambiguous Expressions. 33944 (line 70) 33945 * show new-console: Cygwin Native. (line 54) 33946 * show new-group: Cygwin Native. (line 63) 33947 * show non-stop: Non-Stop Mode. (line 42) 33948 * show opaque-type-resolution: Symbols. (line 256) 33949 * show osabi: ABI. (line 11) 33950 * show output-radix: Numbers. (line 39) 33951 * show overload-resolution: Debugging C Plus Plus. 33952 (line 65) 33953 * show pagination: Screen Size. (line 42) 33954 * show paths: Environment. (line 29) 33955 * show print: Print Settings. (line 39) 33956 * show print inferior-events: Inferiors and Programs. 33957 (line 121) 33958 * show print thread-events: Threads. (line 169) 33959 * show processor: Targets. (line 31) 33960 * show procfs-file: SVR4 Process Information. 33961 (line 64) 33962 * show procfs-trace: SVR4 Process Information. 33963 (line 56) 33964 * show prompt: Prompt. (line 19) 33965 * show python auto-load: Auto-loading. (line 37) 33966 * show radix: Numbers. (line 44) 33967 * show rdiheartbeat: ARM. (line 117) 33968 * show rdiromatzero: ARM. (line 109) 33969 * show record insn-number-max: Process Record and Replay. 33970 (line 97) 33971 * show record stop-at-limit: Process Record and Replay. 33972 (line 111) 33973 * show remote: Remote Configuration. 33974 (line 6) 33975 * show remote system-call-allowed: system. (line 42) 33976 * show remote-mips64-transfers-32bit-regs: MIPS. (line 77) 33977 * show remotecache: Caching Remote Data. (line 23) 33978 * show remoteflow: Remote Configuration. 33979 (line 45) 33980 * show retransmit-timeout: MIPS Embedded. (line 83) 33981 * show rstack_high_address: A29K. (line 17) 33982 * show script-extension: Extending GDB. (line 19) 33983 * show sdstimeout: PowerPC Embedded. (line 42) 33984 * show server-address: M32R/D. (line 31) 33985 * show sh calling-convention: Super-H. (line 25) 33986 * show shell: Cygwin Native. (line 89) 33987 * show signal-thread: Hurd Native. (line 28) 33988 * show signals, Hurd command: Hurd Native. (line 17) 33989 * show sigs, Hurd command: Hurd Native. (line 17) 33990 * show sigthread: Hurd Native. (line 28) 33991 * show solib-search-path: Files. (line 413) 33992 * show spu: SPU. (line 44) 33993 * show stack-cache: Caching Remote Data. (line 31) 33994 * show stop-on-solib-events: Files. (line 357) 33995 * show stopped, Hurd command: Hurd Native. (line 37) 33996 * show struct-convention: i386. (line 15) 33997 * show substitute-path: Source Path. (line 160) 33998 * show symbol-reloading: Symbols. (line 238) 33999 * show syn-garbage-limit, MIPS remote: MIPS Embedded. (line 103) 34000 * show sysroot: Files. (line 399) 34001 * show target-async: Background Execution. 34002 (line 21) 34003 * show target-charset: Character Sets. (line 58) 34004 * show target-wide-charset: Character Sets. (line 67) 34005 * show task, Hurd commands: Hurd Native. (line 57) 34006 * show tcp: Remote Configuration. 34007 (line 107) 34008 * show tdesc filename: Retrieving Descriptions. 34009 (line 25) 34010 * show thread, Hurd command: Hurd Native. (line 101) 34011 * show timeout: MIPS Embedded. (line 83) 34012 * show unwind-on-terminating-exception: Calling. (line 54) 34013 * show unwindonsignal: Calling. (line 42) 34014 * show user: Define. (line 70) 34015 * show values: Value History. (line 47) 34016 * show verbose: Messages/Warnings. (line 21) 34017 * show version: Help. (line 126) 34018 * show warranty: Help. (line 140) 34019 * show width: Screen Size. (line 21) 34020 * show write: Patching. (line 26) 34021 * show-all-if-ambiguous: Readline Init File Syntax. 34022 (line 164) 34023 * show-all-if-unmodified: Readline Init File Syntax. 34024 (line 170) 34025 * si (stepi): Continuing and Stepping. 34026 (line 190) 34027 * signal: Signaling. (line 6) 34028 * signal annotation: Annotations for Running. 34029 (line 42) 34030 * signal-name annotation: Annotations for Running. 34031 (line 22) 34032 * signal-name-end annotation: Annotations for Running. 34033 (line 22) 34034 * signal-string annotation: Annotations for Running. 34035 (line 22) 34036 * signal-string-end annotation: Annotations for Running. 34037 (line 22) 34038 * signalled annotation: Annotations for Running. 34039 (line 22) 34040 * signals: Signals. (line 6) 34041 * SIGQUIT signal, dump core of GDB: Maintenance Commands. 34042 (line 99) 34043 * silent: Break Commands. (line 38) 34044 * sim: Z8000. (line 15) 34045 * sim, a command: Embedded Processors. (line 13) 34046 * simulator, Z8000: Z8000. (line 6) 34047 * size of remote memory accesses: Packets. (line 215) 34048 * size of screen: Screen Size. (line 6) 34049 * sizeof: Types In Python. (line 25) 34050 * snapshot of a process: Checkpoint/Restart. (line 6) 34051 * software watchpoints: Set Watchpoints. (line 31) 34052 * source: Command Files. (line 17) 34053 * source annotation: Source Annotations. (line 6) 34054 * source file and line of a symbol: Print Settings. (line 51) 34055 * source line and its code address: Machine Code. (line 6) 34056 * source path: Source Path. (line 6) 34057 * Sparc: Remote Stub. (line 66) 34058 * sparc-stub.c: Remote Stub. (line 66) 34059 * sparcl-stub.c: Remote Stub. (line 69) 34060 * Sparclet: Sparclet. (line 6) 34061 * SparcLite: Remote Stub. (line 69) 34062 * Special Fortran commands: Special Fortran Commands. 34063 (line 6) 34064 * specifying location: Specify Location. (line 6) 34065 * spr: OpenRISC 1000. (line 33) 34066 * SPU: SPU. (line 6) 34067 * SSE registers (x86): Registers. (line 71) 34068 * stack frame: Frames. (line 6) 34069 * stack on Alpha: MIPS. (line 6) 34070 * stack on MIPS: MIPS. (line 6) 34071 * stack pointer register: Registers. (line 26) 34072 * stacking targets: Active Targets. (line 6) 34073 * standard registers: Registers. (line 26) 34074 * start: Starting. (line 78) 34075 * start a new trace experiment: Starting and Stopping Trace Experiments. 34076 (line 6) 34077 * start-kbd-macro (C-x (): Keyboard Macros. (line 6) 34078 * starting: Starting. (line 6) 34079 * starting annotation: Annotations for Running. 34080 (line 6) 34081 * startup code, and backtrace: Backtrace. (line 93) 34082 * stat, file-i/o system call: stat/fstat. (line 6) 34083 * static members of C++ objects: Print Settings. (line 342) 34084 * static members of Pascal objects: Print Settings. (line 353) 34085 * status of trace data collection: Starting and Stopping Trace Experiments. 34086 (line 20) 34087 * status output in GDB/MI: GDB/MI Output Syntax. 34088 (line 94) 34089 * step: Continuing and Stepping. 34090 (line 46) 34091 * step&: Background Execution. 34092 (line 41) 34093 * stepi: Continuing and Stepping. 34094 (line 190) 34095 * stepi&: Background Execution. 34096 (line 44) 34097 * stepping: Continuing and Stepping. 34098 (line 6) 34099 * stepping into functions with no line info: Continuing and Stepping. 34100 (line 93) 34101 * stop a running trace experiment: Starting and Stopping Trace Experiments. 34102 (line 12) 34103 * stop on C++ exceptions: Set Catchpoints. (line 13) 34104 * stop reply packets: Stop Reply Packets. (line 6) 34105 * stop, a pseudo-command: Hooks. (line 21) 34106 * stopped threads: Thread Stops. (line 6) 34107 * stopping annotation: Annotations for Running. 34108 (line 6) 34109 * stream records in GDB/MI: GDB/MI Stream Records. 34110 (line 6) 34111 * string on Value: Values From Inferior. 34112 (line 69) 34113 * strip_typedefs on Type: Types In Python. (line 106) 34114 * struct return convention: i386. (line 7) 34115 * struct stat, in file-i/o protocol: struct stat. (line 6) 34116 * struct timeval, in file-i/o protocol: struct timeval. (line 6) 34117 * struct user contents: OS Information. (line 9) 34118 * struct/union returned in registers: i386. (line 7) 34119 * structure field name completion: Completion. (line 96) 34120 * stub example, remote debugging: Remote Stub. (line 6) 34121 * stupid questions: Messages/Warnings. (line 50) 34122 * Super-H: Super-H. (line 6) 34123 * supported packets, remote query: General Query Packets. 34124 (line 299) 34125 * switching threads: Threads. (line 6) 34126 * switching threads automatically: All-Stop Mode. (line 28) 34127 * symbol decoding style, C++: Print Settings. (line 296) 34128 * symbol dump: Symbols. (line 259) 34129 * symbol from address: Symbols. (line 54) 34130 * symbol lookup, remote request: General Query Packets. 34131 (line 505) 34132 * symbol names: Symbols. (line 14) 34133 * symbol table: Files. (line 6) 34134 * symbol tables, listing GDB's internal: Symbols. (line 278) 34135 * symbol, source file and line: Print Settings. (line 51) 34136 * symbol-file: Files. (line 45) 34137 * symbols, reading from relocatable object files: Files. (line 132) 34138 * symbols, reading immediately: Files. (line 90) 34139 * synchronize with remote MIPS target: MIPS Embedded. (line 98) 34140 * syscall DSO: Files. (line 162) 34141 * sysinfo: DJGPP Native. (line 19) 34142 * system calls and thread breakpoints: Interrupted System Calls. 34143 (line 6) 34144 * system root, alternate: Files. (line 374) 34145 * system, file-i/o system call: system. (line 6) 34146 * system-wide init file: System-wide configuration. 34147 (line 6) 34148 * T packet: Packets. (line 303) 34149 * t packet: Packets. (line 298) 34150 * T packet reply: Stop Reply Packets. (line 22) 34151 * tabset: TUI Commands. (line 78) 34152 * tag: Types In Python. (line 30) 34153 * target: Target Commands. (line 49) 34154 * target architecture: Targets. (line 17) 34155 * target array: MIPS Embedded. (line 49) 34156 * target byte order: Byte Order. (line 6) 34157 * target character set: Character Sets. (line 6) 34158 * target dbug: M68K. (line 9) 34159 * target ddb PORT: MIPS Embedded. (line 41) 34160 * target debugging info: Debugging Output. (line 148) 34161 * target descriptions: Target Descriptions. (line 6) 34162 * target descriptions, ARM features: ARM Features. (line 6) 34163 * target descriptions, i386 features: i386 Features. (line 6) 34164 * target descriptions, inclusion: Target Description Format. 34165 (line 54) 34166 * target descriptions, M68K features: M68K Features. (line 6) 34167 * target descriptions, MIPS features: MIPS Features. (line 6) 34168 * target descriptions, PowerPC features: PowerPC Features. (line 6) 34169 * target descriptions, predefined types: Predefined Target Types. 34170 (line 6) 34171 * target descriptions, standard features: Standard Target Features. 34172 (line 6) 34173 * target descriptions, XML format: Target Description Format. 34174 (line 6) 34175 * target dink32: PowerPC Embedded. (line 23) 34176 * target jtag: OpenRISC 1000. (line 9) 34177 * target lsi PORT: MIPS Embedded. (line 44) 34178 * target m32r: M32R/D. (line 6) 34179 * target m32rsdi: M32R/D. (line 9) 34180 * target mips PORT: MIPS Embedded. (line 14) 34181 * target on Type: Types In Python. (line 110) 34182 * target op50n: PA. (line 6) 34183 * target output in GDB/MI: GDB/MI Output Syntax. 34184 (line 110) 34185 * target pmon PORT: MIPS Embedded. (line 38) 34186 * target ppcbug: PowerPC Embedded. (line 26) 34187 * target ppcbug1: PowerPC Embedded. (line 27) 34188 * target r3900: MIPS Embedded. (line 46) 34189 * target rdi: ARM. (line 6) 34190 * target rdp: ARM. (line 11) 34191 * target record: Process Record and Replay. 34192 (line 38) 34193 * target remote: Connecting. (line 11) 34194 * target sds: PowerPC Embedded. (line 31) 34195 * target sim, with Z8000: Z8000. (line 15) 34196 * target sparclite: Sparclite. (line 6) 34197 * target stack description: Maintenance Commands. 34198 (line 228) 34199 * target tfile: Trace Files. (line 22) 34200 * target vxworks: VxWorks. (line 6) 34201 * target w89k: PA. (line 9) 34202 * task (Ada): Ada Tasks. (line 105) 34203 * task attributes (GNU Hurd): Hurd Native. (line 49) 34204 * task breakpoints, in Ada: Ada Tasks. (line 135) 34205 * task exception port, GNU Hurd: Hurd Native. (line 68) 34206 * task suspend count: Hurd Native. (line 60) 34207 * tbreak: Set Breaks. (line 55) 34208 * TCP port, target remote: Connecting. (line 29) 34209 * tdump: tdump. (line 6) 34210 * template_argument on Type: Types In Python. (line 125) 34211 * terminal: Input/Output. (line 6) 34212 * teval (tracepoints): Tracepoint Actions. (line 67) 34213 * Text User Interface: TUI. (line 6) 34214 * tfile: Trace Files. (line 22) 34215 * tfind: tfind. (line 6) 34216 * thbreak: Set Breaks. (line 82) 34217 * this, inside C++ member functions: C Plus Plus Expressions. 34218 (line 22) 34219 * thread apply: Threads. (line 150) 34220 * thread attributes info, remote request: General Query Packets. 34221 (line 547) 34222 * thread breakpoints: Thread-Specific Breakpoints. 34223 (line 10) 34224 * thread breakpoints and system calls: Interrupted System Calls. 34225 (line 6) 34226 * thread default settings, GNU Hurd: Hurd Native. (line 131) 34227 * thread identifier (GDB): Threads. (line 63) 34228 * thread identifier (GDB), on HP-UX: Threads. (line 89) 34229 * thread identifier (system): Threads. (line 51) 34230 * thread identifier (system), on HP-UX: Threads. (line 93) 34231 * thread info (Solaris): Threads. (line 133) 34232 * thread information, remote request: General Query Packets. 34233 (line 180) 34234 * thread list format: Thread List Format. (line 6) 34235 * thread number: Threads. (line 63) 34236 * thread properties, GNU Hurd: Hurd Native. (line 91) 34237 * thread suspend count, GNU Hurd: Hurd Native. (line 110) 34238 * thread THREADNO: Threads. (line 135) 34239 * THREAD-ID, in remote protocol: Packets. (line 20) 34240 * threads and watchpoints: Set Watchpoints. (line 147) 34241 * threads of execution: Threads. (line 6) 34242 * threads, automatic switching: All-Stop Mode. (line 28) 34243 * threads, continuing: Thread Stops. (line 6) 34244 * threads, stopped: Thread Stops. (line 6) 34245 * time of command execution: Maintenance Commands. 34246 (line 292) 34247 * timeout for commands: Maintenance Commands. 34248 (line 321) 34249 * timeout for serial communications: Remote Configuration. 34250 (line 65) 34251 * timeout, for remote target connection: Remote Configuration. 34252 (line 123) 34253 * timeout, MIPS protocol: MIPS Embedded. (line 83) 34254 * timestampping debugging info: Debugging Output. (line 159) 34255 * tload, M32R: M32R/D. (line 39) 34256 * to_string on pretty printer: Pretty Printing. (line 77) 34257 * trace: Create and Delete Tracepoints. 34258 (line 6) 34259 * trace experiment, status of: Starting and Stopping Trace Experiments. 34260 (line 20) 34261 * trace file format: Trace File Format. (line 6) 34262 * trace files: Trace Files. (line 6) 34263 * trace state variable value, remote request: Tracepoint Packets. 34264 (line 174) 34265 * trace state variables: Trace State Variables. 34266 (line 6) 34267 * traceback: Backtrace. (line 6) 34268 * tracepoint actions: Tracepoint Actions. (line 6) 34269 * tracepoint conditions: Tracepoint Conditions. 34270 (line 6) 34271 * tracepoint data, display: tdump. (line 6) 34272 * tracepoint deletion: Create and Delete Tracepoints. 34273 (line 53) 34274 * tracepoint number: Create and Delete Tracepoints. 34275 (line 50) 34276 * tracepoint packets: Tracepoint Packets. (line 6) 34277 * tracepoint pass count: Tracepoint Passcounts. 34278 (line 6) 34279 * tracepoint variables: Tracepoint Variables. 34280 (line 6) 34281 * tracepoints: Tracepoints. (line 6) 34282 * trailing underscore, in Fortran symbols: Fortran. (line 9) 34283 * translating between character sets: Character Sets. (line 6) 34284 * transpose-chars (C-t): Commands For Text. (line 30) 34285 * transpose-words (M-t): Commands For Text. (line 36) 34286 * tsave: Trace Files. (line 12) 34287 * tstart: Starting and Stopping Trace Experiments. 34288 (line 6) 34289 * tstatus: Starting and Stopping Trace Experiments. 34290 (line 20) 34291 * tstop: Starting and Stopping Trace Experiments. 34292 (line 12) 34293 * tty: Input/Output. (line 23) 34294 * TUI: TUI. (line 6) 34295 * TUI commands: TUI Commands. (line 6) 34296 * TUI configuration variables: TUI Configuration. (line 6) 34297 * TUI key bindings: TUI Keys. (line 6) 34298 * tui reg: TUI Commands. (line 55) 34299 * TUI single key mode: TUI Single Key Mode. (line 6) 34300 * tvariable: Trace State Variables. 34301 (line 26) 34302 * type <1>: Values From Inferior. 34303 (line 41) 34304 * type: Lazy Strings In Python. 34305 (line 44) 34306 * type casting memory: Expressions. (line 43) 34307 * type chain of a data type: Maintenance Commands. 34308 (line 240) 34309 * type checking: Checks. (line 31) 34310 * type conversions in C++: C Plus Plus Expressions. 34311 (line 27) 34312 * type on Frame: Frames In Python. (line 44) 34313 * TYPE_CODE_ARRAY: Types In Python. (line 142) 34314 * TYPE_CODE_BITSTRING: Types In Python. (line 180) 34315 * TYPE_CODE_BOOL: Types In Python. (line 201) 34316 * TYPE_CODE_CHAR: Types In Python. (line 198) 34317 * TYPE_CODE_COMPLEX: Types In Python. (line 204) 34318 * TYPE_CODE_DECFLOAT: Types In Python. (line 213) 34319 * TYPE_CODE_ENUM: Types In Python. (line 151) 34320 * TYPE_CODE_ERROR: Types In Python. (line 183) 34321 * TYPE_CODE_FLAGS: Types In Python. (line 154) 34322 * TYPE_CODE_FLT: Types In Python. (line 163) 34323 * TYPE_CODE_FUNC: Types In Python. (line 157) 34324 * TYPE_CODE_INT: Types In Python. (line 160) 34325 * TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 216) 34326 * TYPE_CODE_MEMBERPTR: Types In Python. (line 192) 34327 * TYPE_CODE_METHOD: Types In Python. (line 186) 34328 * TYPE_CODE_METHODPTR: Types In Python. (line 189) 34329 * TYPE_CODE_NAMESPACE: Types In Python. (line 210) 34330 * TYPE_CODE_PTR: Types In Python. (line 139) 34331 * TYPE_CODE_RANGE: Types In Python. (line 172) 34332 * TYPE_CODE_REF: Types In Python. (line 195) 34333 * TYPE_CODE_SET: Types In Python. (line 169) 34334 * TYPE_CODE_STRING: Types In Python. (line 175) 34335 * TYPE_CODE_STRUCT: Types In Python. (line 145) 34336 * TYPE_CODE_TYPEDEF: Types In Python. (line 207) 34337 * TYPE_CODE_UNION: Types In Python. (line 148) 34338 * TYPE_CODE_VOID: Types In Python. (line 166) 34339 * types in Python: Types In Python. (line 6) 34340 * u (SingleKey TUI key): TUI Single Key Mode. (line 31) 34341 * u (until): Continuing and Stepping. 34342 (line 118) 34343 * UDP port, target remote: Connecting. (line 49) 34344 * undisplay: Auto Display. (line 45) 34345 * undo (C-_ or C-x C-u): Miscellaneous Commands. 34346 (line 22) 34347 * union field name completion: Completion. (line 96) 34348 * unions in structures, printing: Print Settings. (line 236) 34349 * universal-argument (): Numeric Arguments. (line 10) 34350 * unix-filename-rubout (): Commands For Killing. 34351 (line 32) 34352 * unix-line-discard (C-u): Commands For Killing. 34353 (line 12) 34354 * unix-word-rubout (C-w): Commands For Killing. 34355 (line 28) 34356 * unknown address, locating: Output Formats. (line 35) 34357 * unlink, file-i/o system call: unlink. (line 6) 34358 * unlinked object files: Files. (line 26) 34359 * unload symbols from shared libraries: Files. (line 341) 34360 * unmap an overlay: Overlay Commands. (line 39) 34361 * unmapped overlays: How Overlays Work. (line 6) 34362 * unqualified on Type: Types In Python. (line 87) 34363 * unset environment: Environment. (line 55) 34364 * unset substitute-path: Source Path. (line 152) 34365 * unset tdesc filename: Retrieving Descriptions. 34366 (line 21) 34367 * unsupported languages: Unsupported Languages. 34368 (line 6) 34369 * until: Continuing and Stepping. 34370 (line 118) 34371 * until&: Background Execution. 34372 (line 59) 34373 * unwind stack in called functions: Calling. (line 35) 34374 * unwind stack in called functions with unhandled exceptions: Calling. 34375 (line 46) 34376 * unwind_stop_reason on Frame: Frames In Python. (line 49) 34377 * up: Selection. (line 35) 34378 * Up: TUI Keys. (line 53) 34379 * up-silently: Selection. (line 64) 34380 * upcase-word (M-u): Commands For Text. (line 41) 34381 * update: TUI Commands. (line 70) 34382 * upload, M32R: M32R/D. (line 34) 34383 * use only software watchpoints: Set Watchpoints. (line 75) 34384 * use_dbt_break: M32R/D. (line 64) 34385 * use_debug_dma: M32R/D. (line 53) 34386 * use_ib_break: M32R/D. (line 61) 34387 * use_mon_code: M32R/D. (line 57) 34388 * user-defined command: Define. (line 6) 34389 * user-defined macros: Macros. (line 52) 34390 * user-defined variables: Convenience Vars. (line 6) 34391 * v (SingleKey TUI key): TUI Single Key Mode. (line 34) 34392 * value history: Value History. (line 6) 34393 * value on LazyString: Lazy Strings In Python. 34394 (line 21) 34395 * value optimized out, in backtrace: Backtrace. (line 71) 34396 * values from inferior, with Python: Values From Inferior. 34397 (line 6) 34398 * variable name conflict: Variables. (line 36) 34399 * variable object debugging info: Debugging Output. (line 168) 34400 * variable objects in GDB/MI: GDB/MI Variable Objects. 34401 (line 9) 34402 * variable values, wrong: Variables. (line 58) 34403 * variables, readline: Readline Init File Syntax. 34404 (line 34) 34405 * variables, setting: Assignment. (line 16) 34406 * vAttach packet: Packets. (line 318) 34407 * vCont packet: Packets. (line 338) 34408 * vCont? packet: Packets. (line 380) 34409 * vector unit: Vector Unit. (line 6) 34410 * vector, auxiliary: OS Information. (line 21) 34411 * verbose operation: Messages/Warnings. (line 6) 34412 * verify remote memory image: Memory. (line 115) 34413 * vFile packet: Packets. (line 391) 34414 * vFlashDone packet: Packets. (line 439) 34415 * vFlashErase packet: Packets. (line 395) 34416 * vFlashWrite packet: Packets. (line 417) 34417 * virtual functions (C++) display: Print Settings. (line 364) 34418 * visible-stats: Readline Init File Syntax. 34419 (line 179) 34420 * vKill packet: Packets. (line 447) 34421 * volatile on Type: Types In Python. (line 83) 34422 * vRun packet: Packets. (line 460) 34423 * vStopped packet: Packets. (line 477) 34424 * VTBL display: Print Settings. (line 364) 34425 * VxWorks: VxWorks. (line 6) 34426 * vxworks-timeout: VxWorks. (line 23) 34427 * w (SingleKey TUI key): TUI Single Key Mode. (line 37) 34428 * watch: Set Watchpoints. (line 42) 34429 * watchdog timer: Maintenance Commands. 34430 (line 321) 34431 * watchpoint annotation: Annotations for Running. 34432 (line 50) 34433 * watchpoints: Breakpoints. (line 20) 34434 * watchpoints and threads: Set Watchpoints. (line 147) 34435 * weak alias functions: Calling. (line 58) 34436 * whatis: Symbols. (line 74) 34437 * where: Backtrace. (line 34) 34438 * where to look for shared libraries: Files. (line 369) 34439 * while: Command Files. (line 70) 34440 * while-stepping (tracepoints): Tracepoint Actions. (line 75) 34441 * wild pointer, interpreting: Print Settings. (line 79) 34442 * winheight: TUI Commands. (line 74) 34443 * word completion: Completion. (line 6) 34444 * working directory: Source Path. (line 108) 34445 * working directory (of your program): Working Directory. (line 6) 34446 * working language: Languages. (line 13) 34447 * write: Basic Python. (line 55) 34448 * write data into object, remote request: General Query Packets. 34449 (line 694) 34450 * write, file-i/o system call: write. (line 6) 34451 * writing convenience functions: Functions In Python. (line 6) 34452 * writing into corefiles: Patching. (line 6) 34453 * writing into executables: Patching. (line 6) 34454 * wrong values: Variables. (line 58) 34455 * x (examine memory): Memory. (line 9) 34456 * x command, default address: Machine Code. (line 30) 34457 * X packet: Packets. (line 489) 34458 * x(examine), and info line: Machine Code. (line 30) 34459 * Xilinx MicroBlaze: MicroBlaze. (line 6) 34460 * XInclude: Target Description Format. 34461 (line 54) 34462 * XMD, Xilinx Microprocessor Debugger: MicroBlaze. (line 6) 34463 * XML parser debugging: Debugging Output. (line 176) 34464 * yank (C-y): Commands For Killing. 34465 (line 59) 34466 * yank-last-arg (M-. or M-_): Commands For History. 34467 (line 64) 34468 * yank-nth-arg (M-C-y): Commands For History. 34469 (line 55) 34470 * yank-pop (M-y): Commands For Killing. 34471 (line 62) 34472 * yanking text: Readline Killing Commands. 34473 (line 6) 34474 * z packet: Packets. (line 502) 34475 * Z packets: Packets. (line 502) 34476 * Z0 packet: Packets. (line 517) 34477 * z0 packet: Packets. (line 517) 34478 * z1 packet: Packets. (line 545) 34479 * Z1 packet: Packets. (line 545) 34480 * Z2 packet: Packets. (line 567) 34481 * z2 packet: Packets. (line 567) 34482 * z3 packet: Packets. (line 582) 34483 * Z3 packet: Packets. (line 582) 34484 * z4 packet: Packets. (line 597) 34485 * Z4 packet: Packets. (line 597) 34486 * Z8000: Z8000. (line 6) 34487 * Zilog Z8000 simulator: Z8000. (line 6) 34488 * {TYPE}: Expressions. (line 43) 34489 34490 34491 34492 Tag Table: 34493 Node: Top1971 34494 Node: Summary5110 34495 Node: Free Software6746 34496 Node: Contributors12314 34497 Node: Sample Session20403 34498 Node: Invocation27251 34499 Node: Invoking GDB27795 34500 Node: File Options30108 34501 Node: Mode Options32845 34502 Node: Startup39257 34503 Ref: Startup-Footnote-141479 34504 Node: Quitting GDB41588 34505 Node: Shell Commands42485 34506 Node: Logging Output43327 34507 Node: Commands44173 34508 Node: Command Syntax44811 34509 Node: Completion46977 34510 Ref: Completion-Footnote-152183 34511 Node: Help52343 34512 Node: Running57584 34513 Node: Compilation58813 34514 Node: Starting60790 34515 Node: Arguments69680 34516 Node: Environment70950 34517 Node: Working Directory74218 34518 Node: Input/Output75326 34519 Node: Attach77297 34520 Node: Kill Process79764 34521 Node: Inferiors and Programs80745 34522 Node: Threads87705 34523 Node: Forks95764 34524 Node: Checkpoint/Restart102072 34525 Ref: Checkpoint/Restart-Footnote-1106601 34526 Node: Stopping106636 34527 Node: Breakpoints107795 34528 Node: Set Breaks111165 34529 Ref: Set Breaks-Footnote-1127061 34530 Node: Set Watchpoints127309 34531 Node: Set Catchpoints134963 34532 Node: Delete Breaks144159 34533 Node: Disabling146095 34534 Node: Conditions148960 34535 Node: Break Commands153909 34536 Node: Error in Breakpoints156798 34537 Node: Breakpoint-related Warnings157527 34538 Node: Continuing and Stepping159852 34539 Node: Signals169212 34540 Ref: extra signal information173484 34541 Node: Thread Stops174987 34542 Node: All-Stop Mode176018 34543 Node: Non-Stop Mode179916 34544 Node: Background Execution183393 34545 Node: Thread-Specific Breakpoints185962 34546 Node: Interrupted System Calls187284 34547 Node: Reverse Execution188776 34548 Ref: Reverse Execution-Footnote-1193403 34549 Ref: Reverse Execution-Footnote-2194030 34550 Node: Process Record and Replay194080 34551 Node: Stack200449 34552 Node: Frames201942 34553 Node: Backtrace204694 34554 Ref: Backtrace-Footnote-1209925 34555 Node: Selection210113 34556 Node: Frame Info212977 34557 Node: Source215308 34558 Node: List216374 34559 Node: Specify Location218987 34560 Node: Edit222237 34561 Ref: Edit-Footnote-1223712 34562 Node: Search223947 34563 Node: Source Path224755 34564 Ref: set substitute-path231013 34565 Node: Machine Code233234 34566 Node: Data239266 34567 Node: Expressions241784 34568 Node: Ambiguous Expressions243876 34569 Node: Variables247110 34570 Node: Arrays251613 34571 Node: Output Formats254144 34572 Ref: Output Formats-Footnote-1257215 34573 Node: Memory257372 34574 Node: Auto Display263014 34575 Node: Print Settings266729 34576 Node: Value History280331 34577 Node: Convenience Vars282749 34578 Node: Registers286889 34579 Ref: Registers-Footnote-1291566 34580 Node: Floating Point Hardware291961 34581 Node: Vector Unit292493 34582 Node: OS Information292880 34583 Node: Memory Region Attributes295348 34584 Node: Dump/Restore Files300018 34585 Node: Core File Generation302323 34586 Node: Character Sets303557 34587 Node: Caching Remote Data309924 34588 Ref: Caching Remote Data-Footnote-1311725 34589 Node: Searching Memory311963 34590 Node: Optimized Code314840 34591 Node: Inline Functions316450 34592 Node: Macros319420 34593 Node: Tracepoints326523 34594 Node: Set Tracepoints328584 34595 Node: Create and Delete Tracepoints330336 34596 Node: Enable and Disable Tracepoints332991 34597 Node: Tracepoint Passcounts333775 34598 Node: Tracepoint Conditions335202 34599 Node: Trace State Variables336895 34600 Node: Tracepoint Actions339085 34601 Node: Listing Tracepoints343081 34602 Node: Starting and Stopping Trace Experiments344465 34603 Node: Analyze Collected Data347468 34604 Node: tfind348773 34605 Node: tdump353195 34606 Node: save-tracepoints354854 34607 Node: Tracepoint Variables355273 34608 Node: Trace Files356401 34609 Node: Overlays357859 34610 Node: How Overlays Work358579 34611 Ref: A code overlay361139 34612 Node: Overlay Commands364577 34613 Node: Automatic Overlay Debugging368767 34614 Node: Overlay Sample Program370908 34615 Node: Languages372668 34616 Node: Setting373831 34617 Node: Filenames375533 34618 Node: Manually376319 34619 Node: Automatically377528 34620 Node: Show378589 34621 Node: Checks379911 34622 Node: Type Checking381301 34623 Node: Range Checking384034 34624 Node: Supported Languages386435 34625 Node: C387608 34626 Node: C Operators388909 34627 Node: C Constants393228 34628 Node: C Plus Plus Expressions395632 34629 Node: C Defaults399175 34630 Node: C Checks399858 34631 Node: Debugging C400581 34632 Node: Debugging C Plus Plus401065 34633 Node: Decimal Floating Point404252 34634 Node: Objective-C405511 34635 Node: Method Names in Commands405972 34636 Node: The Print Command with Objective-C407667 34637 Node: Fortran408318 34638 Node: Fortran Operators409043 34639 Node: Fortran Defaults409899 34640 Node: Special Fortran Commands410284 34641 Node: Pascal410790 34642 Node: Modula-2411305 34643 Node: M2 Operators412280 34644 Node: Built-In Func/Proc415279 34645 Node: M2 Constants418140 34646 Node: M2 Types419741 34647 Node: M2 Defaults422960 34648 Node: Deviations423560 34649 Node: M2 Checks424661 34650 Node: M2 Scope425479 34651 Node: GDB/M2426503 34652 Node: Ada427415 34653 Node: Ada Mode Intro428362 34654 Node: Omissions from Ada430272 34655 Node: Additions to Ada434626 34656 Node: Stopping Before Main Program438556 34657 Node: Ada Tasks439085 34658 Node: Ada Tasks and Core Files445498 34659 Node: Ada Glitches446411 34660 Node: Unsupported Languages449478 34661 Node: Symbols450168 34662 Node: Altering463997 34663 Node: Assignment464966 34664 Node: Jumping468071 34665 Node: Signaling470206 34666 Node: Returning471337 34667 Node: Calling474689 34668 Node: Patching477716 34669 Node: GDB Files478793 34670 Node: Files479381 34671 Ref: Shared Libraries492216 34672 Ref: Files-Footnote-1498360 34673 Node: Separate Debug Files498535 34674 Node: Symbol Errors510107 34675 Node: Data Files513729 34676 Node: Targets514568 34677 Node: Active Targets516048 34678 Node: Target Commands517627 34679 Ref: load521886 34680 Node: Byte Order522867 34681 Node: Remote Debugging523844 34682 Node: Connecting525106 34683 Node: File Transfer530046 34684 Node: Server530986 34685 Ref: Monitor Commands for gdbserver538636 34686 Ref: Server-Footnote-1539792 34687 Node: Remote Configuration539912 34688 Ref: set remotebreak540936 34689 Ref: set remote hardware-watchpoint-limit542400 34690 Ref: set remote hardware-breakpoint-limit542400 34691 Ref: set remote exec-file542682 34692 Node: Remote Stub548627 34693 Node: Stub Contents551524 34694 Node: Bootstrapping553635 34695 Node: Debug Session557444 34696 Node: Configurations559004 34697 Node: Native559773 34698 Node: HP-UX560408 34699 Node: BSD libkvm Interface560697 34700 Node: SVR4 Process Information561768 34701 Node: DJGPP Native565198 34702 Node: Cygwin Native571778 34703 Node: Non-debug DLL Symbols575482 34704 Node: Hurd Native580030 34705 Node: Neutrino585293 34706 Node: Darwin585683 34707 Node: Embedded OS586941 34708 Node: VxWorks587417 34709 Node: VxWorks Connection589634 34710 Node: VxWorks Download590568 34711 Node: VxWorks Attach592303 34712 Node: Embedded Processors592701 34713 Node: ARM593880 34714 Node: M32R/D597617 34715 Node: M68K599319 34716 Node: MicroBlaze599612 34717 Node: MIPS Embedded601062 34718 Node: OpenRISC 1000606012 34719 Node: PowerPC Embedded608867 34720 Node: PA610333 34721 Node: Sparclet610622 34722 Node: Sparclet File612106 34723 Node: Sparclet Connection612986 34724 Node: Sparclet Download613464 34725 Node: Sparclet Execution614513 34726 Node: Sparclite615104 34727 Node: Z8000615479 34728 Node: AVR616863 34729 Node: CRIS617226 34730 Node: Super-H618204 34731 Node: Architectures619319 34732 Node: i386619741 34733 Node: A29K620423 34734 Node: Alpha621262 34735 Node: MIPS621395 34736 Node: HPPA624019 34737 Node: SPU624538 34738 Node: PowerPC626726 34739 Node: Controlling GDB627444 34740 Node: Prompt628270 34741 Node: Editing629049 34742 Node: Command History629992 34743 Node: Screen Size633396 34744 Node: Numbers635101 34745 Node: ABI637078 34746 Node: Messages/Warnings640007 34747 Ref: confirmation requests641433 34748 Node: Debugging Output642500 34749 Node: Other Misc Settings648419 34750 Node: Extending GDB649186 34751 Node: Sequences650677 34752 Node: Define651272 34753 Node: Hooks654885 34754 Node: Command Files657252 34755 Node: Output661315 34756 Node: Python666086 34757 Node: Python Commands666511 34758 Node: Python API668186 34759 Node: Basic Python669274 34760 Node: Exception Handling672127 34761 Node: Auto-loading673393 34762 Node: Values From Inferior675310 34763 Node: Types In Python680901 34764 Node: Pretty Printing688179 34765 Node: Selecting Pretty-Printers692359 34766 Node: Commands In Python696105 34767 Node: Functions In Python704526 34768 Node: Objfiles In Python706633 34769 Node: Frames In Python708163 34770 Node: Lazy Strings In Python710755 34771 Node: Interpreters712992 34772 Node: TUI715091 34773 Node: TUI Overview716058 34774 Node: TUI Keys718491 34775 Node: TUI Single Key Mode720795 34776 Node: TUI Commands721670 34777 Node: TUI Configuration723758 34778 Node: Emacs725054 34779 Node: GDB/MI730531 34780 Node: GDB/MI General Design732379 34781 Node: Context management734902 34782 Node: Asynchronous and non-stop modes738037 34783 Node: Thread groups740029 34784 Node: GDB/MI Command Syntax742088 34785 Node: GDB/MI Input Syntax742331 34786 Node: GDB/MI Output Syntax743885 34787 Node: GDB/MI Compatibility with CLI747457 34788 Node: GDB/MI Development and Front Ends748194 34789 Node: GDB/MI Output Records749851 34790 Node: GDB/MI Result Records750186 34791 Node: GDB/MI Stream Records751192 34792 Node: GDB/MI Async Records752457 34793 Node: GDB/MI Frame Information757344 34794 Node: GDB/MI Thread Information758422 34795 Node: GDB/MI Simple Examples759360 34796 Node: GDB/MI Command Description Format761537 34797 Node: GDB/MI Breakpoint Commands762417 34798 Node: GDB/MI Program Context779928 34799 Node: GDB/MI Thread Commands784196 34800 Node: GDB/MI Program Execution787074 34801 Node: GDB/MI Stack Manipulation798513 34802 Node: GDB/MI Variable Objects809207 34803 Ref: -var-set-format818935 34804 Ref: -var-list-children820053 34805 Ref: -var-update828234 34806 Ref: -var-set-frozen830931 34807 Ref: -var-set-update-range831727 34808 Ref: -var-set-visualizer832257 34809 Node: GDB/MI Data Manipulation833750 34810 Node: GDB/MI Tracepoint Commands848130 34811 Node: GDB/MI Symbol Query848374 34812 Node: GDB/MI File Commands849063 34813 Node: GDB/MI Target Manipulation852400 34814 Node: GDB/MI File Transfer Commands858622 34815 Node: GDB/MI Miscellaneous Commands859944 34816 Ref: -interpreter-exec868281 34817 Node: Annotations870594 34818 Node: Annotations Overview871513 34819 Node: Server Prefix873976 34820 Node: Prompting874710 34821 Node: Errors876227 34822 Node: Invalidation877123 34823 Node: Annotations for Running877600 34824 Node: Source Annotations879120 34825 Node: JIT Interface880045 34826 Node: Declarations881763 34827 Node: Registering Code883150 34828 Node: Unregistering Code884122 34829 Node: GDB Bugs884723 34830 Node: Bug Criteria885452 34831 Node: Bug Reporting886329 34832 Node: Command Line Editing893952 34833 Node: Introduction and Notation894604 34834 Node: Readline Interaction896224 34835 Node: Readline Bare Essentials897413 34836 Node: Readline Movement Commands899200 34837 Node: Readline Killing Commands900163 34838 Node: Readline Arguments902081 34839 Node: Searching903123 34840 Node: Readline Init File905272 34841 Node: Readline Init File Syntax906335 34842 Node: Conditional Init Constructs918267 34843 Node: Sample Init File920798 34844 Node: Bindable Readline Commands923913 34845 Node: Commands For Moving924968 34846 Node: Commands For History925827 34847 Node: Commands For Text928949 34848 Node: Commands For Killing931673 34849 Node: Numeric Arguments933813 34850 Node: Commands For Completion934950 34851 Node: Keyboard Macros936492 34852 Node: Miscellaneous Commands937061 34853 Node: Readline vi Mode940420 34854 Node: Using History Interactively941337 34855 Node: History Interaction941852 34856 Node: Event Designators943274 34857 Node: Word Designators944207 34858 Node: Modifiers945844 34859 Node: Formatting Documentation947069 34860 Ref: Formatting Documentation-Footnote-1950446 34861 Node: Installing GDB950534 34862 Node: Requirements951106 34863 Ref: Expat951675 34864 Node: Running Configure953810 34865 Node: Separate Objdir957529 34866 Node: Config Names960485 34867 Node: Configure Options961954 34868 Node: System-wide configuration964324 34869 Node: Maintenance Commands965619 34870 Ref: maint info breakpoints966803 34871 Node: Remote Protocol979359 34872 Node: Overview979921 34873 Ref: Binary Data982483 34874 Node: Packets984742 34875 Ref: thread-id syntax985642 34876 Ref: extended mode987087 34877 Ref: bc988808 34878 Ref: bs989018 34879 Ref: read registers packet990444 34880 Ref: cycle step packet991608 34881 Ref: write register packet993484 34882 Ref: step with signal packet994391 34883 Ref: vStopped packet1000672 34884 Ref: X packet1001015 34885 Ref: insert breakpoint or watchpoint packet1001301 34886 Node: Stop Reply Packets1004063 34887 Node: General Query Packets1008803 34888 Ref: QNonStop1016608 34889 Ref: QPassSignals1017232 34890 Ref: qSearch memory1019309 34891 Ref: QStartNoAckMode1019807 34892 Ref: qSupported1020337 34893 Ref: multiprocess extensions1028332 34894 Ref: qXfer read1031810 34895 Ref: qXfer auxiliary vector read1032304 34896 Ref: qXfer target description read1032653 34897 Ref: qXfer library list read1033097 34898 Ref: qXfer memory map read1033743 34899 Ref: qXfer siginfo read1034131 34900 Ref: qXfer spu read1034527 34901 Ref: qXfer threads read1035050 34902 Ref: qXfer osdata read1035443 34903 Ref: qXfer write1036645 34904 Ref: qXfer siginfo write1037202 34905 Ref: qXfer spu write1037598 34906 Ref: General Query Packets-Footnote-11039685 34907 Node: Architecture-Specific Protocol Details1040012 34908 Node: Tracepoint Packets1041525 34909 Node: Host I/O Packets1050853 34910 Node: Interrupts1054995 34911 Node: Notification Packets1056898 34912 Node: Remote Non-Stop1059169 34913 Node: Packet Acknowledgment1063428 34914 Node: Examples1065543 34915 Node: File-I/O Remote Protocol Extension1066169 34916 Node: File-I/O Overview1066631 34917 Node: Protocol Basics1068828 34918 Node: The F Request Packet1071060 34919 Node: The F Reply Packet1071961 34920 Node: The Ctrl-C Message1072879 34921 Node: Console I/O1074508 34922 Node: List of Supported Calls1075725 34923 Node: open1076087 34924 Node: close1078581 34925 Node: read1078963 34926 Node: write1079570 34927 Node: lseek1080337 34928 Node: rename1081215 34929 Node: unlink1082611 34930 Node: stat/fstat1083550 34931 Node: gettimeofday1084437 34932 Node: isatty1084872 34933 Node: system1085468 34934 Node: Protocol-specific Representation of Datatypes1087010 34935 Node: Integral Datatypes1087387 34936 Node: Pointer Values1088194 34937 Node: Memory Transfer1088902 34938 Node: struct stat1089522 34939 Node: struct timeval1091724 34940 Node: Constants1092241 34941 Node: Open Flags1092690 34942 Node: mode_t Values1093031 34943 Node: Errno Values1093523 34944 Node: Lseek Flags1094334 34945 Node: Limits1094519 34946 Node: File-I/O Examples1094879 34947 Node: Library List Format1095995 34948 Node: Memory Map Format1098759 34949 Node: Thread List Format1101319 34950 Node: Agent Expressions1102106 34951 Node: General Bytecode Design1104927 34952 Node: Bytecode Descriptions1109727 34953 Node: Using Agent Expressions1121438 34954 Node: Varying Target Capabilities1123416 34955 Node: Rationale1124578 34956 Node: Trace File Format1131964 34957 Node: Target Descriptions1133945 34958 Node: Retrieving Descriptions1136005 34959 Node: Target Description Format1137090 34960 Node: Predefined Target Types1144919 34961 Node: Standard Target Features1146304 34962 Node: ARM Features1148075 34963 Node: i386 Features1149351 34964 Node: MIPS Features1150218 34965 Node: M68K Features1151163 34966 Node: PowerPC Features1151826 34967 Node: Operating System Information1153110 34968 Node: Process list1153948 34969 Node: Copying1155010 34970 Node: GNU Free Documentation License1192597 34971 Node: Index1215032 34972 34973 End Tag Table 34974
