1This is gdb.info, produced by makeinfo version 4.13 from 2/scratch/jwlemke/2011.09-arm-eabi-lite/obj/gdb-src-2011.09-69-arm-none-eabi-i686-pc-linux-gnu/gdb/doc/gdb.texinfo. 3 4INFO-DIR-SECTION Software development 5START-INFO-DIR-ENTRY 6* Gdb: (gdb). The GNU debugger. 7END-INFO-DIR-ENTRY 8 9 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 101998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 112010 Free Software Foundation, Inc. 12 13 Permission is granted to copy, distribute and/or modify this document 14under the terms of the GNU Free Documentation License, Version 1.3 or 15any later version published by the Free Software Foundation; with the 16Invariant Sections being "Free Software" and "Free Software Needs Free 17Documentation", with the Front-Cover Texts being "A GNU Manual," and 18with 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 21this GNU Manual. Buying copies from GNU Press supports the FSF in 22developing 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 27Source-Level Debugger' for GDB (Sourcery CodeBench Lite 2011.09-69) 28Version 7.2.50.20100908-cvs. 29 30 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 311998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 322010 Free Software Foundation, Inc. 33 34 Permission is granted to copy, distribute and/or modify this document 35under the terms of the GNU Free Documentation License, Version 1.3 or 36any later version published by the Free Software Foundation; with the 37Invariant Sections being "Free Software" and "Free Software Needs Free 38Documentation", with the Front-Cover Texts being "A GNU Manual," and 39with the Back-Cover Texts as in (a) below. 40 41 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 42this GNU Manual. Buying copies from GNU Press supports the FSF in 43developing GNU and promoting software freedom." 44 45 46File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) 47 48Debugging with GDB 49****************** 50 51This file describes GDB, the GNU symbolic debugger. 52 53 This is the Ninth Edition, for GDB (Sourcery CodeBench Lite 542011.09-69) Version 7.2.50.20100908-cvs. 55 56 Copyright (C) 1988-2010 Free Software Foundation, Inc. 57 58 This edition of the GDB manual is dedicated to the memory of Fred 59Fish. Fred was a long-standing contributor to GDB and to Free software 60in general. We will miss him. 61 62* Menu: 63 64* Summary:: Summary of GDB 65* Sample Session:: A sample GDB session 66 67* Invocation:: Getting in and out of GDB 68* Commands:: GDB commands 69* Running:: Running programs under GDB 70* Stopping:: Stopping and continuing 71* Reverse Execution:: Running programs backward 72* Process Record and Replay:: Recording inferior's execution and replaying it 73* Stack:: Examining the stack 74* Source:: Examining source files 75* Data:: Examining data 76* Optimized Code:: Debugging optimized code 77* Macros:: Preprocessor Macros 78* Tracepoints:: Debugging remote targets non-intrusively 79* Overlays:: Debugging programs that use overlays 80 81* Languages:: Using GDB with different languages 82 83* Symbols:: Examining the symbol table 84* Altering:: Altering execution 85* GDB Files:: GDB files 86* Targets:: Specifying a debugging target 87* Remote Debugging:: Debugging remote programs 88* Configurations:: Configuration-specific information 89* Controlling GDB:: Controlling GDB 90* Extending GDB:: Extending GDB 91* Interpreters:: Command Interpreters 92* TUI:: GDB Text User Interface 93* Emacs:: Using GDB under GNU Emacs 94* GDB/MI:: GDB's Machine Interface. 95* Annotations:: GDB's annotation interface. 96* JIT Interface:: Using the JIT debugging interface. 97 98* GDB Bugs:: Reporting bugs in GDB 99 100* Command Line Editing:: Command Line Editing 101* Using History Interactively:: Using History Interactively 102* Formatting Documentation:: How to format and print GDB documentation 103* Installing GDB:: Installing GDB 104* Maintenance Commands:: Maintenance Commands 105* Remote Protocol:: GDB Remote Serial Protocol 106* Agent Expressions:: The GDB Agent Expression Mechanism 107* Target Descriptions:: How targets can describe themselves to 108 GDB 109* Operating System Information:: Getting additional information from 110 the operating system 111* Trace File Format:: GDB trace file format 112* Copying:: GNU General Public License says 113 how you can copy and share GDB 114* GNU Free Documentation License:: The license for this documentation 115* GDB Index:: Index 116 117 118File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top 119 120Summary of GDB 121************** 122 123The purpose of a debugger such as GDB is to allow you to see what is 124going on "inside" another program while it executes--or what another 125program was doing at the moment it crashed. 126 127 GDB can do four main kinds of things (plus other things in support of 128these) to help you catch bugs in the act: 129 130 * Start your program, specifying anything that might affect its 131 behavior. 132 133 * Make your program stop on specified conditions. 134 135 * Examine what has happened, when your program has stopped. 136 137 * Change things in your program, so you can experiment with 138 correcting the effects of one bug and go on to learn about another. 139 140 You can use GDB to debug programs written in C and C++. For more 141information, see *note Supported Languages: Supported Languages. For 142more information, see *note C and C++: C. 143 144 Support for D is partial. For information on D, see *note D: D. 145 146 Support for Modula-2 is partial. For information on Modula-2, see 147*note Modula-2: Modula-2. 148 149 Debugging Pascal programs which use sets, subranges, file variables, 150or nested functions does not currently work. GDB does not support 151entering expressions, printing values, or similar features using Pascal 152syntax. 153 154 GDB can be used to debug programs written in Fortran, although it 155may be necessary to refer to some variables with a trailing underscore. 156 157 GDB can be used to debug programs written in Objective-C, using 158either the Apple/NeXT or the GNU Objective-C runtime. 159 160* Menu: 161 162* Free Software:: Freely redistributable software 163* Contributors:: Contributors to GDB 164 165 166File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary 167 168Free Software 169============= 170 171GDB is "free software", protected by the GNU General Public License 172(GPL). The GPL gives you the freedom to copy or adapt a licensed 173program--but every person getting a copy also gets with it the freedom 174to modify that copy (which means that they must get access to the 175source code), and the freedom to distribute further copies. Typical 176software companies use copyrights to limit your freedoms; the Free 177Software Foundation uses the GPL to preserve these freedoms. 178 179 Fundamentally, the General Public License is a license which says 180that you have these freedoms and that you cannot take these freedoms 181away from anyone else. 182 183Free Software Needs Free Documentation 184====================================== 185 186The biggest deficiency in the free software community today is not in 187the software--it is the lack of good free documentation that we can 188include with the free software. Many of our most important programs do 189not come with free reference manuals and free introductory texts. 190Documentation is an essential part of any software package; when an 191important free software package does not come with a free manual and a 192free tutorial, that is a major gap. We have many such gaps today. 193 194 Consider Perl, for instance. The tutorial manuals that people 195normally use are non-free. How did this come about? Because the 196authors of those manuals published them with restrictive terms--no 197copying, no modification, source files not available--which exclude 198them from the free software world. 199 200 That wasn't the first time this sort of thing happened, and it was 201far from the last. Many times we have heard a GNU user eagerly 202describe a manual that he is writing, his intended contribution to the 203community, only to learn that he had ruined everything by signing a 204publication contract to make it non-free. 205 206 Free documentation, like free software, is a matter of freedom, not 207price. The problem with the non-free manual is not that publishers 208charge a price for printed copies--that in itself is fine. (The Free 209Software Foundation sells printed copies of manuals, too.) The problem 210is the restrictions on the use of the manual. Free manuals are 211available in source code form, and give you permission to copy and 212modify. Non-free manuals do not allow this. 213 214 The criteria of freedom for a free manual are roughly the same as for 215free software. Redistribution (including the normal kinds of 216commercial redistribution) must be permitted, so that the manual can 217accompany every copy of the program, both on-line and on paper. 218 219 Permission for modification of the technical content is crucial too. 220When people modify the software, adding or changing features, if they 221are conscientious they will change the manual too--so they can provide 222accurate and clear documentation for the modified program. A manual 223that leaves you no choice but to write a new manual to document a 224changed version of the program is not really available to our community. 225 226 Some kinds of limits on the way modification is handled are 227acceptable. For example, requirements to preserve the original 228author's copyright notice, the distribution terms, or the list of 229authors, are ok. It is also no problem to require modified versions to 230include notice that they were modified. Even entire sections that may 231not be deleted or changed are acceptable, as long as they deal with 232nontechnical topics (like this one). These kinds of restrictions are 233acceptable because they don't obstruct the community's normal use of 234the manual. 235 236 However, it must be possible to modify all the _technical_ content 237of the manual, and then distribute the result in all the usual media, 238through all the usual channels. Otherwise, the restrictions obstruct 239the use of the manual, it is not free, and we need another manual to 240replace it. 241 242 Please spread the word about this issue. Our community continues to 243lose manuals to proprietary publishing. If we spread the word that 244free software needs free reference manuals and free tutorials, perhaps 245the next person who wants to contribute by writing documentation will 246realize, before it is too late, that only free manuals contribute to 247the free software community. 248 249 If you are writing documentation, please insist on publishing it 250under the GNU Free Documentation License or another free documentation 251license. Remember that this decision requires your approval--you don't 252have to let the publisher decide. Some commercial publishers will use 253a free license if you insist, but they will not propose the option; it 254is up to you to raise the issue and say firmly that this is what you 255want. If the publisher you are dealing with refuses, please try other 256publishers. If you're not sure whether a proposed license is free, 257write to <licensing@gnu.org>. 258 259 You can encourage commercial publishers to sell more free, copylefted 260manuals and tutorials by buying them, and particularly by buying copies 261from the publishers that paid for their writing or for major 262improvements. Meanwhile, try to avoid buying non-free documentation at 263all. Check the distribution terms of a manual before you buy it, and 264insist that whoever seeks your business must respect your freedom. 265Check the history of the book, and try to reward the publishers that 266have paid or pay the authors to work on it. 267 268 The Free Software Foundation maintains a list of free documentation 269published by other publishers, at 270`http://www.fsf.org/doc/other-free-books.html'. 271 272 273File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary 274 275Contributors to GDB 276=================== 277 278Richard Stallman was the original author of GDB, and of many other GNU 279programs. Many others have contributed to its development. This 280section attempts to credit major contributors. One of the virtues of 281free software is that everyone is free to contribute to it; with 282regret, we cannot actually acknowledge everyone here. The file 283`ChangeLog' in the GDB distribution approximates a blow-by-blow account. 284 285 Changes much prior to version 2.0 are lost in the mists of time. 286 287 _Plea:_ Additions to this section are particularly welcome. If you 288 or your friends (or enemies, to be evenhanded) have been unfairly 289 omitted from this list, we would like to add your names! 290 291 So that they may not regard their many labors as thankless, we 292particularly thank those who shepherded GDB through major releases: 293Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim 294Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs 295(release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, 296and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, 297and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim 298Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 2993.1, and 3.0). 300 301 Richard Stallman, assisted at various times by Peter TerMaat, Chris 302Hanson, and Richard Mlynarik, handled releases through 2.8. 303 304 Michael Tiemann is the author of most of the GNU C++ support in GDB, 305with significant additional contributions from Per Bothner and Daniel 306Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ 307was by Peter TerMaat (who also did much general update work leading to 308release 3.0). 309 310 GDB uses the BFD subroutine library to examine multiple object-file 311formats; BFD was a joint project of David V. Henkel-Wallace, Rich 312Pixley, Steve Chamberlain, and John Gilmore. 313 314 David Johnson wrote the original COFF support; Pace Willison did the 315original support for encapsulated COFF. 316 317 Brent Benson of Harris Computer Systems contributed DWARF 2 support. 318 319 Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 320Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 321support. Jean-Daniel Fekete contributed Sun 386i support. Chris 322Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki 323Hasei contributed Sony/News OS 3 support. David Johnson contributed 324Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. 325Jeff Law contributed HP PA and SOM support. Keith Packard contributed 326NS32K support. Doug Rabson contributed Acorn Risc Machine support. 327Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith 328contributed Convex support (and Fortran debugging). Jonathan Stone 329contributed Pyramid support. Michael Tiemann contributed SPARC support. 330Tim Tucker contributed support for the Gould NP1 and Gould Powernode. 331Pace Willison contributed Intel 386 support. Jay Vosburgh contributed 332Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. 333 334 Andreas Schwab contributed M68K GNU/Linux support. 335 336 Rich Schaefer and Peter Schauer helped with support of SunOS shared 337libraries. 338 339 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about 340several machine instruction sets. 341 342 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped 343develop remote debugging. Intel Corporation, Wind River Systems, AMD, 344and ARM contributed remote debugging modules for the i960, VxWorks, 345A29K UDI, and RDI targets, respectively. 346 347 Brian Fox is the author of the readline libraries providing 348command-line editing and command history. 349 350 Andrew Beers of SUNY Buffalo wrote the language-switching code, the 351Modula-2 support, and contributed the Languages chapter of this manual. 352 353 Fred Fish wrote most of the support for Unix System Vr4. He also 354enhanced the command-completion support to cover C++ overloaded symbols. 355 356 Hitachi America (now Renesas America), Ltd. sponsored the support for 357H8/300, H8/500, and Super-H processors. 358 359 NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx 360processors. 361 362 Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and 363M32R/D processors. 364 365 Toshiba sponsored the support for the TX39 Mips processor. 366 367 Matsushita sponsored the support for the MN10200 and MN10300 368processors. 369 370 Fujitsu sponsored the support for SPARClite and FR30 processors. 371 372 Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 373watchpoints. 374 375 Michael Snyder added support for tracepoints. 376 377 Stu Grossman wrote gdbserver. 378 379 Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly 380innumerable bug fixes and cleanups throughout GDB. 381 382 The following people at the Hewlett-Packard Company contributed 383support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 384(narrow mode), HP's implementation of kernel threads, HP's aC++ 385compiler, and the Text User Interface (nee Terminal User Interface): 386Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, 387Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase 388provided HP-specific information in this manual. 389 390 DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert 391Hoehne made significant contributions to the DJGPP port. 392 393 Cygnus Solutions has sponsored GDB maintenance and much of its 394development since 1991. Cygnus engineers who have worked on GDB 395fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 396Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 397Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 398Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 399Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 400addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 401JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 402Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 403Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 404Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 405Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 406Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 407Zuhn have made contributions both large and small. 408 409 Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for 410Cygnus Solutions, implemented the original GDB/MI interface. 411 412 Jim Blandy added support for preprocessor macros, while working for 413Red Hat. 414 415 Andrew Cagney designed GDB's architecture vector. Many people 416including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, 417Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, 418Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna 419Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration 420of old architectures to this new framework. 421 422 Andrew Cagney completely re-designed and re-implemented GDB's 423unwinder framework, this consisting of a fresh new design featuring 424frame IDs, independent frame sniffers, and the sentinel frame. Mark 425Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind 426unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad 427unwinders. The architecture-specific changes, each involving a 428complete rewrite of the architecture's frame code, were carried out by 429Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane 430Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel 431Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei 432Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich 433Weigand. 434 435 Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from 436Tensilica, Inc. contributed support for Xtensa processors. Others who 437have worked on the Xtensa port of GDB in the past include Steve Tjiang, 438John Newlin, and Scott Foehner. 439 440 Michael Eager and staff of Xilinx, Inc., contributed support for the 441Xilinx MicroBlaze architecture. 442 443 444File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top 445 4461 A Sample GDB Session 447********************** 448 449You can use this manual at your leisure to read all about GDB. 450However, a handful of commands are enough to get started using the 451debugger. This chapter illustrates those commands. 452 453 One of the preliminary versions of GNU `m4' (a generic macro 454processor) exhibits the following bug: sometimes, when we change its 455quote strings from the default, the commands used to capture one macro 456definition within another stop working. In the following short `m4' 457session, we define a macro `foo' which expands to `0000'; we then use 458the `m4' built-in `defn' to define `bar' as the same thing. However, 459when we change the open quote string to `<QUOTE>' and the close quote 460string to `<UNQUOTE>', the same procedure fails to define a new synonym 461`baz': 462 463 $ cd gnu/m4 464 $ ./m4 465 define(foo,0000) 466 467 foo 468 0000 469 define(bar,defn(`foo')) 470 471 bar 472 0000 473 changequote(<QUOTE>,<UNQUOTE>) 474 475 define(baz,defn(<QUOTE>foo<UNQUOTE>)) 476 baz 477 Ctrl-d 478 m4: End of input: 0: fatal error: EOF in string 479 480Let us use GDB to try to see what is going on. 481 482 $ gdb m4 483 GDB is free software and you are welcome to distribute copies 484 of it under certain conditions; type "show copying" to see 485 the conditions. 486 There is absolutely no warranty for GDB; type "show warranty" 487 for details. 488 489 GDB 7.2.50.20100908-cvs, Copyright 1999 Free Software Foundation, Inc... 490 (gdb) 491 492GDB reads only enough symbol data to know where to find the rest when 493needed; as a result, the first prompt comes up very quickly. We now 494tell GDB to use a narrower display width than usual, so that examples 495fit in this manual. 496 497 (gdb) set width 70 498 499We need to see how the `m4' built-in `changequote' works. Having 500looked at the source, we know the relevant subroutine is 501`m4_changequote', so we set a breakpoint there with the GDB `break' 502command. 503 504 (gdb) break m4_changequote 505 Breakpoint 1 at 0x62f4: file builtin.c, line 879. 506 507Using the `run' command, we start `m4' running under GDB control; as 508long as control does not reach the `m4_changequote' subroutine, the 509program runs as usual: 510 511 (gdb) run 512 Starting program: /work/Editorial/gdb/gnu/m4/m4 513 define(foo,0000) 514 515 foo 516 0000 517 518To trigger the breakpoint, we call `changequote'. GDB suspends 519execution of `m4', displaying information about the context where it 520stops. 521 522 changequote(<QUOTE>,<UNQUOTE>) 523 524 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) 525 at builtin.c:879 526 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 527 528Now we use the command `n' (`next') to advance execution to the next 529line of the current function. 530 531 (gdb) n 532 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ 533 : nil, 534 535`set_quotes' looks like a promising subroutine. We can go into it by 536using the command `s' (`step') instead of `next'. `step' goes to the 537next line to be executed in _any_ subroutine, so it steps into 538`set_quotes'. 539 540 (gdb) s 541 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 542 at input.c:530 543 530 if (lquote != def_lquote) 544 545The display that shows the subroutine where `m4' is now suspended (and 546its arguments) is called a stack frame display. It shows a summary of 547the stack. We can use the `backtrace' command (which can also be 548spelled `bt'), to see where we are in the stack as a whole: the 549`backtrace' command displays a stack frame for each active subroutine. 550 551 (gdb) bt 552 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 553 at input.c:530 554 #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) 555 at builtin.c:882 556 #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 557 #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 558 at macro.c:71 559 #4 0x79dc in expand_input () at macro.c:40 560 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 561 562We step through a few more lines to see what happens. The first two 563times, we can use `s'; the next two times we use `n' to avoid falling 564into the `xstrdup' subroutine. 565 566 (gdb) s 567 0x3b5c 532 if (rquote != def_rquote) 568 (gdb) s 569 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ 570 def_lquote : xstrdup(lq); 571 (gdb) n 572 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 573 : xstrdup(rq); 574 (gdb) n 575 538 len_lquote = strlen(rquote); 576 577The last line displayed looks a little odd; we can examine the variables 578`lquote' and `rquote' to see if they are in fact the new left and right 579quotes we specified. We use the command `p' (`print') to see their 580values. 581 582 (gdb) p lquote 583 $1 = 0x35d40 "<QUOTE>" 584 (gdb) p rquote 585 $2 = 0x35d50 "<UNQUOTE>" 586 587`lquote' and `rquote' are indeed the new left and right quotes. To 588look at some context, we can display ten lines of source surrounding 589the current line with the `l' (`list') command. 590 591 (gdb) l 592 533 xfree(rquote); 593 534 594 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ 595 : xstrdup (lq); 596 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ 597 : xstrdup (rq); 598 537 599 538 len_lquote = strlen(rquote); 600 539 len_rquote = strlen(lquote); 601 540 } 602 541 603 542 void 604 605Let us step past the two lines that set `len_lquote' and `len_rquote', 606and then examine the values of those variables. 607 608 (gdb) n 609 539 len_rquote = strlen(lquote); 610 (gdb) n 611 540 } 612 (gdb) p len_lquote 613 $3 = 9 614 (gdb) p len_rquote 615 $4 = 7 616 617That certainly looks wrong, assuming `len_lquote' and `len_rquote' are 618meant to be the lengths of `lquote' and `rquote' respectively. We can 619set them to better values using the `p' command, since it can print the 620value of any expression--and that expression can include subroutine 621calls and assignments. 622 623 (gdb) p len_lquote=strlen(lquote) 624 $5 = 7 625 (gdb) p len_rquote=strlen(rquote) 626 $6 = 9 627 628Is that enough to fix the problem of using the new quotes with the `m4' 629built-in `defn'? We can allow `m4' to continue executing with the `c' 630(`continue') command, and then try the example that caused trouble 631initially: 632 633 (gdb) c 634 Continuing. 635 636 define(baz,defn(<QUOTE>foo<UNQUOTE>)) 637 638 baz 639 0000 640 641Success! The new quotes now work just as well as the default ones. The 642problem seems to have been just the two typos defining the wrong 643lengths. We allow `m4' exit by giving it an EOF as input: 644 645 Ctrl-d 646 Program exited normally. 647 648The message `Program exited normally.' is from GDB; it indicates `m4' 649has finished executing. We can end our GDB session with the GDB `quit' 650command. 651 652 (gdb) quit 653 654 655File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top 656 6572 Getting In and Out of GDB 658*************************** 659 660This chapter discusses how to start GDB, and how to get out of it. The 661essentials are: 662 * type `gdb' to start GDB. 663 664 * type `quit' or `Ctrl-d' to exit. 665 666* Menu: 667 668* Invoking GDB:: How to start GDB 669* Quitting GDB:: How to quit GDB 670* Shell Commands:: How to use shell commands inside GDB 671* Logging Output:: How to log GDB's output to a file 672 673 674File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation 675 6762.1 Invoking GDB 677================ 678 679Invoke GDB by running the program `gdb'. Once started, GDB reads 680commands from the terminal until you tell it to exit. 681 682 You can also run `gdb' with a variety of arguments and options, to 683specify more of your debugging environment at the outset. 684 685 The command-line options described here are designed to cover a 686variety of situations; in some environments, some of these options may 687effectively be unavailable. 688 689 The most usual way to start GDB is with one argument, specifying an 690executable program: 691 692 gdb PROGRAM 693 694You can also start with both an executable program and a core file 695specified: 696 697 gdb PROGRAM CORE 698 699 You can, instead, specify a process ID as a second argument, if you 700want to debug a running process: 701 702 gdb PROGRAM 1234 703 704would attach GDB to process `1234' (unless you also have a file named 705`1234'; GDB does check for a core file first). 706 707 Taking advantage of the second command-line argument requires a 708fairly complete operating system; when you use GDB as a remote debugger 709attached to a bare board, there may not be any notion of "process", and 710there is often no way to get a core dump. GDB will warn you if it is 711unable to attach or to read core dumps. 712 713 You can optionally have `gdb' pass any arguments after the 714executable file to the inferior using `--args'. This option stops 715option processing. 716 gdb --args gcc -O2 -c foo.c 717 This will cause `gdb' to debug `gcc', and to set `gcc''s 718command-line arguments (*note Arguments::) to `-O2 -c foo.c'. 719 720 You can run `gdb' without printing the front material, which 721describes GDB's non-warranty, by specifying `-silent': 722 723 gdb -silent 724 725You can further control how GDB starts up by using command-line 726options. GDB itself can remind you of the options available. 727 728Type 729 730 gdb -help 731 732to display all available options and briefly describe their use (`gdb 733-h' is a shorter equivalent). 734 735 All options and command line arguments you give are processed in 736sequential order. The order makes a difference when the `-x' option is 737used. 738 739* Menu: 740 741* File Options:: Choosing files 742* Mode Options:: Choosing modes 743* Startup:: What GDB does during startup 744 745 746File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB 747 7482.1.1 Choosing Files 749-------------------- 750 751When GDB starts, it reads any arguments other than options as 752specifying an executable file and core file (or process ID). This is 753the same as if the arguments were specified by the `-se' and `-c' (or 754`-p') options respectively. (GDB reads the first argument that does 755not have an associated option flag as equivalent to the `-se' option 756followed by that argument; and the second argument that does not have 757an associated option flag, if any, as equivalent to the `-c'/`-p' 758option followed by that argument.) If the second argument begins with 759a decimal digit, GDB will first attempt to attach to it as a process, 760and if that fails, attempt to open it as a corefile. If you have a 761corefile whose name begins with a digit, you can prevent GDB from 762treating it as a pid by prefixing it with `./', e.g. `./12345'. 763 764 If GDB has not been configured to included core file support, such 765as for most embedded targets, then it will complain about a second 766argument and ignore it. 767 768 Many options have both long and short forms; both are shown in the 769following list. GDB also recognizes the long forms if you truncate 770them, so long as enough of the option is present to be unambiguous. 771(If you prefer, you can flag option arguments with `--' rather than 772`-', though we illustrate the more usual convention.) 773 774`-symbols FILE' 775`-s FILE' 776 Read symbol table from file FILE. 777 778`-exec FILE' 779`-e FILE' 780 Use file FILE as the executable file to execute when appropriate, 781 and for examining pure data in conjunction with a core dump. 782 783`-se FILE' 784 Read symbol table from file FILE and use it as the executable file. 785 786`-core FILE' 787`-c FILE' 788 Use file FILE as a core dump to examine. 789 790`-pid NUMBER' 791`-p NUMBER' 792 Connect to process ID NUMBER, as with the `attach' command. 793 794`-command FILE' 795`-x FILE' 796 Execute commands from file FILE. The contents of this file is 797 evaluated exactly as the `source' command would. *Note Command 798 files: Command Files. 799 800`-eval-command COMMAND' 801`-ex COMMAND' 802 Execute a single GDB command. 803 804 This option may be used multiple times to call multiple commands. 805 It may also be interleaved with `-command' as required. 806 807 gdb -ex 'target sim' -ex 'load' \ 808 -x setbreakpoints -ex 'run' a.out 809 810`-directory DIRECTORY' 811`-d DIRECTORY' 812 Add DIRECTORY to the path to search for source and script files. 813 814`-r' 815`-readnow' 816 Read each symbol file's entire symbol table immediately, rather 817 than the default, which is to read it incrementally as it is 818 needed. This makes startup slower, but makes future operations 819 faster. 820 821 822 823File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB 824 8252.1.2 Choosing Modes 826-------------------- 827 828You can run GDB in various alternative modes--for example, in batch 829mode or quiet mode. 830 831`-nx' 832`-n' 833 Do not execute commands found in any initialization files. 834 Normally, GDB executes the commands in these files after all the 835 command options and arguments have been processed. *Note Command 836 Files: Command Files. 837 838`-quiet' 839`-silent' 840`-q' 841 "Quiet". Do not print the introductory and copyright messages. 842 These messages are also suppressed in batch mode. 843 844`-batch' 845 Run in batch mode. Exit with status `0' after processing all the 846 command files specified with `-x' (and all commands from 847 initialization files, if not inhibited with `-n'). Exit with 848 nonzero status if an error occurs in executing the GDB commands in 849 the command files. Batch mode also disables pagination, sets 850 unlimited terminal width and height *note Screen Size::, and acts 851 as if `set confirm off' were in effect (*note Messages/Warnings::). 852 853 Batch mode may be useful for running GDB as a filter, for example 854 to download and run a program on another computer; in order to 855 make this more useful, the message 856 857 Program exited normally. 858 859 (which is ordinarily issued whenever a program running under GDB 860 control terminates) is not issued when running in batch mode. 861 862`-batch-silent' 863 Run in batch mode exactly like `-batch', but totally silently. All 864 GDB output to `stdout' is prevented (`stderr' is unaffected). 865 This is much quieter than `-silent' and would be useless for an 866 interactive session. 867 868 This is particularly useful when using targets that give `Loading 869 section' messages, for example. 870 871 Note that targets that give their output via GDB, as opposed to 872 writing directly to `stdout', will also be made silent. 873 874`-return-child-result' 875 The return code from GDB will be the return code from the child 876 process (the process being debugged), with the following 877 exceptions: 878 879 * GDB exits abnormally. E.g., due to an incorrect argument or 880 an internal error. In this case the exit code is the same as 881 it would have been without `-return-child-result'. 882 883 * The user quits with an explicit value. E.g., `quit 1'. 884 885 * The child process never runs, or is not allowed to terminate, 886 in which case the exit code will be -1. 887 888 This option is useful in conjunction with `-batch' or 889 `-batch-silent', when GDB is being used as a remote program loader 890 or simulator interface. 891 892`-nowindows' 893`-nw' 894 "No windows". If GDB comes with a graphical user interface (GUI) 895 built in, then this option tells GDB to only use the command-line 896 interface. If no GUI is available, this option has no effect. 897 898`-windows' 899`-w' 900 If GDB includes a GUI, then this option requires it to be used if 901 possible. 902 903`-cd DIRECTORY' 904 Run GDB using DIRECTORY as its working directory, instead of the 905 current directory. 906 907`-fullname' 908`-f' 909 GNU Emacs sets this option when it runs GDB as a subprocess. It 910 tells GDB to output the full file name and line number in a 911 standard, recognizable fashion each time a stack frame is 912 displayed (which includes each time your program stops). This 913 recognizable format looks like two `\032' characters, followed by 914 the file name, line number and character position separated by 915 colons, and a newline. The Emacs-to-GDB interface program uses 916 the two `\032' characters as a signal to display the source code 917 for the frame. 918 919`-epoch' 920 The Epoch Emacs-GDB interface sets this option when it runs GDB as 921 a subprocess. It tells GDB to modify its print routines so as to 922 allow Epoch to display values of expressions in a separate window. 923 924`-annotate LEVEL' 925 This option sets the "annotation level" inside GDB. Its effect is 926 identical to using `set annotate LEVEL' (*note Annotations::). 927 The annotation LEVEL controls how much information GDB prints 928 together with its prompt, values of expressions, source lines, and 929 other types of output. Level 0 is the normal, level 1 is for use 930 when GDB is run as a subprocess of GNU Emacs, level 3 is the 931 maximum annotation suitable for programs that control GDB, and 932 level 2 has been deprecated. 933 934 The annotation mechanism has largely been superseded by GDB/MI 935 (*note GDB/MI::). 936 937`--args' 938 Change interpretation of command line so that arguments following 939 the executable file are passed as command line arguments to the 940 inferior. This option stops option processing. 941 942`-baud BPS' 943`-b BPS' 944 Set the line speed (baud rate or bits per second) of any serial 945 interface used by GDB for remote debugging. 946 947`-l TIMEOUT' 948 Set the timeout (in seconds) of any communication used by GDB for 949 remote debugging. 950 951`-tty DEVICE' 952`-t DEVICE' 953 Run using DEVICE for your program's standard input and output. 954 955`-tui' 956 Activate the "Text User Interface" when starting. The Text User 957 Interface manages several text windows on the terminal, showing 958 source, assembly, registers and GDB command outputs (*note GDB 959 Text User Interface: TUI.). Alternatively, the Text User 960 Interface can be enabled by invoking the program `gdbtui'. Do not 961 use this option if you run GDB from Emacs (*note Using GDB under 962 GNU Emacs: Emacs.). 963 964`-interpreter INTERP' 965 Use the interpreter INTERP for interface with the controlling 966 program or device. This option is meant to be set by programs 967 which communicate with GDB using it as a back end. *Note Command 968 Interpreters: Interpreters. 969 970 `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the 971 "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included 972 since GDB version 6.0. The previous GDB/MI interface, included in 973 GDB version 5.3 and selected with `--interpreter=mi1', is 974 deprecated. Earlier GDB/MI interfaces are no longer supported. 975 976`-write' 977 Open the executable and core files for both reading and writing. 978 This is equivalent to the `set write on' command inside GDB (*note 979 Patching::). 980 981`-statistics' 982 This option causes GDB to print statistics about time and memory 983 usage after it completes each command and returns to the prompt. 984 985`-version' 986 This option causes GDB to print its version number and no-warranty 987 blurb, and exit. 988 989 990 991File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB 992 9932.1.3 What GDB Does During Startup 994---------------------------------- 995 996Here's the description of what GDB does during session startup: 997 998 1. Sets up the command interpreter as specified by the command line 999 (*note interpreter: Mode Options.). 1000 1001 2. Reads the system-wide "init file" (if `--with-system-gdbinit' was 1002 used when building GDB; *note System-wide configuration and 1003 settings: System-wide configuration.) and executes all the 1004 commands in that file. 1005 1006 3. Reads the init file (if any) in your home directory(1) and 1007 executes all the commands in that file. 1008 1009 4. Processes command line options and operands. 1010 1011 5. Reads and executes the commands from init file (if any) in the 1012 current working directory. This is only done if the current 1013 directory is different from your home directory. Thus, you can 1014 have more than one init file, one generic in your home directory, 1015 and another, specific to the program you are debugging, in the 1016 directory where you invoke GDB. 1017 1018 6. Reads command files specified by the `-x' option. *Note Command 1019 Files::, for more details about GDB command files. 1020 1021 7. Reads the command history recorded in the "history file". *Note 1022 Command History::, for more details about the command history and 1023 the files where GDB records it. 1024 1025 Init files use the same syntax as "command files" (*note Command 1026Files::) and are processed by GDB in the same way. The init file in 1027your home directory can set options (such as `set complaints') that 1028affect subsequent processing of command line options and operands. 1029Init files are not executed if you use the `-nx' option (*note Choosing 1030Modes: Mode Options.). 1031 1032 To display the list of init files loaded by gdb at startup, you can 1033use `gdb --help'. 1034 1035 The GDB init files are normally called `.gdbinit'. The DJGPP port 1036of GDB uses the name `gdb.ini', due to the limitations of file names 1037imposed by DOS filesystems. The Windows ports of GDB use the standard 1038name, but if they find a `gdb.ini' file, they warn you about that and 1039suggest to rename the file to the standard name. 1040 1041 ---------- Footnotes ---------- 1042 1043 (1) On DOS/Windows systems, the home directory is the one pointed to 1044by the `HOME' environment variable. 1045 1046 1047File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation 1048 10492.2 Quitting GDB 1050================ 1051 1052`quit [EXPRESSION]' 1053`q' 1054 To exit GDB, use the `quit' command (abbreviated `q'), or type an 1055 end-of-file character (usually `Ctrl-d'). If you do not supply 1056 EXPRESSION, GDB will terminate normally; otherwise it will 1057 terminate using the result of EXPRESSION as the error code. 1058 1059 An interrupt (often `Ctrl-c') does not exit from GDB, but rather 1060terminates the action of any GDB command that is in progress and 1061returns to GDB command level. It is safe to type the interrupt 1062character at any time because GDB does not allow it to take effect 1063until a time when it is safe. 1064 1065 If you have been using GDB to control an attached process or device, 1066you can release it with the `detach' command (*note Debugging an 1067Already-running Process: Attach.). 1068 1069 1070File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation 1071 10722.3 Shell Commands 1073================== 1074 1075If you need to execute occasional shell commands during your debugging 1076session, there is no need to leave or suspend GDB; you can just use the 1077`shell' command. 1078 1079`shell COMMAND STRING' 1080 Invoke a standard shell to execute COMMAND STRING. If it exists, 1081 the environment variable `SHELL' determines which shell to run. 1082 Otherwise GDB uses the default shell (`/bin/sh' on Unix systems, 1083 `COMMAND.COM' on MS-DOS, etc.). 1084 1085 The utility `make' is often needed in development environments. You 1086do not have to use the `shell' command for this purpose in GDB: 1087 1088`make MAKE-ARGS' 1089 Execute the `make' program with the specified arguments. This is 1090 equivalent to `shell make MAKE-ARGS'. 1091 1092 1093File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation 1094 10952.4 Logging Output 1096================== 1097 1098You may want to save the output of GDB commands to a file. There are 1099several commands to control GDB's logging. 1100 1101`set logging on' 1102 Enable logging. 1103 1104`set logging off' 1105 Disable logging. 1106 1107`set logging file FILE' 1108 Change the name of the current logfile. The default logfile is 1109 `gdb.txt'. 1110 1111`set logging overwrite [on|off]' 1112 By default, GDB will append to the logfile. Set `overwrite' if 1113 you want `set logging on' to overwrite the logfile instead. 1114 1115`set logging redirect [on|off]' 1116 By default, GDB output will go to both the terminal and the 1117 logfile. Set `redirect' if you want output to go only to the log 1118 file. 1119 1120`show logging' 1121 Show the current values of the logging settings. 1122 1123 1124File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top 1125 11263 GDB Commands 1127************** 1128 1129You can abbreviate a GDB command to the first few letters of the command 1130name, if that abbreviation is unambiguous; and you can repeat certain 1131GDB commands by typing just <RET>. You can also use the <TAB> key to 1132get GDB to fill out the rest of a word in a command (or to show you the 1133alternatives available, if there is more than one possibility). 1134 1135* Menu: 1136 1137* Command Syntax:: How to give commands to GDB 1138* Completion:: Command completion 1139* Help:: How to ask GDB for help 1140 1141 1142File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands 1143 11443.1 Command Syntax 1145================== 1146 1147A GDB command is a single line of input. There is no limit on how long 1148it can be. It starts with a command name, which is followed by 1149arguments whose meaning depends on the command name. For example, the 1150command `step' accepts an argument which is the number of times to 1151step, as in `step 5'. You can also use the `step' command with no 1152arguments. Some commands do not allow any arguments. 1153 1154 GDB command names may always be truncated if that abbreviation is 1155unambiguous. Other possible command abbreviations are listed in the 1156documentation for individual commands. In some cases, even ambiguous 1157abbreviations are allowed; for example, `s' is specially defined as 1158equivalent to `step' even though there are other commands whose names 1159start with `s'. You can test abbreviations by using them as arguments 1160to the `help' command. 1161 1162 A blank line as input to GDB (typing just <RET>) means to repeat the 1163previous command. Certain commands (for example, `run') will not 1164repeat this way; these are commands whose unintentional repetition 1165might cause trouble and which you are unlikely to want to repeat. 1166User-defined commands can disable this feature; see *note dont-repeat: 1167Define. 1168 1169 The `list' and `x' commands, when you repeat them with <RET>, 1170construct new arguments rather than repeating exactly as typed. This 1171permits easy scanning of source or memory. 1172 1173 GDB can also use <RET> in another way: to partition lengthy output, 1174in a way similar to the common utility `more' (*note Screen Size: 1175Screen Size.). Since it is easy to press one <RET> too many in this 1176situation, GDB disables command repetition after any command that 1177generates this sort of display. 1178 1179 Any text from a `#' to the end of the line is a comment; it does 1180nothing. This is useful mainly in command files (*note Command Files: 1181Command Files.). 1182 1183 The `Ctrl-o' binding is useful for repeating a complex sequence of 1184commands. This command accepts the current line, like <RET>, and then 1185fetches the next line relative to the current line from the history for 1186editing. 1187 1188 1189File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands 1190 11913.2 Command Completion 1192====================== 1193 1194GDB can fill in the rest of a word in a command for you, if there is 1195only one possibility; it can also show you what the valid possibilities 1196are for the next word in a command, at any time. This works for GDB 1197commands, GDB subcommands, and the names of symbols in your program. 1198 1199 Press the <TAB> key whenever you want GDB to fill out the rest of a 1200word. If there is only one possibility, GDB fills in the word, and 1201waits for you to finish the command (or press <RET> to enter it). For 1202example, if you type 1203 1204 (gdb) info bre <TAB> 1205 1206GDB fills in the rest of the word `breakpoints', since that is the only 1207`info' subcommand beginning with `bre': 1208 1209 (gdb) info breakpoints 1210 1211You can either press <RET> at this point, to run the `info breakpoints' 1212command, or backspace and enter something else, if `breakpoints' does 1213not look like the command you expected. (If you were sure you wanted 1214`info breakpoints' in the first place, you might as well just type 1215<RET> immediately after `info bre', to exploit command abbreviations 1216rather than command completion). 1217 1218 If there is more than one possibility for the next word when you 1219press <TAB>, GDB sounds a bell. You can either supply more characters 1220and try again, or just press <TAB> a second time; GDB displays all the 1221possible completions for that word. For example, you might want to set 1222a breakpoint on a subroutine whose name begins with `make_', but when 1223you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again 1224displays all the function names in your program that begin with those 1225characters, for example: 1226 1227 (gdb) b make_ <TAB> 1228GDB sounds bell; press <TAB> again, to see: 1229 make_a_section_from_file make_environ 1230 make_abs_section make_function_type 1231 make_blockvector make_pointer_type 1232 make_cleanup make_reference_type 1233 make_command make_symbol_completion_list 1234 (gdb) b make_ 1235 1236After displaying the available possibilities, GDB copies your partial 1237input (`b make_' in the example) so you can finish the command. 1238 1239 If you just want to see the list of alternatives in the first place, 1240you can press `M-?' rather than pressing <TAB> twice. `M-?' means 1241`<META> ?'. You can type this either by holding down a key designated 1242as the <META> shift on your keyboard (if there is one) while typing 1243`?', or as <ESC> followed by `?'. 1244 1245 Sometimes the string you need, while logically a "word", may contain 1246parentheses or other characters that GDB normally excludes from its 1247notion of a word. To permit word completion to work in this situation, 1248you may enclose words in `'' (single quote marks) in GDB commands. 1249 1250 The most likely situation where you might need this is in typing the 1251name of a C++ function. This is because C++ allows function 1252overloading (multiple definitions of the same function, distinguished 1253by argument type). For example, when you want to set a breakpoint you 1254may need to distinguish whether you mean the version of `name' that 1255takes an `int' parameter, `name(int)', or the version that takes a 1256`float' parameter, `name(float)'. To use the word-completion 1257facilities in this situation, type a single quote `'' at the beginning 1258of the function name. This alerts GDB that it may need to consider 1259more information than usual when you press <TAB> or `M-?' to request 1260word completion: 1261 1262 (gdb) b 'bubble( M-? 1263 bubble(double,double) bubble(int,int) 1264 (gdb) b 'bubble( 1265 1266 In some cases, GDB can tell that completing a name requires using 1267quotes. When this happens, GDB inserts the quote for you (while 1268completing as much as it can) if you do not type the quote in the first 1269place: 1270 1271 (gdb) b bub <TAB> 1272GDB alters your input line to the following, and rings a bell: 1273 (gdb) b 'bubble( 1274 1275In general, GDB can tell that a quote is needed (and inserts it) if you 1276have not yet started typing the argument list when you ask for 1277completion on an overloaded symbol. 1278 1279 For more information about overloaded functions, see *note C++ 1280Expressions: C Plus Plus Expressions. You can use the command `set 1281overload-resolution off' to disable overload resolution; see *note GDB 1282Features for C++: Debugging C Plus Plus. 1283 1284 When completing in an expression which looks up a field in a 1285structure, GDB also tries(1) to limit completions to the field names 1286available in the type of the left-hand-side: 1287 1288 (gdb) p gdb_stdout.M-? 1289 magic to_delete to_fputs to_put to_rewind 1290 to_data to_flush to_isatty to_read to_write 1291 1292This is because the `gdb_stdout' is a variable of the type `struct 1293ui_file' that is defined in GDB sources as follows: 1294 1295 struct ui_file 1296 { 1297 int *magic; 1298 ui_file_flush_ftype *to_flush; 1299 ui_file_write_ftype *to_write; 1300 ui_file_fputs_ftype *to_fputs; 1301 ui_file_read_ftype *to_read; 1302 ui_file_delete_ftype *to_delete; 1303 ui_file_isatty_ftype *to_isatty; 1304 ui_file_rewind_ftype *to_rewind; 1305 ui_file_put_ftype *to_put; 1306 void *to_data; 1307 } 1308 1309 ---------- Footnotes ---------- 1310 1311 (1) The completer can be confused by certain kinds of invalid 1312expressions. Also, it only examines the static type of the expression, 1313not the dynamic type. 1314 1315 1316File: gdb.info, Node: Help, Prev: Completion, Up: Commands 1317 13183.3 Getting Help 1319================ 1320 1321You can always ask GDB itself for information on its commands, using 1322the command `help'. 1323 1324`help' 1325`h' 1326 You can use `help' (abbreviated `h') with no arguments to display 1327 a short list of named classes of commands: 1328 1329 (gdb) help 1330 List of classes of commands: 1331 1332 aliases -- Aliases of other commands 1333 breakpoints -- Making program stop at certain points 1334 data -- Examining data 1335 files -- Specifying and examining files 1336 internals -- Maintenance commands 1337 obscure -- Obscure features 1338 running -- Running the program 1339 stack -- Examining the stack 1340 status -- Status inquiries 1341 support -- Support facilities 1342 tracepoints -- Tracing of program execution without 1343 stopping the program 1344 user-defined -- User-defined commands 1345 1346 Type "help" followed by a class name for a list of 1347 commands in that class. 1348 Type "help" followed by command name for full 1349 documentation. 1350 Command name abbreviations are allowed if unambiguous. 1351 (gdb) 1352 1353`help CLASS' 1354 Using one of the general help classes as an argument, you can get a 1355 list of the individual commands in that class. For example, here 1356 is the help display for the class `status': 1357 1358 (gdb) help status 1359 Status inquiries. 1360 1361 List of commands: 1362 1363 info -- Generic command for showing things 1364 about the program being debugged 1365 show -- Generic command for showing things 1366 about the debugger 1367 1368 Type "help" followed by command name for full 1369 documentation. 1370 Command name abbreviations are allowed if unambiguous. 1371 (gdb) 1372 1373`help COMMAND' 1374 With a command name as `help' argument, GDB displays a short 1375 paragraph on how to use that command. 1376 1377`apropos ARGS' 1378 The `apropos' command searches through all of the GDB commands, 1379 and their documentation, for the regular expression specified in 1380 ARGS. It prints out all matches found. For example: 1381 1382 apropos reload 1383 1384 results in: 1385 1386 set symbol-reloading -- Set dynamic symbol table reloading 1387 multiple times in one run 1388 show symbol-reloading -- Show dynamic symbol table reloading 1389 multiple times in one run 1390 1391`complete ARGS' 1392 The `complete ARGS' command lists all the possible completions for 1393 the beginning of a command. Use ARGS to specify the beginning of 1394 the command you want completed. For example: 1395 1396 complete i 1397 1398 results in: 1399 1400 if 1401 ignore 1402 info 1403 inspect 1404 1405 This is intended for use by GNU Emacs. 1406 1407 In addition to `help', you can use the GDB commands `info' and 1408`show' to inquire about the state of your program, or the state of GDB 1409itself. Each command supports many topics of inquiry; this manual 1410introduces each of them in the appropriate context. The listings under 1411`info' and under `show' in the Index point to all the sub-commands. 1412*Note GDB Index::. 1413 1414`info' 1415 This command (abbreviated `i') is for describing the state of your 1416 program. For example, you can show the arguments passed to a 1417 function with `info args', list the registers currently in use 1418 with `info registers', or list the breakpoints you have set with 1419 `info breakpoints'. You can get a complete list of the `info' 1420 sub-commands with `help info'. 1421 1422`set' 1423 You can assign the result of an expression to an environment 1424 variable with `set'. For example, you can set the GDB prompt to a 1425 $-sign with `set prompt $'. 1426 1427`show' 1428 In contrast to `info', `show' is for describing the state of GDB 1429 itself. You can change most of the things you can `show', by 1430 using the related command `set'; for example, you can control what 1431 number system is used for displays with `set radix', or simply 1432 inquire which is currently in use with `show radix'. 1433 1434 To display all the settable parameters and their current values, 1435 you can use `show' with no arguments; you may also use `info set'. 1436 Both commands produce the same display. 1437 1438 Here are three miscellaneous `show' subcommands, all of which are 1439exceptional in lacking corresponding `set' commands: 1440 1441`show version' 1442 Show what version of GDB is running. You should include this 1443 information in GDB bug-reports. If multiple versions of GDB are 1444 in use at your site, you may need to determine which version of 1445 GDB you are running; as GDB evolves, new commands are introduced, 1446 and old ones may wither away. Also, many system vendors ship 1447 variant versions of GDB, and there are variant versions of GDB in 1448 GNU/Linux distributions as well. The version number is the same 1449 as the one announced when you start GDB. 1450 1451`show copying' 1452`info copying' 1453 Display information about permission for copying GDB. 1454 1455`show warranty' 1456`info warranty' 1457 Display the GNU "NO WARRANTY" statement, or a warranty, if your 1458 version of GDB comes with one. 1459 1460 1461 1462File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top 1463 14644 Running Programs Under GDB 1465**************************** 1466 1467When you run a program under GDB, you must first generate debugging 1468information when you compile it. 1469 1470 You may start GDB with its arguments, if any, in an environment of 1471your choice. If you are doing native debugging, you may redirect your 1472program's input and output, debug an already running process, or kill a 1473child process. 1474 1475* Menu: 1476 1477* Compilation:: Compiling for debugging 1478* Starting:: Starting your program 1479* Arguments:: Your program's arguments 1480* Environment:: Your program's environment 1481 1482* Working Directory:: Your program's working directory 1483* Input/Output:: Your program's input and output 1484* Attach:: Debugging an already-running process 1485* Kill Process:: Killing the child process 1486 1487* Inferiors and Programs:: Debugging multiple inferiors and programs 1488* Threads:: Debugging programs with multiple threads 1489* Forks:: Debugging forks 1490* Checkpoint/Restart:: Setting a _bookmark_ to return to later 1491 1492 1493File: gdb.info, Node: Compilation, Next: Starting, Up: Running 1494 14954.1 Compiling for Debugging 1496=========================== 1497 1498In order to debug a program effectively, you need to generate debugging 1499information when you compile it. This debugging information is stored 1500in the object file; it describes the data type of each variable or 1501function and the correspondence between source line numbers and 1502addresses in the executable code. 1503 1504 To request debugging information, specify the `-g' option when you 1505run the compiler. 1506 1507 Programs that are to be shipped to your customers are compiled with 1508optimizations, using the `-O' compiler option. However, some compilers 1509are unable to handle the `-g' and `-O' options together. Using those 1510compilers, you cannot generate optimized executables containing 1511debugging information. 1512 1513 GCC, the GNU C/C++ compiler, supports `-g' with or without `-O', 1514making it possible to debug optimized code. We recommend that you 1515_always_ use `-g' whenever you compile a program. You may think your 1516program is correct, but there is no sense in pushing your luck. For 1517more information, see *note Optimized Code::. 1518 1519 Older versions of the GNU C compiler permitted a variant option 1520`-gg' for debugging information. GDB no longer supports this format; 1521if your GNU C compiler has this option, do not use it. 1522 1523 GDB knows about preprocessor macros and can show you their expansion 1524(*note Macros::). Most compilers do not include information about 1525preprocessor macros in the debugging information if you specify the 1526`-g' flag alone, because this information is rather large. Version 3.1 1527and later of GCC, the GNU C compiler, provides macro information if you 1528specify the options `-gdwarf-2' and `-g3'; the former option requests 1529debugging information in the Dwarf 2 format, and the latter requests 1530"extra information". In the future, we hope to find more compact ways 1531to represent macro information, so that it can be included with `-g' 1532alone. 1533 1534 1535File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running 1536 15374.2 Starting your Program 1538========================= 1539 1540`run' 1541`r' 1542 Use the `run' command to start your program under GDB. You must 1543 first specify the program name (except on VxWorks) with an 1544 argument to GDB (*note Getting In and Out of GDB: Invocation.), or 1545 by using the `file' or `exec-file' command (*note Commands to 1546 Specify Files: Files.). 1547 1548 1549 If you are running your program in an execution environment that 1550supports processes, `run' creates an inferior process and makes that 1551process run your program. In some environments without processes, 1552`run' jumps to the start of your program. Other targets, like 1553`remote', are always running. If you get an error message like this 1554one: 1555 1556 The "remote" target does not support "run". 1557 Try "help target" or "continue". 1558 1559then use `continue' to run your program. You may need `load' first 1560(*note load::). 1561 1562 The execution of a program is affected by certain information it 1563receives from its superior. GDB provides ways to specify this 1564information, which you must do _before_ starting your program. (You 1565can change it after starting your program, but such changes only affect 1566your program the next time you start it.) This information may be 1567divided into four categories: 1568 1569The _arguments._ 1570 Specify the arguments to give your program as the arguments of the 1571 `run' command. If a shell is available on your target, the shell 1572 is used to pass the arguments, so that you may use normal 1573 conventions (such as wildcard expansion or variable substitution) 1574 in describing the arguments. In Unix systems, you can control 1575 which shell is used with the `SHELL' environment variable. *Note 1576 Your Program's Arguments: Arguments. 1577 1578The _environment._ 1579 Your program normally inherits its environment from GDB, but you 1580 can use the GDB commands `set environment' and `unset environment' 1581 to change parts of the environment that affect your program. 1582 *Note Your Program's Environment: Environment. 1583 1584The _working directory._ 1585 Your program inherits its working directory from GDB. You can set 1586 the GDB working directory with the `cd' command in GDB. *Note 1587 Your Program's Working Directory: Working Directory. 1588 1589The _standard input and output._ 1590 Your program normally uses the same device for standard input and 1591 standard output as GDB is using. You can redirect input and output 1592 in the `run' command line, or you can use the `tty' command to set 1593 a different device for your program. *Note Your Program's Input 1594 and Output: Input/Output. 1595 1596 _Warning:_ While input and output redirection work, you cannot use 1597 pipes to pass the output of the program you are debugging to 1598 another program; if you attempt this, GDB is likely to wind up 1599 debugging the wrong program. 1600 1601 When you issue the `run' command, your program begins to execute 1602immediately. *Note Stopping and Continuing: Stopping, for discussion 1603of how to arrange for your program to stop. Once your program has 1604stopped, you may call functions in your program, using the `print' or 1605`call' commands. *Note Examining Data: Data. 1606 1607 If the modification time of your symbol file has changed since the 1608last time GDB read its symbols, GDB discards its symbol table, and 1609reads it again. When it does this, GDB tries to retain your current 1610breakpoints. 1611 1612`start' 1613 The name of the main procedure can vary from language to language. 1614 With C or C++, the main procedure name is always `main', but other 1615 languages such as Ada do not require a specific name for their 1616 main procedure. The debugger provides a convenient way to start 1617 the execution of the program and to stop at the beginning of the 1618 main procedure, depending on the language used. 1619 1620 The `start' command does the equivalent of setting a temporary 1621 breakpoint at the beginning of the main procedure and then invoking 1622 the `run' command. 1623 1624 Some programs contain an "elaboration" phase where some startup 1625 code is executed before the main procedure is called. This 1626 depends on the languages used to write your program. In C++, for 1627 instance, constructors for static and global objects are executed 1628 before `main' is called. It is therefore possible that the 1629 debugger stops before reaching the main procedure. However, the 1630 temporary breakpoint will remain to halt execution. 1631 1632 Specify the arguments to give to your program as arguments to the 1633 `start' command. These arguments will be given verbatim to the 1634 underlying `run' command. Note that the same arguments will be 1635 reused if no argument is provided during subsequent calls to 1636 `start' or `run'. 1637 1638 It is sometimes necessary to debug the program during elaboration. 1639 In these cases, using the `start' command would stop the execution 1640 of your program too late, as the program would have already 1641 completed the elaboration phase. Under these circumstances, 1642 insert breakpoints in your elaboration code before running your 1643 program. 1644 1645`set exec-wrapper WRAPPER' 1646`show exec-wrapper' 1647`unset exec-wrapper' 1648 When `exec-wrapper' is set, the specified wrapper is used to 1649 launch programs for debugging. GDB starts your program with a 1650 shell command of the form `exec WRAPPER PROGRAM'. Quoting is 1651 added to PROGRAM and its arguments, but not to WRAPPER, so you 1652 should add quotes if appropriate for your shell. The wrapper runs 1653 until it executes your program, and then GDB takes control. 1654 1655 You can use any program that eventually calls `execve' with its 1656 arguments as a wrapper. Several standard Unix utilities do this, 1657 e.g. `env' and `nohup'. Any Unix shell script ending with `exec 1658 "$@"' will also work. 1659 1660 For example, you can use `env' to pass an environment variable to 1661 the debugged program, without setting the variable in your shell's 1662 environment: 1663 1664 (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so' 1665 (gdb) run 1666 1667 This command is available when debugging locally on most targets, 1668 excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino. 1669 1670`set disable-randomization' 1671`set disable-randomization on' 1672 This option (enabled by default in GDB) will turn off the native 1673 randomization of the virtual address space of the started program. 1674 This option is useful for multiple debugging sessions to make the 1675 execution better reproducible and memory addresses reusable across 1676 debugging sessions. 1677 1678 This feature is implemented only on GNU/Linux. You can get the 1679 same behavior using 1680 1681 (gdb) set exec-wrapper setarch `uname -m` -R 1682 1683`set disable-randomization off' 1684 Leave the behavior of the started executable unchanged. Some bugs 1685 rear their ugly heads only when the program is loaded at certain 1686 addresses. If your bug disappears when you run the program under 1687 GDB, that might be because GDB by default disables the address 1688 randomization on platforms, such as GNU/Linux, which do that for 1689 stand-alone programs. Use `set disable-randomization off' to try 1690 to reproduce such elusive bugs. 1691 1692 The virtual address space randomization is implemented only on 1693 GNU/Linux. It protects the programs against some kinds of 1694 security attacks. In these cases the attacker needs to know the 1695 exact location of a concrete executable code. Randomizing its 1696 location makes it impossible to inject jumps misusing a code at 1697 its expected addresses. 1698 1699 Prelinking shared libraries provides a startup performance 1700 advantage but it makes addresses in these libraries predictable 1701 for privileged processes by having just unprivileged access at the 1702 target system. Reading the shared library binary gives enough 1703 information for assembling the malicious code misusing it. Still 1704 even a prelinked shared library can get loaded at a new random 1705 address just requiring the regular relocation process during the 1706 startup. Shared libraries not already prelinked are always loaded 1707 at a randomly chosen address. 1708 1709 Position independent executables (PIE) contain position 1710 independent code similar to the shared libraries and therefore 1711 such executables get loaded at a randomly chosen address upon 1712 startup. PIE executables always load even already prelinked 1713 shared libraries at a random address. You can build such 1714 executable using `gcc -fPIE -pie'. 1715 1716 Heap (malloc storage), stack and custom mmap areas are always 1717 placed randomly (as long as the randomization is enabled). 1718 1719`show disable-randomization' 1720 Show the current setting of the explicit disable of the native 1721 randomization of the virtual address space of the started program. 1722 1723 1724 1725File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running 1726 17274.3 Your Program's Arguments 1728============================ 1729 1730The arguments to your program can be specified by the arguments of the 1731`run' command. They are passed to a shell, which expands wildcard 1732characters and performs redirection of I/O, and thence to your program. 1733Your `SHELL' environment variable (if it exists) specifies what shell 1734GDB uses. If you do not define `SHELL', GDB uses the default shell 1735(`/bin/sh' on Unix). 1736 1737 On non-Unix systems, the program is usually invoked directly by GDB, 1738which emulates I/O redirection via the appropriate system calls, and 1739the wildcard characters are expanded by the startup code of the 1740program, not by the shell. 1741 1742 `run' with no arguments uses the same arguments used by the previous 1743`run', or those set by the `set args' command. 1744 1745`set args' 1746 Specify the arguments to be used the next time your program is 1747 run. If `set args' has no arguments, `run' executes your program 1748 with no arguments. Once you have run your program with arguments, 1749 using `set args' before the next `run' is the only way to run it 1750 again without arguments. 1751 1752`show args' 1753 Show the arguments to give your program when it is started. 1754 1755 1756File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running 1757 17584.4 Your Program's Environment 1759============================== 1760 1761The "environment" consists of a set of environment variables and their 1762values. Environment variables conventionally record such things as 1763your user name, your home directory, your terminal type, and your search 1764path for programs to run. Usually you set up environment variables with 1765the shell and they are inherited by all the other programs you run. 1766When debugging, it can be useful to try running your program with a 1767modified environment without having to start GDB over again. 1768 1769`path DIRECTORY' 1770 Add DIRECTORY to the front of the `PATH' environment variable (the 1771 search path for executables) that will be passed to your program. 1772 The value of `PATH' used by GDB does not change. You may specify 1773 several directory names, separated by whitespace or by a 1774 system-dependent separator character (`:' on Unix, `;' on MS-DOS 1775 and MS-Windows). If DIRECTORY is already in the path, it is moved 1776 to the front, so it is searched sooner. 1777 1778 You can use the string `$cwd' to refer to whatever is the current 1779 working directory at the time GDB searches the path. If you use 1780 `.' instead, it refers to the directory where you executed the 1781 `path' command. GDB replaces `.' in the DIRECTORY argument (with 1782 the current path) before adding DIRECTORY to the search path. 1783 1784`show paths' 1785 Display the list of search paths for executables (the `PATH' 1786 environment variable). 1787 1788`show environment [VARNAME]' 1789 Print the value of environment variable VARNAME to be given to 1790 your program when it starts. If you do not supply VARNAME, print 1791 the names and values of all environment variables to be given to 1792 your program. You can abbreviate `environment' as `env'. 1793 1794`set environment VARNAME [=VALUE]' 1795 Set environment variable VARNAME to VALUE. The value changes for 1796 your program only, not for GDB itself. VALUE may be any string; 1797 the values of environment variables are just strings, and any 1798 interpretation is supplied by your program itself. The VALUE 1799 parameter is optional; if it is eliminated, the variable is set to 1800 a null value. 1801 1802 For example, this command: 1803 1804 set env USER = foo 1805 1806 tells the debugged program, when subsequently run, that its user 1807 is named `foo'. (The spaces around `=' are used for clarity here; 1808 they are not actually required.) 1809 1810`unset environment VARNAME' 1811 Remove variable VARNAME from the environment to be passed to your 1812 program. This is different from `set env VARNAME ='; `unset 1813 environment' removes the variable from the environment, rather 1814 than assigning it an empty value. 1815 1816 _Warning:_ On Unix systems, GDB runs your program using the shell 1817indicated by your `SHELL' environment variable if it exists (or 1818`/bin/sh' if not). If your `SHELL' variable names a shell that runs an 1819initialization file--such as `.cshrc' for C-shell, or `.bashrc' for 1820BASH--any variables you set in that file affect your program. You may 1821wish to move setting of environment variables to files that are only 1822run when you sign on, such as `.login' or `.profile'. 1823 1824 1825File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running 1826 18274.5 Your Program's Working Directory 1828==================================== 1829 1830Each time you start your program with `run', it inherits its working 1831directory from the current working directory of GDB. The GDB working 1832directory is initially whatever it inherited from its parent process 1833(typically the shell), but you can specify a new working directory in 1834GDB with the `cd' command. 1835 1836 The GDB working directory also serves as a default for the commands 1837that specify files for GDB to operate on. *Note Commands to Specify 1838Files: Files. 1839 1840`cd DIRECTORY' 1841 Set the GDB working directory to DIRECTORY. 1842 1843`pwd' 1844 Print the GDB working directory. 1845 1846 It is generally impossible to find the current working directory of 1847the process being debugged (since a program can change its directory 1848during its run). If you work on a system where GDB is configured with 1849the `/proc' support, you can use the `info proc' command (*note SVR4 1850Process Information::) to find out the current working directory of the 1851debuggee. 1852 1853 1854File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running 1855 18564.6 Your Program's Input and Output 1857=================================== 1858 1859By default, the program you run under GDB does input and output to the 1860same terminal that GDB uses. GDB switches the terminal to its own 1861terminal modes to interact with you, but it records the terminal modes 1862your program was using and switches back to them when you continue 1863running your program. 1864 1865`info terminal' 1866 Displays information recorded by GDB about the terminal modes your 1867 program is using. 1868 1869 You can redirect your program's input and/or output using shell 1870redirection with the `run' command. For example, 1871 1872 run > outfile 1873 1874starts your program, diverting its output to the file `outfile'. 1875 1876 Another way to specify where your program should do input and output 1877is with the `tty' command. This command accepts a file name as 1878argument, and causes this file to be the default for future `run' 1879commands. It also resets the controlling terminal for the child 1880process, for future `run' commands. For example, 1881 1882 tty /dev/ttyb 1883 1884directs that processes started with subsequent `run' commands default 1885to do input and output on the terminal `/dev/ttyb' and have that as 1886their controlling terminal. 1887 1888 An explicit redirection in `run' overrides the `tty' command's 1889effect on the input/output device, but not its effect on the controlling 1890terminal. 1891 1892 When you use the `tty' command or redirect input in the `run' 1893command, only the input _for your program_ is affected. The input for 1894GDB still comes from your terminal. `tty' is an alias for `set 1895inferior-tty'. 1896 1897 You can use the `show inferior-tty' command to tell GDB to display 1898the name of the terminal that will be used for future runs of your 1899program. 1900 1901`set inferior-tty /dev/ttyb' 1902 Set the tty for the program being debugged to /dev/ttyb. 1903 1904`show inferior-tty' 1905 Show the current tty for the program being debugged. 1906 1907 1908File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running 1909 19104.7 Debugging an Already-running Process 1911======================================== 1912 1913`attach PROCESS-ID' 1914 This command attaches to a running process--one that was started 1915 outside GDB. (`info files' shows your active targets.) The 1916 command takes as argument a process ID. The usual way to find out 1917 the PROCESS-ID of a Unix process is with the `ps' utility, or with 1918 the `jobs -l' shell command. 1919 1920 `attach' does not repeat if you press <RET> a second time after 1921 executing the command. 1922 1923 To use `attach', your program must be running in an environment 1924which supports processes; for example, `attach' does not work for 1925programs on bare-board targets that lack an operating system. You must 1926also have permission to send the process a signal. 1927 1928 When you use `attach', the debugger finds the program running in the 1929process first by looking in the current working directory, then (if the 1930program is not found) by using the source file search path (*note 1931Specifying Source Directories: Source Path.). You can also use the 1932`file' command to load the program. *Note Commands to Specify Files: 1933Files. 1934 1935 The first thing GDB does after arranging to debug the specified 1936process is to stop it. You can examine and modify an attached process 1937with all the GDB commands that are ordinarily available when you start 1938processes with `run'. You can insert breakpoints; you can step and 1939continue; you can modify storage. If you would rather the process 1940continue running, you may use the `continue' command after attaching 1941GDB to the process. 1942 1943`detach' 1944 When you have finished debugging the attached process, you can use 1945 the `detach' command to release it from GDB control. Detaching 1946 the process continues its execution. After the `detach' command, 1947 that process and GDB become completely independent once more, and 1948 you are ready to `attach' another process or start one with `run'. 1949 `detach' does not repeat if you press <RET> again after executing 1950 the command. 1951 1952 If you exit GDB while you have an attached process, you detach that 1953process. If you use the `run' command, you kill that process. By 1954default, GDB asks for confirmation if you try to do either of these 1955things; you can control whether or not you need to confirm by using the 1956`set confirm' command (*note Optional Warnings and Messages: 1957Messages/Warnings.). 1958 1959 1960File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running 1961 19624.8 Killing the Child Process 1963============================= 1964 1965`kill' 1966 Kill the child process in which your program is running under GDB. 1967 1968 This command is useful if you wish to debug a core dump instead of a 1969running process. GDB ignores any core dump file while your program is 1970running. 1971 1972 On some operating systems, a program cannot be executed outside GDB 1973while you have breakpoints set on it inside GDB. You can use the 1974`kill' command in this situation to permit running your program outside 1975the debugger. 1976 1977 The `kill' command is also useful if you wish to recompile and 1978relink your program, since on many systems it is impossible to modify an 1979executable file while it is running in a process. In this case, when 1980you next type `run', GDB notices that the file has changed, and reads 1981the symbol table again (while trying to preserve your current 1982breakpoint settings). 1983 1984 1985File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running 1986 19874.9 Debugging Multiple Inferiors and Programs 1988============================================= 1989 1990GDB lets you run and debug multiple programs in a single session. In 1991addition, GDB on some systems may let you run several programs 1992simultaneously (otherwise you have to exit from one before starting 1993another). In the most general case, you can have multiple threads of 1994execution in each of multiple processes, launched from multiple 1995executables. 1996 1997 GDB represents the state of each program execution with an object 1998called an "inferior". An inferior typically corresponds to a process, 1999but is more general and applies also to targets that do not have 2000processes. Inferiors may be created before a process runs, and may be 2001retained after a process exits. Inferiors have unique identifiers that 2002are different from process ids. Usually each inferior will also have 2003its own distinct address space, although some embedded targets may have 2004several inferiors running in different parts of a single address space. 2005Each inferior may in turn have multiple threads running in it. 2006 2007 To find out what inferiors exist at any moment, use `info inferiors': 2008 2009`info inferiors' 2010 Print a list of all inferiors currently being managed by GDB. 2011 2012 GDB displays for each inferior (in this order): 2013 2014 1. the inferior number assigned by GDB 2015 2016 2. the target system's inferior identifier 2017 2018 3. the name of the executable the inferior is running. 2019 2020 2021 An asterisk `*' preceding the GDB inferior number indicates the 2022 current inferior. 2023 2024 For example, 2025 2026 (gdb) info inferiors 2027 Num Description Executable 2028 2 process 2307 hello 2029 * 1 process 3401 goodbye 2030 2031 To switch focus between inferiors, use the `inferior' command: 2032 2033`inferior INFNO' 2034 Make inferior number INFNO the current inferior. The argument 2035 INFNO is the inferior number assigned by GDB, as shown in the 2036 first field of the `info inferiors' display. 2037 2038 You can get multiple executables into a debugging session via the 2039`add-inferior' and `clone-inferior' commands. On some systems GDB can 2040add inferiors to the debug session automatically by following calls to 2041`fork' and `exec'. To remove inferiors from the debugging session use 2042the `remove-inferior' command. 2043 2044`add-inferior [ -copies N ] [ -exec EXECUTABLE ]' 2045 Adds N inferiors to be run using EXECUTABLE as the executable. N 2046 defaults to 1. If no executable is specified, the inferiors 2047 begins empty, with no program. You can still assign or change the 2048 program assigned to the inferior at any time by using the `file' 2049 command with the executable name as its argument. 2050 2051`clone-inferior [ -copies N ] [ INFNO ]' 2052 Adds N inferiors ready to execute the same program as inferior 2053 INFNO. N defaults to 1. INFNO defaults to the number of the 2054 current inferior. This is a convenient command when you want to 2055 run another instance of the inferior you are debugging. 2056 2057 (gdb) info inferiors 2058 Num Description Executable 2059 * 1 process 29964 helloworld 2060 (gdb) clone-inferior 2061 Added inferior 2. 2062 1 inferiors added. 2063 (gdb) info inferiors 2064 Num Description Executable 2065 2 <null> helloworld 2066 * 1 process 29964 helloworld 2067 2068 You can now simply switch focus to inferior 2 and run it. 2069 2070`remove-inferior INFNO' 2071 Removes the inferior INFNO. It is not possible to remove an 2072 inferior that is running with this command. For those, use the 2073 `kill' or `detach' command first. 2074 2075 2076 To quit debugging one of the running inferiors that is not the 2077current inferior, you can either detach from it by using the 2078`detach inferior' command (allowing it to run independently), or kill it 2079using the `kill inferior' command: 2080 2081`detach inferior INFNO' 2082 Detach from the inferior identified by GDB inferior number INFNO. 2083 Note that the inferior's entry still stays on the list of 2084 inferiors shown by `info inferiors', but its Description will show 2085 `<null>'. 2086 2087`kill inferior INFNO' 2088 Kill the inferior identified by GDB inferior number INFNO. Note 2089 that the inferior's entry still stays on the list of inferiors 2090 shown by `info inferiors', but its Description will show `<null>'. 2091 2092 After the successful completion of a command such as `detach', 2093`detach inferior', `kill' or `kill inferior', or after a normal process 2094exit, the inferior is still valid and listed with `info inferiors', 2095ready to be restarted. 2096 2097 To be notified when inferiors are started or exit under GDB's 2098control use `set print inferior-events': 2099 2100`set print inferior-events' 2101`set print inferior-events on' 2102`set print inferior-events off' 2103 The `set print inferior-events' command allows you to enable or 2104 disable printing of messages when GDB notices that new inferiors 2105 have started or that inferiors have exited or have been detached. 2106 By default, these messages will not be printed. 2107 2108`show print inferior-events' 2109 Show whether messages will be printed when GDB detects that 2110 inferiors have started, exited or have been detached. 2111 2112 Many commands will work the same with multiple programs as with a 2113single program: e.g., `print myglobal' will simply display the value of 2114`myglobal' in the current inferior. 2115 2116 Occasionaly, when debugging GDB itself, it may be useful to get more 2117info about the relationship of inferiors, programs, address spaces in a 2118debug session. You can do that with the `maint info program-spaces' 2119command. 2120 2121`maint info program-spaces' 2122 Print a list of all program spaces currently being managed by GDB. 2123 2124 GDB displays for each program space (in this order): 2125 2126 1. the program space number assigned by GDB 2127 2128 2. the name of the executable loaded into the program space, 2129 with e.g., the `file' command. 2130 2131 2132 An asterisk `*' preceding the GDB program space number indicates 2133 the current program space. 2134 2135 In addition, below each program space line, GDB prints extra 2136 information that isn't suitable to display in tabular form. For 2137 example, the list of inferiors bound to the program space. 2138 2139 (gdb) maint info program-spaces 2140 Id Executable 2141 2 goodbye 2142 Bound inferiors: ID 1 (process 21561) 2143 * 1 hello 2144 2145 Here we can see that no inferior is running the program `hello', 2146 while `process 21561' is running the program `goodbye'. On some 2147 targets, it is possible that multiple inferiors are bound to the 2148 same program space. The most common example is that of debugging 2149 both the parent and child processes of a `vfork' call. For 2150 example, 2151 2152 (gdb) maint info program-spaces 2153 Id Executable 2154 * 1 vfork-test 2155 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) 2156 2157 Here, both inferior 2 and inferior 1 are running in the same 2158 program space as a result of inferior 1 having executed a `vfork' 2159 call. 2160 2161 2162File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running 2163 21644.10 Debugging Programs with Multiple Threads 2165============================================= 2166 2167In some operating systems, such as HP-UX and Solaris, a single program 2168may have more than one "thread" of execution. The precise semantics of 2169threads differ from one operating system to another, but in general the 2170threads of a single program are akin to multiple processes--except that 2171they share one address space (that is, they can all examine and modify 2172the same variables). On the other hand, each thread has its own 2173registers and execution stack, and perhaps private memory. 2174 2175 GDB provides these facilities for debugging multi-thread programs: 2176 2177 * automatic notification of new threads 2178 2179 * `thread THREADNO', a command to switch among threads 2180 2181 * `info threads', a command to inquire about existing threads 2182 2183 * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command 2184 to a list of threads 2185 2186 * thread-specific breakpoints 2187 2188 * `set print thread-events', which controls printing of messages on 2189 thread start and exit. 2190 2191 * `set libthread-db-search-path PATH', which lets the user specify 2192 which `libthread_db' to use if the default choice isn't compatible 2193 with the program. 2194 2195 _Warning:_ These facilities are not yet available on every GDB 2196 configuration where the operating system supports threads. If 2197 your GDB does not support threads, these commands have no effect. 2198 For example, a system without thread support shows no output from 2199 `info threads', and always rejects the `thread' command, like this: 2200 2201 (gdb) info threads 2202 (gdb) thread 1 2203 Thread ID 1 not known. Use the "info threads" command to 2204 see the IDs of currently known threads. 2205 2206 The GDB thread debugging facility allows you to observe all threads 2207while your program runs--but whenever GDB takes control, one thread in 2208particular is always the focus of debugging. This thread is called the 2209"current thread". Debugging commands show program information from the 2210perspective of the current thread. 2211 2212 Whenever GDB detects a new thread in your program, it displays the 2213target system's identification for the thread with a message in the 2214form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies 2215depending on the particular system. For example, on GNU/Linux, you 2216might see 2217 2218 [New Thread 46912507313328 (LWP 25582)] 2219 2220when GDB notices a new thread. In contrast, on an SGI system, the 2221SYSTAG is simply something like `process 368', with no further 2222qualifier. 2223 2224 For debugging purposes, GDB associates its own thread number--always 2225a single integer--with each thread in your program. 2226 2227`info threads' 2228 Display a summary of all threads currently in your program. GDB 2229 displays for each thread (in this order): 2230 2231 1. the thread number assigned by GDB 2232 2233 2. the target system's thread identifier (SYSTAG) 2234 2235 3. the current stack frame summary for that thread 2236 2237 An asterisk `*' to the left of the GDB thread number indicates the 2238 current thread. 2239 2240 For example, 2241 2242 (gdb) info threads 2243 3 process 35 thread 27 0x34e5 in sigpause () 2244 2 process 35 thread 23 0x34e5 in sigpause () 2245 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 2246 at threadtest.c:68 2247 2248 On HP-UX systems: 2249 2250 For debugging purposes, GDB associates its own thread number--a 2251small integer assigned in thread-creation order--with each thread in 2252your program. 2253 2254 Whenever GDB detects a new thread in your program, it displays both 2255GDB's thread number and the target system's identification for the 2256thread with a message in the form `[New SYSTAG]'. SYSTAG is a thread 2257identifier whose form varies depending on the particular system. For 2258example, on HP-UX, you see 2259 2260 [New thread 2 (system thread 26594)] 2261 2262when GDB notices a new thread. 2263 2264`info threads' 2265 Display a summary of all threads currently in your program. GDB 2266 displays for each thread (in this order): 2267 2268 1. the thread number assigned by GDB 2269 2270 2. the target system's thread identifier (SYSTAG) 2271 2272 3. the current stack frame summary for that thread 2273 2274 An asterisk `*' to the left of the GDB thread number indicates the 2275 current thread. 2276 2277 For example, 2278 2279 (gdb) info threads 2280 * 3 system thread 26607 worker (wptr=0x7b09c318 "@") \ 2281 2282 at quicksort.c:137 2283 2 system thread 26606 0x7b0030d8 in __ksleep () \ 2284 2285 from /usr/lib/libc.2 2286 1 system thread 27905 0x7b003498 in _brk () \ 2287 2288 from /usr/lib/libc.2 2289 2290 On Solaris, you can display more information about user threads with 2291a Solaris-specific command: 2292 2293`maint info sol-threads' 2294 Display info on Solaris user threads. 2295 2296`thread THREADNO' 2297 Make thread number THREADNO the current thread. The command 2298 argument THREADNO is the internal GDB thread number, as shown in 2299 the first field of the `info threads' display. GDB responds by 2300 displaying the system identifier of the thread you selected, and 2301 its current stack frame summary: 2302 2303 (gdb) thread 2 2304 [Switching to process 35 thread 23] 2305 0x34e5 in sigpause () 2306 2307 As with the `[New ...]' message, the form of the text after 2308 `Switching to' depends on your system's conventions for identifying 2309 threads. 2310 2311 The debugger convenience variable `$_thread' contains the number 2312 of the current thread. You may find this useful in writing 2313 breakpoint conditional expressions, command scripts, and so forth. 2314 See *Note Convenience Variables: Convenience Vars, for general 2315 information on convenience variables. 2316 2317`thread apply [THREADNO] [ALL] COMMAND' 2318 The `thread apply' command allows you to apply the named COMMAND 2319 to one or more threads. Specify the numbers of the threads that 2320 you want affected with the command argument THREADNO. It can be a 2321 single thread number, one of the numbers shown in the first field 2322 of the `info threads' display; or it could be a range of thread 2323 numbers, as in `2-4'. To apply a command to all threads, type 2324 `thread apply all COMMAND'. 2325 2326`set print thread-events' 2327`set print thread-events on' 2328`set print thread-events off' 2329 The `set print thread-events' command allows you to enable or 2330 disable printing of messages when GDB notices that new threads have 2331 started or that threads have exited. By default, these messages 2332 will be printed if detection of these events is supported by the 2333 target. Note that these messages cannot be disabled on all 2334 targets. 2335 2336`show print thread-events' 2337 Show whether messages will be printed when GDB detects that threads 2338 have started and exited. 2339 2340 *Note Stopping and Starting Multi-thread Programs: Thread Stops, for 2341more information about how GDB behaves when you stop and start programs 2342with multiple threads. 2343 2344 *Note Setting Watchpoints: Set Watchpoints, for information about 2345watchpoints in programs with multiple threads. 2346 2347`set libthread-db-search-path [PATH]' 2348 If this variable is set, PATH is a colon-separated list of 2349 directories GDB will use to search for `libthread_db'. If you 2350 omit PATH, `libthread-db-search-path' will be reset to an empty 2351 list. 2352 2353 On GNU/Linux and Solaris systems, GDB uses a "helper" 2354 `libthread_db' library to obtain information about threads in the 2355 inferior process. GDB will use `libthread-db-search-path' to find 2356 `libthread_db'. If that fails, GDB will continue with default 2357 system shared library directories, and finally the directory from 2358 which `libpthread' was loaded in the inferior process. 2359 2360 For any `libthread_db' library GDB finds in above directories, GDB 2361 attempts to initialize it with the current inferior process. If 2362 this initialization fails (which could happen because of a version 2363 mismatch between `libthread_db' and `libpthread'), GDB will unload 2364 `libthread_db', and continue with the next directory. If none of 2365 `libthread_db' libraries initialize successfully, GDB will issue a 2366 warning and thread debugging will be disabled. 2367 2368 Setting `libthread-db-search-path' is currently implemented only 2369 on some platforms. 2370 2371`show libthread-db-search-path' 2372 Display current libthread_db search path. 2373 2374`set debug libthread-db' 2375`show debug libthread-db' 2376 Turns on or off display of `libthread_db'-related events. Use `1' 2377 to enable, `0' to disable. 2378 2379 2380File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running 2381 23824.11 Debugging Forks 2383==================== 2384 2385On most systems, GDB has no special support for debugging programs 2386which create additional processes using the `fork' function. When a 2387program forks, GDB will continue to debug the parent process and the 2388child process will run unimpeded. If you have set a breakpoint in any 2389code which the child then executes, the child will get a `SIGTRAP' 2390signal which (unless it catches the signal) will cause it to terminate. 2391 2392 However, if you want to debug the child process there is a workaround 2393which isn't too painful. Put a call to `sleep' in the code which the 2394child process executes after the fork. It may be useful to sleep only 2395if a certain environment variable is set, or a certain file exists, so 2396that the delay need not occur when you don't want to run GDB on the 2397child. While the child is sleeping, use the `ps' program to get its 2398process ID. Then tell GDB (a new invocation of GDB if you are also 2399debugging the parent process) to attach to the child process (*note 2400Attach::). From that point on you can debug the child process just 2401like any other process which you attached to. 2402 2403 On some systems, GDB provides support for debugging programs that 2404create additional processes using the `fork' or `vfork' functions. 2405Currently, the only platforms with this feature are HP-UX (11.x and 2406later only?) and GNU/Linux (kernel version 2.5.60 and later). 2407 2408 By default, when a program forks, GDB will continue to debug the 2409parent process and the child process will run unimpeded. 2410 2411 If you want to follow the child process instead of the parent 2412process, use the command `set follow-fork-mode'. 2413 2414`set follow-fork-mode MODE' 2415 Set the debugger response to a program call of `fork' or `vfork'. 2416 A call to `fork' or `vfork' creates a new process. The MODE 2417 argument can be: 2418 2419 `parent' 2420 The original process is debugged after a fork. The child 2421 process runs unimpeded. This is the default. 2422 2423 `child' 2424 The new process is debugged after a fork. The parent process 2425 runs unimpeded. 2426 2427 2428`show follow-fork-mode' 2429 Display the current debugger response to a `fork' or `vfork' call. 2430 2431 On Linux, if you want to debug both the parent and child processes, 2432use the command `set detach-on-fork'. 2433 2434`set detach-on-fork MODE' 2435 Tells gdb whether to detach one of the processes after a fork, or 2436 retain debugger control over them both. 2437 2438 `on' 2439 The child process (or parent process, depending on the value 2440 of `follow-fork-mode') will be detached and allowed to run 2441 independently. This is the default. 2442 2443 `off' 2444 Both processes will be held under the control of GDB. One 2445 process (child or parent, depending on the value of 2446 `follow-fork-mode') is debugged as usual, while the other is 2447 held suspended. 2448 2449 2450`show detach-on-fork' 2451 Show whether detach-on-fork mode is on/off. 2452 2453 If you choose to set `detach-on-fork' mode off, then GDB will retain 2454control of all forked processes (including nested forks). You can list 2455the forked processes under the control of GDB by using the 2456`info inferiors' command, and switch from one fork to another by using 2457the `inferior' command (*note Debugging Multiple Inferiors and 2458Programs: Inferiors and Programs.). 2459 2460 To quit debugging one of the forked processes, you can either detach 2461from it by using the `detach inferior' command (allowing it to run 2462independently), or kill it using the `kill inferior' command. *Note 2463Debugging Multiple Inferiors and Programs: Inferiors and Programs. 2464 2465 If you ask to debug a child process and a `vfork' is followed by an 2466`exec', GDB executes the new target up to the first breakpoint in the 2467new target. If you have a breakpoint set on `main' in your original 2468program, the breakpoint will also be set on the child process's `main'. 2469 2470 On some systems, when a child process is spawned by `vfork', you 2471cannot debug the child or parent until an `exec' call completes. 2472 2473 If you issue a `run' command to GDB after an `exec' call executes, 2474the new target restarts. To restart the parent process, use the `file' 2475command with the parent executable name as its argument. By default, 2476after an `exec' call executes, GDB discards the symbols of the previous 2477executable image. You can change this behaviour with the 2478`set follow-exec-mode' command. 2479 2480`set follow-exec-mode MODE' 2481 Set debugger response to a program call of `exec'. An `exec' call 2482 replaces the program image of a process. 2483 2484 `follow-exec-mode' can be: 2485 2486 `new' 2487 GDB creates a new inferior and rebinds the process to this 2488 new inferior. The program the process was running before the 2489 `exec' call can be restarted afterwards by restarting the 2490 original inferior. 2491 2492 For example: 2493 2494 (gdb) info inferiors 2495 (gdb) info inferior 2496 Id Description Executable 2497 * 1 <null> prog1 2498 (gdb) run 2499 process 12020 is executing new program: prog2 2500 Program exited normally. 2501 (gdb) info inferiors 2502 Id Description Executable 2503 * 2 <null> prog2 2504 1 <null> prog1 2505 2506 `same' 2507 GDB keeps the process bound to the same inferior. The new 2508 executable image replaces the previous executable loaded in 2509 the inferior. Restarting the inferior after the `exec' call, 2510 with e.g., the `run' command, restarts the executable the 2511 process was running after the `exec' call. This is the 2512 default mode. 2513 2514 For example: 2515 2516 (gdb) info inferiors 2517 Id Description Executable 2518 * 1 <null> prog1 2519 (gdb) run 2520 process 12020 is executing new program: prog2 2521 Program exited normally. 2522 (gdb) info inferiors 2523 Id Description Executable 2524 * 1 <null> prog2 2525 2526 2527 You can use the `catch' command to make GDB stop whenever a `fork', 2528`vfork', or `exec' call is made. *Note Setting Catchpoints: Set 2529Catchpoints. 2530 2531 2532File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running 2533 25344.12 Setting a _Bookmark_ to Return to Later 2535============================================ 2536 2537On certain operating systems(1), GDB is able to save a "snapshot" of a 2538program's state, called a "checkpoint", and come back to it later. 2539 2540 Returning to a checkpoint effectively undoes everything that has 2541happened in the program since the `checkpoint' was saved. This 2542includes changes in memory, registers, and even (within some limits) 2543system state. Effectively, it is like going back in time to the moment 2544when the checkpoint was saved. 2545 2546 Thus, if you're stepping thru a program and you think you're getting 2547close to the point where things go wrong, you can save a checkpoint. 2548Then, if you accidentally go too far and miss the critical statement, 2549instead of having to restart your program from the beginning, you can 2550just go back to the checkpoint and start again from there. 2551 2552 This can be especially useful if it takes a lot of time or steps to 2553reach the point where you think the bug occurs. 2554 2555 To use the `checkpoint'/`restart' method of debugging: 2556 2557`checkpoint' 2558 Save a snapshot of the debugged program's current execution state. 2559 The `checkpoint' command takes no arguments, but each checkpoint 2560 is assigned a small integer id, similar to a breakpoint id. 2561 2562`info checkpoints' 2563 List the checkpoints that have been saved in the current debugging 2564 session. For each checkpoint, the following information will be 2565 listed: 2566 2567 `Checkpoint ID' 2568 2569 `Process ID' 2570 2571 `Code Address' 2572 2573 `Source line, or label' 2574 2575`restart CHECKPOINT-ID' 2576 Restore the program state that was saved as checkpoint number 2577 CHECKPOINT-ID. All program variables, registers, stack frames 2578 etc. will be returned to the values that they had when the 2579 checkpoint was saved. In essence, gdb will "wind back the clock" 2580 to the point in time when the checkpoint was saved. 2581 2582 Note that breakpoints, GDB variables, command history etc. are 2583 not affected by restoring a checkpoint. In general, a checkpoint 2584 only restores things that reside in the program being debugged, 2585 not in the debugger. 2586 2587`delete checkpoint CHECKPOINT-ID' 2588 Delete the previously-saved checkpoint identified by CHECKPOINT-ID. 2589 2590 2591 Returning to a previously saved checkpoint will restore the user 2592state of the program being debugged, plus a significant subset of the 2593system (OS) state, including file pointers. It won't "un-write" data 2594from a file, but it will rewind the file pointer to the previous 2595location, so that the previously written data can be overwritten. For 2596files opened in read mode, the pointer will also be restored so that the 2597previously read data can be read again. 2598 2599 Of course, characters that have been sent to a printer (or other 2600external device) cannot be "snatched back", and characters received 2601from eg. a serial device can be removed from internal program buffers, 2602but they cannot be "pushed back" into the serial pipeline, ready to be 2603received again. Similarly, the actual contents of files that have been 2604changed cannot be restored (at this time). 2605 2606 However, within those constraints, you actually can "rewind" your 2607program to a previously saved point in time, and begin debugging it 2608again -- and you can change the course of events so as to debug a 2609different execution path this time. 2610 2611 Finally, there is one bit of internal program state that will be 2612different when you return to a checkpoint -- the program's process id. 2613Each checkpoint will have a unique process id (or PID), and each will 2614be different from the program's original PID. If your program has 2615saved a local copy of its process id, this could potentially pose a 2616problem. 2617 26184.12.1 A Non-obvious Benefit of Using Checkpoints 2619------------------------------------------------- 2620 2621On some systems such as GNU/Linux, address space randomization is 2622performed on new processes for security reasons. This makes it 2623difficult or impossible to set a breakpoint, or watchpoint, on an 2624absolute address if you have to restart the program, since the absolute 2625location of a symbol will change from one execution to the next. 2626 2627 A checkpoint, however, is an _identical_ copy of a process. 2628Therefore if you create a checkpoint at (eg.) the start of main, and 2629simply return to that checkpoint instead of restarting the process, you 2630can avoid the effects of address randomization and your symbols will 2631all stay in the same place. 2632 2633 ---------- Footnotes ---------- 2634 2635 (1) Currently, only GNU/Linux. 2636 2637 2638File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top 2639 26405 Stopping and Continuing 2641************************* 2642 2643The principal purposes of using a debugger are so that you can stop your 2644program before it terminates; or so that, if your program runs into 2645trouble, you can investigate and find out why. 2646 2647 Inside GDB, your program may stop for any of several reasons, such 2648as a signal, a breakpoint, or reaching a new line after a GDB command 2649such as `step'. You may then examine and change variables, set new 2650breakpoints or remove old ones, and then continue execution. Usually, 2651the messages shown by GDB provide ample explanation of the status of 2652your program--but you can also explicitly request this information at 2653any time. 2654 2655`info program' 2656 Display information about the status of your program: whether it is 2657 running or not, what process it is, and why it stopped. 2658 2659* Menu: 2660 2661* Breakpoints:: Breakpoints, watchpoints, and catchpoints 2662* Continuing and Stepping:: Resuming execution 2663* Signals:: Signals 2664* Thread Stops:: Stopping and starting multi-thread programs 2665 2666 2667File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping 2668 26695.1 Breakpoints, Watchpoints, and Catchpoints 2670============================================= 2671 2672A "breakpoint" makes your program stop whenever a certain point in the 2673program is reached. For each breakpoint, you can add conditions to 2674control in finer detail whether your program stops. You can set 2675breakpoints with the `break' command and its variants (*note Setting 2676Breakpoints: Set Breaks.), to specify the place where your program 2677should stop by line number, function name or exact address in the 2678program. 2679 2680 On some systems, you can set breakpoints in shared libraries before 2681the executable is run. There is a minor limitation on HP-UX systems: 2682you must wait until the executable is run in order to set breakpoints 2683in shared library routines that are not called directly by the program 2684(for example, routines that are arguments in a `pthread_create' call). 2685 2686 A "watchpoint" is a special breakpoint that stops your program when 2687the value of an expression changes. The expression may be a value of a 2688variable, or it could involve values of one or more variables combined 2689by operators, such as `a + b'. This is sometimes called "data 2690breakpoints". You must use a different command to set watchpoints 2691(*note Setting Watchpoints: Set Watchpoints.), but aside from that, you 2692can manage a watchpoint like any other breakpoint: you enable, disable, 2693and delete both breakpoints and watchpoints using the same commands. 2694 2695 You can arrange to have values from your program displayed 2696automatically whenever GDB stops at a breakpoint. *Note Automatic 2697Display: Auto Display. 2698 2699 A "catchpoint" is another special breakpoint that stops your program 2700when a certain kind of event occurs, such as the throwing of a C++ 2701exception or the loading of a library. As with watchpoints, you use a 2702different command to set a catchpoint (*note Setting Catchpoints: Set 2703Catchpoints.), but aside from that, you can manage a catchpoint like any 2704other breakpoint. (To stop when your program receives a signal, use the 2705`handle' command; see *note Signals: Signals.) 2706 2707 GDB assigns a number to each breakpoint, watchpoint, or catchpoint 2708when you create it; these numbers are successive integers starting with 2709one. In many of the commands for controlling various features of 2710breakpoints you use the breakpoint number to say which breakpoint you 2711want to change. Each breakpoint may be "enabled" or "disabled"; if 2712disabled, it has no effect on your program until you enable it again. 2713 2714 Some GDB commands accept a range of breakpoints on which to operate. 2715A breakpoint range is either a single breakpoint number, like `5', or 2716two such numbers, in increasing order, separated by a hyphen, like 2717`5-7'. When a breakpoint range is given to a command, all breakpoints 2718in that range are operated on. 2719 2720* Menu: 2721 2722* Set Breaks:: Setting breakpoints 2723* Set Watchpoints:: Setting watchpoints 2724* Set Catchpoints:: Setting catchpoints 2725* Delete Breaks:: Deleting breakpoints 2726* Disabling:: Disabling breakpoints 2727* Conditions:: Break conditions 2728* Break Commands:: Breakpoint command lists 2729* Save Breakpoints:: How to save breakpoints in a file 2730* Error in Breakpoints:: ``Cannot insert breakpoints'' 2731* Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' 2732 2733 2734File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints 2735 27365.1.1 Setting Breakpoints 2737------------------------- 2738 2739Breakpoints are set with the `break' command (abbreviated `b'). The 2740debugger convenience variable `$bpnum' records the number of the 2741breakpoint you've set most recently; see *note Convenience Variables: 2742Convenience Vars, for a discussion of what you can do with convenience 2743variables. 2744 2745`break LOCATION' 2746 Set a breakpoint at the given LOCATION, which can specify a 2747 function name, a line number, or an address of an instruction. 2748 (*Note Specify Location::, for a list of all the possible ways to 2749 specify a LOCATION.) The breakpoint will stop your program just 2750 before it executes any of the code in the specified LOCATION. 2751 2752 When using source languages that permit overloading of symbols, 2753 such as C++, a function name may refer to more than one possible 2754 place to break. *Note Ambiguous Expressions: Ambiguous 2755 Expressions, for a discussion of that situation. 2756 2757 It is also possible to insert a breakpoint that will stop the 2758 program only if a specific thread (*note Thread-Specific 2759 Breakpoints::) or a specific task (*note Ada Tasks::) hits that 2760 breakpoint. 2761 2762`break' 2763 When called without any arguments, `break' sets a breakpoint at 2764 the next instruction to be executed in the selected stack frame 2765 (*note Examining the Stack: Stack.). In any selected frame but the 2766 innermost, this makes your program stop as soon as control returns 2767 to that frame. This is similar to the effect of a `finish' 2768 command in the frame inside the selected frame--except that 2769 `finish' does not leave an active breakpoint. If you use `break' 2770 without an argument in the innermost frame, GDB stops the next 2771 time it reaches the current location; this may be useful inside 2772 loops. 2773 2774 GDB normally ignores breakpoints when it resumes execution, until 2775 at least one instruction has been executed. If it did not do 2776 this, you would be unable to proceed past a breakpoint without 2777 first disabling the breakpoint. This rule applies whether or not 2778 the breakpoint already existed when your program stopped. 2779 2780`break ... if COND' 2781 Set a breakpoint with condition COND; evaluate the expression COND 2782 each time the breakpoint is reached, and stop only if the value is 2783 nonzero--that is, if COND evaluates as true. `...' stands for one 2784 of the possible arguments described above (or no argument) 2785 specifying where to break. *Note Break Conditions: Conditions, 2786 for more information on breakpoint conditions. 2787 2788`tbreak ARGS' 2789 Set a breakpoint enabled only for one stop. ARGS are the same as 2790 for the `break' command, and the breakpoint is set in the same 2791 way, but the breakpoint is automatically deleted after the first 2792 time your program stops there. *Note Disabling Breakpoints: 2793 Disabling. 2794 2795`hbreak ARGS' 2796 Set a hardware-assisted breakpoint. ARGS are the same as for the 2797 `break' command and the breakpoint is set in the same way, but the 2798 breakpoint requires hardware support and some target hardware may 2799 not have this support. The main purpose of this is EPROM/ROM code 2800 debugging, so you can set a breakpoint at an instruction without 2801 changing the instruction. This can be used with the new 2802 trap-generation provided by SPARClite DSU and most x86-based 2803 targets. These targets will generate traps when a program 2804 accesses some data or instruction address that is assigned to the 2805 debug registers. However the hardware breakpoint registers can 2806 take a limited number of breakpoints. For example, on the DSU, 2807 only two data breakpoints can be set at a time, and GDB will 2808 reject this command if more than two are used. Delete or disable 2809 unused hardware breakpoints before setting new ones (*note 2810 Disabling Breakpoints: Disabling.). *Note Break Conditions: 2811 Conditions. For remote targets, you can restrict the number of 2812 hardware breakpoints GDB will use, see *note set remote 2813 hardware-breakpoint-limit::. 2814 2815`thbreak ARGS' 2816 Set a hardware-assisted breakpoint enabled only for one stop. ARGS 2817 are the same as for the `hbreak' command and the breakpoint is set 2818 in the same way. However, like the `tbreak' command, the 2819 breakpoint is automatically deleted after the first time your 2820 program stops there. Also, like the `hbreak' command, the 2821 breakpoint requires hardware support and some target hardware may 2822 not have this support. *Note Disabling Breakpoints: Disabling. 2823 See also *note Break Conditions: Conditions. 2824 2825`rbreak REGEX' 2826 Set breakpoints on all functions matching the regular expression 2827 REGEX. This command sets an unconditional breakpoint on all 2828 matches, printing a list of all breakpoints it set. Once these 2829 breakpoints are set, they are treated just like the breakpoints 2830 set with the `break' command. You can delete them, disable them, 2831 or make them conditional the same way as any other breakpoint. 2832 2833 The syntax of the regular expression is the standard one used with 2834 tools like `grep'. Note that this is different from the syntax 2835 used by shells, so for instance `foo*' matches all functions that 2836 include an `fo' followed by zero or more `o's. There is an 2837 implicit `.*' leading and trailing the regular expression you 2838 supply, so to match only functions that begin with `foo', use 2839 `^foo'. 2840 2841 When debugging C++ programs, `rbreak' is useful for setting 2842 breakpoints on overloaded functions that are not members of any 2843 special classes. 2844 2845 The `rbreak' command can be used to set breakpoints in *all* the 2846 functions in a program, like this: 2847 2848 (gdb) rbreak . 2849 2850`rbreak FILE:REGEX' 2851 If `rbreak' is called with a filename qualification, it limits the 2852 search for functions matching the given regular expression to the 2853 specified FILE. This can be used, for example, to set breakpoints 2854 on every function in a given file: 2855 2856 (gdb) rbreak file.c:. 2857 2858 The colon separating the filename qualifier from the regex may 2859 optionally be surrounded by spaces. 2860 2861`info breakpoints [N]' 2862`info break [N]' 2863 Print a table of all breakpoints, watchpoints, and catchpoints set 2864 and not deleted. Optional argument N means print information only 2865 about the specified breakpoint (or watchpoint or catchpoint). For 2866 each breakpoint, following columns are printed: 2867 2868 _Breakpoint Numbers_ 2869 2870 _Type_ 2871 Breakpoint, watchpoint, or catchpoint. 2872 2873 _Disposition_ 2874 Whether the breakpoint is marked to be disabled or deleted 2875 when hit. 2876 2877 _Enabled or Disabled_ 2878 Enabled breakpoints are marked with `y'. `n' marks 2879 breakpoints that are not enabled. 2880 2881 _Address_ 2882 Where the breakpoint is in your program, as a memory address. 2883 For a pending breakpoint whose address is not yet known, this 2884 field will contain `<PENDING>'. Such breakpoint won't fire 2885 until a shared library that has the symbol or line referred 2886 by breakpoint is loaded. See below for details. A 2887 breakpoint with several locations will have `<MULTIPLE>' in 2888 this field--see below for details. 2889 2890 _What_ 2891 Where the breakpoint is in the source for your program, as a 2892 file and line number. For a pending breakpoint, the original 2893 string passed to the breakpoint command will be listed as it 2894 cannot be resolved until the appropriate shared library is 2895 loaded in the future. 2896 2897 If a breakpoint is conditional, `info break' shows the condition on 2898 the line following the affected breakpoint; breakpoint commands, 2899 if any, are listed after that. A pending breakpoint is allowed to 2900 have a condition specified for it. The condition is not parsed 2901 for validity until a shared library is loaded that allows the 2902 pending breakpoint to resolve to a valid location. 2903 2904 `info break' with a breakpoint number N as argument lists only 2905 that breakpoint. The convenience variable `$_' and the default 2906 examining-address for the `x' command are set to the address of 2907 the last breakpoint listed (*note Examining Memory: Memory.). 2908 2909 `info break' displays a count of the number of times the breakpoint 2910 has been hit. This is especially useful in conjunction with the 2911 `ignore' command. You can ignore a large number of breakpoint 2912 hits, look at the breakpoint info to see how many times the 2913 breakpoint was hit, and then run again, ignoring one less than 2914 that number. This will get you quickly to the last hit of that 2915 breakpoint. 2916 2917 GDB allows you to set any number of breakpoints at the same place in 2918your program. There is nothing silly or meaningless about this. When 2919the breakpoints are conditional, this is even useful (*note Break 2920Conditions: Conditions.). 2921 2922 It is possible that a breakpoint corresponds to several locations in 2923your program. Examples of this situation are: 2924 2925 * For a C++ constructor, the GCC compiler generates several 2926 instances of the function body, used in different cases. 2927 2928 * For a C++ template function, a given line in the function can 2929 correspond to any number of instantiations. 2930 2931 * For an inlined function, a given source line can correspond to 2932 several places where that function is inlined. 2933 2934 In all those cases, GDB will insert a breakpoint at all the relevant 2935locations(1). 2936 2937 A breakpoint with multiple locations is displayed in the breakpoint 2938table using several rows--one header row, followed by one row for each 2939breakpoint location. The header row has `<MULTIPLE>' in the address 2940column. The rows for individual locations contain the actual addresses 2941for locations, and show the functions to which those locations belong. 2942The number column for a location is of the form 2943BREAKPOINT-NUMBER.LOCATION-NUMBER. 2944 2945 For example: 2946 2947 Num Type Disp Enb Address What 2948 1 breakpoint keep y <MULTIPLE> 2949 stop only if i==1 2950 breakpoint already hit 1 time 2951 1.1 y 0x080486a2 in void foo<int>() at t.cc:8 2952 1.2 y 0x080486ca in void foo<double>() at t.cc:8 2953 2954 Each location can be individually enabled or disabled by passing 2955BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and 2956`disable' commands. Note that you cannot delete the individual 2957locations from the list, you can only delete the entire list of 2958locations that belong to their parent breakpoint (with the `delete NUM' 2959command, where NUM is the number of the parent breakpoint, 1 in the 2960above example). Disabling or enabling the parent breakpoint (*note 2961Disabling::) affects all of the locations that belong to that 2962breakpoint. 2963 2964 It's quite common to have a breakpoint inside a shared library. 2965Shared libraries can be loaded and unloaded explicitly, and possibly 2966repeatedly, as the program is executed. To support this use case, GDB 2967updates breakpoint locations whenever any shared library is loaded or 2968unloaded. Typically, you would set a breakpoint in a shared library at 2969the beginning of your debugging session, when the library is not 2970loaded, and when the symbols from the library are not available. When 2971you try to set breakpoint, GDB will ask you if you want to set a so 2972called "pending breakpoint"--breakpoint whose address is not yet 2973resolved. 2974 2975 After the program is run, whenever a new shared library is loaded, 2976GDB reevaluates all the breakpoints. When a newly loaded shared 2977library contains the symbol or line referred to by some pending 2978breakpoint, that breakpoint is resolved and becomes an ordinary 2979breakpoint. When a library is unloaded, all breakpoints that refer to 2980its symbols or source lines become pending again. 2981 2982 This logic works for breakpoints with multiple locations, too. For 2983example, if you have a breakpoint in a C++ template function, and a 2984newly loaded shared library has an instantiation of that template, a 2985new location is added to the list of locations for the breakpoint. 2986 2987 Except for having unresolved address, pending breakpoints do not 2988differ from regular breakpoints. You can set conditions or commands, 2989enable and disable them and perform other breakpoint operations. 2990 2991 GDB provides some additional commands for controlling what happens 2992when the `break' command cannot resolve breakpoint address 2993specification to an address: 2994 2995`set breakpoint pending auto' 2996 This is the default behavior. When GDB cannot find the breakpoint 2997 location, it queries you whether a pending breakpoint should be 2998 created. 2999 3000`set breakpoint pending on' 3001 This indicates that an unrecognized breakpoint location should 3002 automatically result in a pending breakpoint being created. 3003 3004`set breakpoint pending off' 3005 This indicates that pending breakpoints are not to be created. Any 3006 unrecognized breakpoint location results in an error. This 3007 setting does not affect any pending breakpoints previously created. 3008 3009`show breakpoint pending' 3010 Show the current behavior setting for creating pending breakpoints. 3011 3012 The settings above only affect the `break' command and its variants. 3013Once breakpoint is set, it will be automatically updated as shared 3014libraries are loaded and unloaded. 3015 3016 For some targets, GDB can automatically decide if hardware or 3017software breakpoints should be used, depending on whether the 3018breakpoint address is read-only or read-write. This applies to 3019breakpoints set with the `break' command as well as to internal 3020breakpoints set by commands like `next' and `finish'. For breakpoints 3021set with `hbreak', GDB will always use hardware breakpoints. 3022 3023 You can control this automatic behaviour with the following 3024commands:: 3025 3026`set breakpoint auto-hw on' 3027 This is the default behavior. When GDB sets a breakpoint, it will 3028 try to use the target memory map to decide if software or hardware 3029 breakpoint must be used. 3030 3031`set breakpoint auto-hw off' 3032 This indicates GDB should not automatically select breakpoint 3033 type. If the target provides a memory map, GDB will warn when 3034 trying to set software breakpoint at a read-only address. 3035 3036 GDB normally implements breakpoints by replacing the program code at 3037the breakpoint address with a special instruction, which, when 3038executed, given control to the debugger. By default, the program code 3039is so modified only when the program is resumed. As soon as the 3040program stops, GDB restores the original instructions. This behaviour 3041guards against leaving breakpoints inserted in the target should gdb 3042abrubptly disconnect. However, with slow remote targets, inserting and 3043removing breakpoint can reduce the performance. This behavior can be 3044controlled with the following commands:: 3045 3046`set breakpoint always-inserted off' 3047 All breakpoints, including newly added by the user, are inserted in 3048 the target only when the target is resumed. All breakpoints are 3049 removed from the target when it stops. 3050 3051`set breakpoint always-inserted on' 3052 Causes all breakpoints to be inserted in the target at all times. 3053 If the user adds a new breakpoint, or changes an existing 3054 breakpoint, the breakpoints in the target are updated immediately. 3055 A breakpoint is removed from the target only when breakpoint 3056 itself is removed. 3057 3058`set breakpoint always-inserted auto' 3059 This is the default mode. If GDB is controlling the inferior in 3060 non-stop mode (*note Non-Stop Mode::), gdb behaves as if 3061 `breakpoint always-inserted' mode is on. If GDB is controlling 3062 the inferior in all-stop mode, GDB behaves as if `breakpoint 3063 always-inserted' mode is off. 3064 3065 GDB itself sometimes sets breakpoints in your program for special 3066purposes, such as proper handling of `longjmp' (in C programs). These 3067internal breakpoints are assigned negative numbers, starting with `-1'; 3068`info breakpoints' does not display them. You can see these 3069breakpoints with the GDB maintenance command `maint info breakpoints' 3070(*note maint info breakpoints::). 3071 3072 ---------- Footnotes ---------- 3073 3074 (1) As of this writing, multiple-location breakpoints work only if 3075there's line number information for all the locations. This means that 3076they will generally not work in system libraries, unless you have debug 3077info with line numbers for them. 3078 3079 3080File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints 3081 30825.1.2 Setting Watchpoints 3083------------------------- 3084 3085You can use a watchpoint to stop execution whenever the value of an 3086expression changes, without having to predict a particular place where 3087this may happen. (This is sometimes called a "data breakpoint".) The 3088expression may be as simple as the value of a single variable, or as 3089complex as many variables combined by operators. Examples include: 3090 3091 * A reference to the value of a single variable. 3092 3093 * An address cast to an appropriate data type. For example, `*(int 3094 *)0x12345678' will watch a 4-byte region at the specified address 3095 (assuming an `int' occupies 4 bytes). 3096 3097 * An arbitrarily complex expression, such as `a*b + c/d'. The 3098 expression can use any operators valid in the program's native 3099 language (*note Languages::). 3100 3101 You can set a watchpoint on an expression even if the expression can 3102not be evaluated yet. For instance, you can set a watchpoint on 3103`*global_ptr' before `global_ptr' is initialized. GDB will stop when 3104your program sets `global_ptr' and the expression produces a valid 3105value. If the expression becomes valid in some other way than changing 3106a variable (e.g. if the memory pointed to by `*global_ptr' becomes 3107readable as the result of a `malloc' call), GDB may not stop until the 3108next time the expression changes. 3109 3110 Depending on your system, watchpoints may be implemented in software 3111or hardware. GDB does software watchpointing by single-stepping your 3112program and testing the variable's value each time, which is hundreds of 3113times slower than normal execution. (But this may still be worth it, to 3114catch errors where you have no clue what part of your program is the 3115culprit.) 3116 3117 On some systems, such as HP-UX, PowerPC, GNU/Linux and most other 3118x86-based targets, GDB includes support for hardware watchpoints, which 3119do not slow down the running of your program. 3120 3121`watch [-l|-location] EXPR [thread THREADNUM]' 3122 Set a watchpoint for an expression. GDB will break when the 3123 expression EXPR is written into by the program and its value 3124 changes. The simplest (and the most popular) use of this command 3125 is to watch the value of a single variable: 3126 3127 (gdb) watch foo 3128 3129 If the command includes a `[thread THREADNUM]' clause, GDB breaks 3130 only when the thread identified by THREADNUM changes the value of 3131 EXPR. If any other threads change the value of EXPR, GDB will not 3132 break. Note that watchpoints restricted to a single thread in 3133 this way only work with Hardware Watchpoints. 3134 3135 Ordinarily a watchpoint respects the scope of variables in EXPR 3136 (see below). The `-location' argument tells GDB to instead watch 3137 the memory referred to by EXPR. In this case, GDB will evaluate 3138 EXPR, take the address of the result, and watch the memory at that 3139 address. The type of the result is used to determine the size of 3140 the watched memory. If the expression's result does not have an 3141 address, then GDB will print an error. 3142 3143`rwatch [-l|-location] EXPR [thread THREADNUM]' 3144 Set a watchpoint that will break when the value of EXPR is read by 3145 the program. 3146 3147`awatch [-l|-location] EXPR [thread THREADNUM]' 3148 Set a watchpoint that will break when EXPR is either read from or 3149 written into by the program. 3150 3151`info watchpoints' 3152 This command prints a list of watchpoints, using the same format as 3153 `info break' (*note Set Breaks::). 3154 3155 If you watch for a change in a numerically entered address you need 3156to dereference it, as the address itself is just a constant number 3157which will never change. GDB refuses to create a watchpoint that 3158watches a never-changing value: 3159 3160 (gdb) watch 0x600850 3161 Cannot watch constant value 0x600850. 3162 (gdb) watch *(int *) 0x600850 3163 Watchpoint 1: *(int *) 6293584 3164 3165 GDB sets a "hardware watchpoint" if possible. Hardware watchpoints 3166execute very quickly, and the debugger reports a change in value at the 3167exact instruction where the change occurs. If GDB cannot set a 3168hardware watchpoint, it sets a software watchpoint, which executes more 3169slowly and reports the change in value at the next _statement_, not the 3170instruction, after the change occurs. 3171 3172 You can force GDB to use only software watchpoints with the `set 3173can-use-hw-watchpoints 0' command. With this variable set to zero, GDB 3174will never try to use hardware watchpoints, even if the underlying 3175system supports them. (Note that hardware-assisted watchpoints that 3176were set _before_ setting `can-use-hw-watchpoints' to zero will still 3177use the hardware mechanism of watching expression values.) 3178 3179`set can-use-hw-watchpoints' 3180 Set whether or not to use hardware watchpoints. 3181 3182`show can-use-hw-watchpoints' 3183 Show the current mode of using hardware watchpoints. 3184 3185 For remote targets, you can restrict the number of hardware 3186watchpoints GDB will use, see *note set remote 3187hardware-breakpoint-limit::. 3188 3189 When you issue the `watch' command, GDB reports 3190 3191 Hardware watchpoint NUM: EXPR 3192 3193if it was able to set a hardware watchpoint. 3194 3195 Currently, the `awatch' and `rwatch' commands can only set hardware 3196watchpoints, because accesses to data that don't change the value of 3197the watched expression cannot be detected without examining every 3198instruction as it is being executed, and GDB does not do that 3199currently. If GDB finds that it is unable to set a hardware breakpoint 3200with the `awatch' or `rwatch' command, it will print a message like 3201this: 3202 3203 Expression cannot be implemented with read/access watchpoint. 3204 3205 Sometimes, GDB cannot set a hardware watchpoint because the data 3206type of the watched expression is wider than what a hardware watchpoint 3207on the target machine can handle. For example, some systems can only 3208watch regions that are up to 4 bytes wide; on such systems you cannot 3209set hardware watchpoints for an expression that yields a 3210double-precision floating-point number (which is typically 8 bytes 3211wide). As a work-around, it might be possible to break the large region 3212into a series of smaller ones and watch them with separate watchpoints. 3213 3214 If you set too many hardware watchpoints, GDB might be unable to 3215insert all of them when you resume the execution of your program. 3216Since the precise number of active watchpoints is unknown until such 3217time as the program is about to be resumed, GDB might not be able to 3218warn you about this when you set the watchpoints, and the warning will 3219be printed only when the program is resumed: 3220 3221 Hardware watchpoint NUM: Could not insert watchpoint 3222 3223If this happens, delete or disable some of the watchpoints. 3224 3225 Watching complex expressions that reference many variables can also 3226exhaust the resources available for hardware-assisted watchpoints. 3227That's because GDB needs to watch every variable in the expression with 3228separately allocated resources. 3229 3230 If you call a function interactively using `print' or `call', any 3231watchpoints you have set will be inactive until GDB reaches another 3232kind of breakpoint or the call completes. 3233 3234 GDB automatically deletes watchpoints that watch local (automatic) 3235variables, or expressions that involve such variables, when they go out 3236of scope, that is, when the execution leaves the block in which these 3237variables were defined. In particular, when the program being debugged 3238terminates, _all_ local variables go out of scope, and so only 3239watchpoints that watch global variables remain set. If you rerun the 3240program, you will need to set all such watchpoints again. One way of 3241doing that would be to set a code breakpoint at the entry to the `main' 3242function and when it breaks, set all the watchpoints. 3243 3244 In multi-threaded programs, watchpoints will detect changes to the 3245watched expression from every thread. 3246 3247 _Warning:_ In multi-threaded programs, software watchpoints have 3248 only limited usefulness. If GDB creates a software watchpoint, it 3249 can only watch the value of an expression _in a single thread_. 3250 If you are confident that the expression can only change due to 3251 the current thread's activity (and if you are also confident that 3252 no other thread can become current), then you can use software 3253 watchpoints as usual. However, GDB may not notice when a 3254 non-current thread's activity changes the expression. (Hardware 3255 watchpoints, in contrast, watch an expression in all threads.) 3256 3257 *Note set remote hardware-watchpoint-limit::. 3258 3259 3260File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints 3261 32625.1.3 Setting Catchpoints 3263------------------------- 3264 3265You can use "catchpoints" to cause the debugger to stop for certain 3266kinds of program events, such as C++ exceptions or the loading of a 3267shared library. Use the `catch' command to set a catchpoint. 3268 3269`catch EVENT' 3270 Stop when EVENT occurs. EVENT can be any of the following: 3271 `throw' 3272 The throwing of a C++ exception. 3273 3274 `catch' 3275 The catching of a C++ exception. 3276 3277 `exception' 3278 An Ada exception being raised. If an exception name is 3279 specified at the end of the command (eg `catch exception 3280 Program_Error'), the debugger will stop only when this 3281 specific exception is raised. Otherwise, the debugger stops 3282 execution when any Ada exception is raised. 3283 3284 When inserting an exception catchpoint on a user-defined 3285 exception whose name is identical to one of the exceptions 3286 defined by the language, the fully qualified name must be 3287 used as the exception name. Otherwise, GDB will assume that 3288 it should stop on the pre-defined exception rather than the 3289 user-defined one. For instance, assuming an exception called 3290 `Constraint_Error' is defined in package `Pck', then the 3291 command to use to catch such exceptions is `catch exception 3292 Pck.Constraint_Error'. 3293 3294 `exception unhandled' 3295 An exception that was raised but is not handled by the 3296 program. 3297 3298 `assert' 3299 A failed Ada assertion. 3300 3301 `exec' 3302 A call to `exec'. This is currently only available for HP-UX 3303 and GNU/Linux. 3304 3305 `syscall' 3306 `syscall [NAME | NUMBER] ...' 3307 A call to or return from a system call, a.k.a. "syscall". A 3308 syscall is a mechanism for application programs to request a 3309 service from the operating system (OS) or one of the OS 3310 system services. GDB can catch some or all of the syscalls 3311 issued by the debuggee, and show the related information for 3312 each syscall. If no argument is specified, calls to and 3313 returns from all system calls will be caught. 3314 3315 NAME can be any system call name that is valid for the 3316 underlying OS. Just what syscalls are valid depends on the 3317 OS. On GNU and Unix systems, you can find the full list of 3318 valid syscall names on `/usr/include/asm/unistd.h'. 3319 3320 Normally, GDB knows in advance which syscalls are valid for 3321 each OS, so you can use the GDB command-line completion 3322 facilities (*note command completion: Completion.) to list the 3323 available choices. 3324 3325 You may also specify the system call numerically. A syscall's 3326 number is the value passed to the OS's syscall dispatcher to 3327 identify the requested service. When you specify the syscall 3328 by its name, GDB uses its database of syscalls to convert the 3329 name into the corresponding numeric code, but using the 3330 number directly may be useful if GDB's database does not have 3331 the complete list of syscalls on your system (e.g., because 3332 GDB lags behind the OS upgrades). 3333 3334 The example below illustrates how this command works if you 3335 don't provide arguments to it: 3336 3337 (gdb) catch syscall 3338 Catchpoint 1 (syscall) 3339 (gdb) r 3340 Starting program: /tmp/catch-syscall 3341 3342 Catchpoint 1 (call to syscall 'close'), \ 3343 0xffffe424 in __kernel_vsyscall () 3344 (gdb) c 3345 Continuing. 3346 3347 Catchpoint 1 (returned from syscall 'close'), \ 3348 0xffffe424 in __kernel_vsyscall () 3349 (gdb) 3350 3351 Here is an example of catching a system call by name: 3352 3353 (gdb) catch syscall chroot 3354 Catchpoint 1 (syscall 'chroot' [61]) 3355 (gdb) r 3356 Starting program: /tmp/catch-syscall 3357 3358 Catchpoint 1 (call to syscall 'chroot'), \ 3359 0xffffe424 in __kernel_vsyscall () 3360 (gdb) c 3361 Continuing. 3362 3363 Catchpoint 1 (returned from syscall 'chroot'), \ 3364 0xffffe424 in __kernel_vsyscall () 3365 (gdb) 3366 3367 An example of specifying a system call numerically. In the 3368 case below, the syscall number has a corresponding entry in 3369 the XML file, so GDB finds its name and prints it: 3370 3371 (gdb) catch syscall 252 3372 Catchpoint 1 (syscall(s) 'exit_group') 3373 (gdb) r 3374 Starting program: /tmp/catch-syscall 3375 3376 Catchpoint 1 (call to syscall 'exit_group'), \ 3377 0xffffe424 in __kernel_vsyscall () 3378 (gdb) c 3379 Continuing. 3380 3381 Program exited normally. 3382 (gdb) 3383 3384 However, there can be situations when there is no 3385 corresponding name in XML file for that syscall number. In 3386 this case, GDB prints a warning message saying that it was 3387 not able to find the syscall name, but the catchpoint will be 3388 set anyway. See the example below: 3389 3390 (gdb) catch syscall 764 3391 warning: The number '764' does not represent a known syscall. 3392 Catchpoint 2 (syscall 764) 3393 (gdb) 3394 3395 If you configure GDB using the `--without-expat' option, it 3396 will not be able to display syscall names. Also, if your 3397 architecture does not have an XML file describing its system 3398 calls, you will not be able to see the syscall names. It is 3399 important to notice that these two features are used for 3400 accessing the syscall name database. In either case, you 3401 will see a warning like this: 3402 3403 (gdb) catch syscall 3404 warning: Could not open "syscalls/i386-linux.xml" 3405 warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. 3406 GDB will not be able to display syscall names. 3407 Catchpoint 1 (syscall) 3408 (gdb) 3409 3410 Of course, the file name will change depending on your 3411 architecture and system. 3412 3413 Still using the example above, you can also try to catch a 3414 syscall by its number. In this case, you would see something 3415 like: 3416 3417 (gdb) catch syscall 252 3418 Catchpoint 1 (syscall(s) 252) 3419 3420 Again, in this case GDB would not be able to display 3421 syscall's names. 3422 3423 `fork' 3424 A call to `fork'. This is currently only available for HP-UX 3425 and GNU/Linux. 3426 3427 `vfork' 3428 A call to `vfork'. This is currently only available for HP-UX 3429 and GNU/Linux. 3430 3431 3432`tcatch EVENT' 3433 Set a catchpoint that is enabled only for one stop. The 3434 catchpoint is automatically deleted after the first time the event 3435 is caught. 3436 3437 3438 Use the `info break' command to list the current catchpoints. 3439 3440 There are currently some limitations to C++ exception handling 3441(`catch throw' and `catch catch') in GDB: 3442 3443 * If you call a function interactively, GDB normally returns control 3444 to you when the function has finished executing. If the call 3445 raises an exception, however, the call may bypass the mechanism 3446 that returns control to you and cause your program either to abort 3447 or to simply continue running until it hits a breakpoint, catches 3448 a signal that GDB is listening for, or exits. This is the case 3449 even if you set a catchpoint for the exception; catchpoints on 3450 exceptions are disabled within interactive calls. 3451 3452 * You cannot raise an exception interactively. 3453 3454 * You cannot install an exception handler interactively. 3455 3456 Sometimes `catch' is not the best way to debug exception handling: 3457if you need to know exactly where an exception is raised, it is better 3458to stop _before_ the exception handler is called, since that way you 3459can see the stack before any unwinding takes place. If you set a 3460breakpoint in an exception handler instead, it may not be easy to find 3461out where the exception was raised. 3462 3463 To stop just before an exception handler is called, you need some 3464knowledge of the implementation. In the case of GNU C++, exceptions are 3465raised by calling a library function named `__raise_exception' which 3466has the following ANSI C interface: 3467 3468 /* ADDR is where the exception identifier is stored. 3469 ID is the exception identifier. */ 3470 void __raise_exception (void **addr, void *id); 3471 3472To make the debugger catch all exceptions before any stack unwinding 3473takes place, set a breakpoint on `__raise_exception' (*note 3474Breakpoints; Watchpoints; and Exceptions: Breakpoints.). 3475 3476 With a conditional breakpoint (*note Break Conditions: Conditions.) 3477that depends on the value of ID, you can stop your program when a 3478specific exception is raised. You can use multiple conditional 3479breakpoints to stop your program when any of a number of exceptions are 3480raised. 3481 3482 3483File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints 3484 34855.1.4 Deleting Breakpoints 3486-------------------------- 3487 3488It is often necessary to eliminate a breakpoint, watchpoint, or 3489catchpoint once it has done its job and you no longer want your program 3490to stop there. This is called "deleting" the breakpoint. A breakpoint 3491that has been deleted no longer exists; it is forgotten. 3492 3493 With the `clear' command you can delete breakpoints according to 3494where they are in your program. With the `delete' command you can 3495delete individual breakpoints, watchpoints, or catchpoints by specifying 3496their breakpoint numbers. 3497 3498 It is not necessary to delete a breakpoint to proceed past it. GDB 3499automatically ignores breakpoints on the first instruction to be 3500executed when you continue execution without changing the execution 3501address. 3502 3503`clear' 3504 Delete any breakpoints at the next instruction to be executed in 3505 the selected stack frame (*note Selecting a Frame: Selection.). 3506 When the innermost frame is selected, this is a good way to delete 3507 a breakpoint where your program just stopped. 3508 3509`clear LOCATION' 3510 Delete any breakpoints set at the specified LOCATION. *Note 3511 Specify Location::, for the various forms of LOCATION; the most 3512 useful ones are listed below: 3513 3514 `clear FUNCTION' 3515 `clear FILENAME:FUNCTION' 3516 Delete any breakpoints set at entry to the named FUNCTION. 3517 3518 `clear LINENUM' 3519 `clear FILENAME:LINENUM' 3520 Delete any breakpoints set at or within the code of the 3521 specified LINENUM of the specified FILENAME. 3522 3523`delete [breakpoints] [RANGE...]' 3524 Delete the breakpoints, watchpoints, or catchpoints of the 3525 breakpoint ranges specified as arguments. If no argument is 3526 specified, delete all breakpoints (GDB asks confirmation, unless 3527 you have `set confirm off'). You can abbreviate this command as 3528 `d'. 3529 3530 3531File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints 3532 35335.1.5 Disabling Breakpoints 3534--------------------------- 3535 3536Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 3537prefer to "disable" it. This makes the breakpoint inoperative as if it 3538had been deleted, but remembers the information on the breakpoint so 3539that you can "enable" it again later. 3540 3541 You disable and enable breakpoints, watchpoints, and catchpoints with 3542the `enable' and `disable' commands, optionally specifying one or more 3543breakpoint numbers as arguments. Use `info break' to print a list of 3544all breakpoints, watchpoints, and catchpoints if you do not know which 3545numbers to use. 3546 3547 Disabling and enabling a breakpoint that has multiple locations 3548affects all of its locations. 3549 3550 A breakpoint, watchpoint, or catchpoint can have any of four 3551different states of enablement: 3552 3553 * Enabled. The breakpoint stops your program. A breakpoint set 3554 with the `break' command starts out in this state. 3555 3556 * Disabled. The breakpoint has no effect on your program. 3557 3558 * Enabled once. The breakpoint stops your program, but then becomes 3559 disabled. 3560 3561 * Enabled for deletion. The breakpoint stops your program, but 3562 immediately after it does so it is deleted permanently. A 3563 breakpoint set with the `tbreak' command starts out in this state. 3564 3565 You can use the following commands to enable or disable breakpoints, 3566watchpoints, and catchpoints: 3567 3568`disable [breakpoints] [RANGE...]' 3569 Disable the specified breakpoints--or all breakpoints, if none are 3570 listed. A disabled breakpoint has no effect but is not forgotten. 3571 All options such as ignore-counts, conditions and commands are 3572 remembered in case the breakpoint is enabled again later. You may 3573 abbreviate `disable' as `dis'. 3574 3575`enable [breakpoints] [RANGE...]' 3576 Enable the specified breakpoints (or all defined breakpoints). 3577 They become effective once again in stopping your program. 3578 3579`enable [breakpoints] once RANGE...' 3580 Enable the specified breakpoints temporarily. GDB disables any of 3581 these breakpoints immediately after stopping your program. 3582 3583`enable [breakpoints] delete RANGE...' 3584 Enable the specified breakpoints to work once, then die. GDB 3585 deletes any of these breakpoints as soon as your program stops 3586 there. Breakpoints set by the `tbreak' command start out in this 3587 state. 3588 3589 Except for a breakpoint set with `tbreak' (*note Setting 3590Breakpoints: Set Breaks.), breakpoints that you set are initially 3591enabled; subsequently, they become disabled or enabled only when you 3592use one of the commands above. (The command `until' can set and delete 3593a breakpoint of its own, but it does not change the state of your other 3594breakpoints; see *note Continuing and Stepping: Continuing and 3595Stepping.) 3596 3597 3598File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints 3599 36005.1.6 Break Conditions 3601---------------------- 3602 3603The simplest sort of breakpoint breaks every time your program reaches a 3604specified place. You can also specify a "condition" for a breakpoint. 3605A condition is just a Boolean expression in your programming language 3606(*note Expressions: Expressions.). A breakpoint with a condition 3607evaluates the expression each time your program reaches it, and your 3608program stops only if the condition is _true_. 3609 3610 This is the converse of using assertions for program validation; in 3611that situation, you want to stop when the assertion is violated--that 3612is, when the condition is false. In C, if you want to test an 3613assertion expressed by the condition ASSERT, you should set the 3614condition `! ASSERT' on the appropriate breakpoint. 3615 3616 Conditions are also accepted for watchpoints; you may not need them, 3617since a watchpoint is inspecting the value of an expression anyhow--but 3618it might be simpler, say, to just set a watchpoint on a variable name, 3619and specify a condition that tests whether the new value is an 3620interesting one. 3621 3622 Break conditions can have side effects, and may even call functions 3623in your program. This can be useful, for example, to activate functions 3624that log program progress, or to use your own print functions to format 3625special data structures. The effects are completely predictable unless 3626there is another enabled breakpoint at the same address. (In that 3627case, GDB might see the other breakpoint first and stop your program 3628without checking the condition of this one.) Note that breakpoint 3629commands are usually more convenient and flexible than break conditions 3630for the purpose of performing side effects when a breakpoint is reached 3631(*note Breakpoint Command Lists: Break Commands.). 3632 3633 Break conditions can be specified when a breakpoint is set, by using 3634`if' in the arguments to the `break' command. *Note Setting 3635Breakpoints: Set Breaks. They can also be changed at any time with the 3636`condition' command. 3637 3638 You can also use the `if' keyword with the `watch' command. The 3639`catch' command does not recognize the `if' keyword; `condition' is the 3640only way to impose a further condition on a catchpoint. 3641 3642`condition BNUM EXPRESSION' 3643 Specify EXPRESSION as the break condition for breakpoint, 3644 watchpoint, or catchpoint number BNUM. After you set a condition, 3645 breakpoint BNUM stops your program only if the value of EXPRESSION 3646 is true (nonzero, in C). When you use `condition', GDB checks 3647 EXPRESSION immediately for syntactic correctness, and to determine 3648 whether symbols in it have referents in the context of your 3649 breakpoint. If EXPRESSION uses symbols not referenced in the 3650 context of the breakpoint, GDB prints an error message: 3651 3652 No symbol "foo" in current context. 3653 3654 GDB does not actually evaluate EXPRESSION at the time the 3655 `condition' command (or a command that sets a breakpoint with a 3656 condition, like `break if ...') is given, however. *Note 3657 Expressions: Expressions. 3658 3659`condition BNUM' 3660 Remove the condition from breakpoint number BNUM. It becomes an 3661 ordinary unconditional breakpoint. 3662 3663 A special case of a breakpoint condition is to stop only when the 3664breakpoint has been reached a certain number of times. This is so 3665useful that there is a special way to do it, using the "ignore count" 3666of the breakpoint. Every breakpoint has an ignore count, which is an 3667integer. Most of the time, the ignore count is zero, and therefore has 3668no effect. But if your program reaches a breakpoint whose ignore count 3669is positive, then instead of stopping, it just decrements the ignore 3670count by one and continues. As a result, if the ignore count value is 3671N, the breakpoint does not stop the next N times your program reaches 3672it. 3673 3674`ignore BNUM COUNT' 3675 Set the ignore count of breakpoint number BNUM to COUNT. The next 3676 COUNT times the breakpoint is reached, your program's execution 3677 does not stop; other than to decrement the ignore count, GDB takes 3678 no action. 3679 3680 To make the breakpoint stop the next time it is reached, specify a 3681 count of zero. 3682 3683 When you use `continue' to resume execution of your program from a 3684 breakpoint, you can specify an ignore count directly as an 3685 argument to `continue', rather than using `ignore'. *Note 3686 Continuing and Stepping: Continuing and Stepping. 3687 3688 If a breakpoint has a positive ignore count and a condition, the 3689 condition is not checked. Once the ignore count reaches zero, GDB 3690 resumes checking the condition. 3691 3692 You could achieve the effect of the ignore count with a condition 3693 such as `$foo-- <= 0' using a debugger convenience variable that 3694 is decremented each time. *Note Convenience Variables: 3695 Convenience Vars. 3696 3697 Ignore counts apply to breakpoints, watchpoints, and catchpoints. 3698 3699 3700File: gdb.info, Node: Break Commands, Next: Save Breakpoints, Prev: Conditions, Up: Breakpoints 3701 37025.1.7 Breakpoint Command Lists 3703------------------------------ 3704 3705You can give any breakpoint (or watchpoint or catchpoint) a series of 3706commands to execute when your program stops due to that breakpoint. For 3707example, you might want to print the values of certain expressions, or 3708enable other breakpoints. 3709 3710`commands [RANGE...]' 3711`... COMMAND-LIST ...' 3712`end' 3713 Specify a list of commands for the given breakpoints. The commands 3714 themselves appear on the following lines. Type a line containing 3715 just `end' to terminate the commands. 3716 3717 To remove all commands from a breakpoint, type `commands' and 3718 follow it immediately with `end'; that is, give no commands. 3719 3720 With no argument, `commands' refers to the last breakpoint, 3721 watchpoint, or catchpoint set (not to the breakpoint most recently 3722 encountered). If the most recent breakpoints were set with a 3723 single command, then the `commands' will apply to all the 3724 breakpoints set by that command. This applies to breakpoints set 3725 by `rbreak', and also applies when a single `break' command 3726 creates multiple breakpoints (*note Ambiguous Expressions: 3727 Ambiguous Expressions.). 3728 3729 Pressing <RET> as a means of repeating the last GDB command is 3730disabled within a COMMAND-LIST. 3731 3732 You can use breakpoint commands to start your program up again. 3733Simply use the `continue' command, or `step', or any other command that 3734resumes execution. 3735 3736 Any other commands in the command list, after a command that resumes 3737execution, are ignored. This is because any time you resume execution 3738(even with a simple `next' or `step'), you may encounter another 3739breakpoint--which could have its own command list, leading to 3740ambiguities about which list to execute. 3741 3742 If the first command you specify in a command list is `silent', the 3743usual message about stopping at a breakpoint is not printed. This may 3744be desirable for breakpoints that are to print a specific message and 3745then continue. If none of the remaining commands print anything, you 3746see no sign that the breakpoint was reached. `silent' is meaningful 3747only at the beginning of a breakpoint command list. 3748 3749 The commands `echo', `output', and `printf' allow you to print 3750precisely controlled output, and are often useful in silent 3751breakpoints. *Note Commands for Controlled Output: Output. 3752 3753 For example, here is how you could use breakpoint commands to print 3754the value of `x' at entry to `foo' whenever `x' is positive. 3755 3756 break foo if x>0 3757 commands 3758 silent 3759 printf "x is %d\n",x 3760 cont 3761 end 3762 3763 One application for breakpoint commands is to compensate for one bug 3764so you can test for another. Put a breakpoint just after the erroneous 3765line of code, give it a condition to detect the case in which something 3766erroneous has been done, and give it commands to assign correct values 3767to any variables that need them. End with the `continue' command so 3768that your program does not stop, and start with the `silent' command so 3769that no output is produced. Here is an example: 3770 3771 break 403 3772 commands 3773 silent 3774 set x = y + 4 3775 cont 3776 end 3777 3778 3779File: gdb.info, Node: Save Breakpoints, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints 3780 37815.1.8 How to save breakpoints to a file 3782--------------------------------------- 3783 3784To save breakpoint definitions to a file use the `save breakpoints' 3785command. 3786 3787`save breakpoints [FILENAME]' 3788 This command saves all current breakpoint definitions together with 3789 their commands and ignore counts, into a file `FILENAME' suitable 3790 for use in a later debugging session. This includes all types of 3791 breakpoints (breakpoints, watchpoints, catchpoints, tracepoints). 3792 To read the saved breakpoint definitions, use the `source' command 3793 (*note Command Files::). Note that watchpoints with expressions 3794 involving local variables may fail to be recreated because it may 3795 not be possible to access the context where the watchpoint is 3796 valid anymore. Because the saved breakpoint definitions are 3797 simply a sequence of GDB commands that recreate the breakpoints, 3798 you can edit the file in your favorite editing program, and remove 3799 the breakpoint definitions you're not interested in, or that can 3800 no longer be recreated. 3801 3802 3803File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Save Breakpoints, Up: Breakpoints 3804 38055.1.9 "Cannot insert breakpoints" 3806--------------------------------- 3807 3808If you request too many active hardware-assisted breakpoints and 3809watchpoints, you will see this error message: 3810 3811 Stopped; cannot insert breakpoints. 3812 You may have requested too many hardware breakpoints and watchpoints. 3813 3814This message is printed when you attempt to resume the program, since 3815only then GDB knows exactly how many hardware breakpoints and 3816watchpoints it needs to insert. 3817 3818 When this message is printed, you need to disable or remove some of 3819the hardware-assisted breakpoints and watchpoints, and then continue. 3820 3821 3822File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints 3823 38245.1.10 "Breakpoint address adjusted..." 3825--------------------------------------- 3826 3827Some processor architectures place constraints on the addresses at 3828which breakpoints may be placed. For architectures thus constrained, 3829GDB will attempt to adjust the breakpoint's address to comply with the 3830constraints dictated by the architecture. 3831 3832 One example of such an architecture is the Fujitsu FR-V. The FR-V is 3833a VLIW architecture in which a number of RISC-like instructions may be 3834bundled together for parallel execution. The FR-V architecture 3835constrains the location of a breakpoint instruction within such a 3836bundle to the instruction with the lowest address. GDB honors this 3837constraint by adjusting a breakpoint's address to the first in the 3838bundle. 3839 3840 It is not uncommon for optimized code to have bundles which contain 3841instructions from different source statements, thus it may happen that 3842a breakpoint's address will be adjusted from one source statement to 3843another. Since this adjustment may significantly alter GDB's 3844breakpoint related behavior from what the user expects, a warning is 3845printed when the breakpoint is first set and also when the breakpoint 3846is hit. 3847 3848 A warning like the one below is printed when setting a breakpoint 3849that's been subject to address adjustment: 3850 3851 warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. 3852 3853 Such warnings are printed both for user settable and GDB's internal 3854breakpoints. If you see one of these warnings, you should verify that 3855a breakpoint set at the adjusted address will have the desired affect. 3856If not, the breakpoint in question may be removed and other breakpoints 3857may be set which will have the desired behavior. E.g., it may be 3858sufficient to place the breakpoint at a later instruction. A 3859conditional breakpoint may also be useful in some cases to prevent the 3860breakpoint from triggering too often. 3861 3862 GDB will also issue a warning when stopping at one of these adjusted 3863breakpoints: 3864 3865 warning: Breakpoint 1 address previously adjusted from 0x00010414 3866 to 0x00010410. 3867 3868 When this warning is encountered, it may be too late to take remedial 3869action except in cases where the breakpoint is hit earlier or more 3870frequently than expected. 3871 3872 3873File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping 3874 38755.2 Continuing and Stepping 3876=========================== 3877 3878"Continuing" means resuming program execution until your program 3879completes normally. In contrast, "stepping" means executing just one 3880more "step" of your program, where "step" may mean either one line of 3881source code, or one machine instruction (depending on what particular 3882command you use). Either when continuing or when stepping, your 3883program may stop even sooner, due to a breakpoint or a signal. (If it 3884stops due to a signal, you may want to use `handle', or use `signal 0' 3885to resume execution. *Note Signals: Signals.) 3886 3887`continue [IGNORE-COUNT]' 3888`c [IGNORE-COUNT]' 3889`fg [IGNORE-COUNT]' 3890 Resume program execution, at the address where your program last 3891 stopped; any breakpoints set at that address are bypassed. The 3892 optional argument IGNORE-COUNT allows you to specify a further 3893 number of times to ignore a breakpoint at this location; its 3894 effect is like that of `ignore' (*note Break Conditions: 3895 Conditions.). 3896 3897 The argument IGNORE-COUNT is meaningful only when your program 3898 stopped due to a breakpoint. At other times, the argument to 3899 `continue' is ignored. 3900 3901 The synonyms `c' and `fg' (for "foreground", as the debugged 3902 program is deemed to be the foreground program) are provided 3903 purely for convenience, and have exactly the same behavior as 3904 `continue'. 3905 3906 To resume execution at a different place, you can use `return' 3907(*note Returning from a Function: Returning.) to go back to the calling 3908function; or `jump' (*note Continuing at a Different Address: Jumping.) 3909to go to an arbitrary location in your program. 3910 3911 A typical technique for using stepping is to set a breakpoint (*note 3912Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the 3913beginning of the function or the section of your program where a problem 3914is believed to lie, run your program until it stops at that breakpoint, 3915and then step through the suspect area, examining the variables that are 3916interesting, until you see the problem happen. 3917 3918`step' 3919 Continue running your program until control reaches a different 3920 source line, then stop it and return control to GDB. This command 3921 is abbreviated `s'. 3922 3923 _Warning:_ If you use the `step' command while control is 3924 within a function that was compiled without debugging 3925 information, execution proceeds until control reaches a 3926 function that does have debugging information. Likewise, it 3927 will not step into a function which is compiled without 3928 debugging information. To step through functions without 3929 debugging information, use the `stepi' command, described 3930 below. 3931 3932 The `step' command only stops at the first instruction of a source 3933 line. This prevents the multiple stops that could otherwise occur 3934 in `switch' statements, `for' loops, etc. `step' continues to 3935 stop if a function that has debugging information is called within 3936 the line. In other words, `step' _steps inside_ any functions 3937 called within the line. 3938 3939 Also, the `step' command only enters a function if there is line 3940 number information for the function. Otherwise it acts like the 3941 `next' command. This avoids problems when using `cc -gl' on MIPS 3942 machines. Previously, `step' entered subroutines if there was any 3943 debugging information about the routine. 3944 3945`step COUNT' 3946 Continue running as in `step', but do so COUNT times. If a 3947 breakpoint is reached, or a signal not related to stepping occurs 3948 before COUNT steps, stepping stops right away. 3949 3950`next [COUNT]' 3951 Continue to the next source line in the current (innermost) stack 3952 frame. This is similar to `step', but function calls that appear 3953 within the line of code are executed without stopping. Execution 3954 stops when control reaches a different line of code at the 3955 original stack level that was executing when you gave the `next' 3956 command. This command is abbreviated `n'. 3957 3958 An argument COUNT is a repeat count, as for `step'. 3959 3960 The `next' command only stops at the first instruction of a source 3961 line. This prevents multiple stops that could otherwise occur in 3962 `switch' statements, `for' loops, etc. 3963 3964`set step-mode' 3965`set step-mode on' 3966 The `set step-mode on' command causes the `step' command to stop 3967 at the first instruction of a function which contains no debug line 3968 information rather than stepping over it. 3969 3970 This is useful in cases where you may be interested in inspecting 3971 the machine instructions of a function which has no symbolic info 3972 and do not want GDB to automatically skip over this function. 3973 3974`set step-mode off' 3975 Causes the `step' command to step over any functions which 3976 contains no debug information. This is the default. 3977 3978`show step-mode' 3979 Show whether GDB will stop in or step over functions without 3980 source line debug information. 3981 3982`finish' 3983 Continue running until just after function in the selected stack 3984 frame returns. Print the returned value (if any). This command 3985 can be abbreviated as `fin'. 3986 3987 Contrast this with the `return' command (*note Returning from a 3988 Function: Returning.). 3989 3990`until' 3991`u' 3992 Continue running until a source line past the current line, in the 3993 current stack frame, is reached. This command is used to avoid 3994 single stepping through a loop more than once. It is like the 3995 `next' command, except that when `until' encounters a jump, it 3996 automatically continues execution until the program counter is 3997 greater than the address of the jump. 3998 3999 This means that when you reach the end of a loop after single 4000 stepping though it, `until' makes your program continue execution 4001 until it exits the loop. In contrast, a `next' command at the end 4002 of a loop simply steps back to the beginning of the loop, which 4003 forces you to step through the next iteration. 4004 4005 `until' always stops your program if it attempts to exit the 4006 current stack frame. 4007 4008 `until' may produce somewhat counterintuitive results if the order 4009 of machine code does not match the order of the source lines. For 4010 example, in the following excerpt from a debugging session, the `f' 4011 (`frame') command shows that execution is stopped at line `206'; 4012 yet when we use `until', we get to line `195': 4013 4014 (gdb) f 4015 #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 4016 206 expand_input(); 4017 (gdb) until 4018 195 for ( ; argc > 0; NEXTARG) { 4019 4020 This happened because, for execution efficiency, the compiler had 4021 generated code for the loop closure test at the end, rather than 4022 the start, of the loop--even though the test in a C `for'-loop is 4023 written before the body of the loop. The `until' command appeared 4024 to step back to the beginning of the loop when it advanced to this 4025 expression; however, it has not really gone to an earlier 4026 statement--not in terms of the actual machine code. 4027 4028 `until' with no argument works by means of single instruction 4029 stepping, and hence is slower than `until' with an argument. 4030 4031`until LOCATION' 4032`u LOCATION' 4033 Continue running your program until either the specified location 4034 is reached, or the current stack frame returns. LOCATION is any of 4035 the forms described in *note Specify Location::. This form of the 4036 command uses temporary breakpoints, and hence is quicker than 4037 `until' without an argument. The specified location is actually 4038 reached only if it is in the current frame. This implies that 4039 `until' can be used to skip over recursive function invocations. 4040 For instance in the code below, if the current location is line 4041 `96', issuing `until 99' will execute the program up to line `99' 4042 in the same invocation of factorial, i.e., after the inner 4043 invocations have returned. 4044 4045 94 int factorial (int value) 4046 95 { 4047 96 if (value > 1) { 4048 97 value *= factorial (value - 1); 4049 98 } 4050 99 return (value); 4051 100 } 4052 4053`advance LOCATION' 4054 Continue running the program up to the given LOCATION. An 4055 argument is required, which should be of one of the forms 4056 described in *note Specify Location::. Execution will also stop 4057 upon exit from the current stack frame. This command is similar 4058 to `until', but `advance' will not skip over recursive function 4059 calls, and the target location doesn't have to be in the same 4060 frame as the current one. 4061 4062`stepi' 4063`stepi ARG' 4064`si' 4065 Execute one machine instruction, then stop and return to the 4066 debugger. 4067 4068 It is often useful to do `display/i $pc' when stepping by machine 4069 instructions. This makes GDB automatically display the next 4070 instruction to be executed, each time your program stops. *Note 4071 Automatic Display: Auto Display. 4072 4073 An argument is a repeat count, as in `step'. 4074 4075`nexti' 4076`nexti ARG' 4077`ni' 4078 Execute one machine instruction, but if it is a function call, 4079 proceed until the function returns. 4080 4081 An argument is a repeat count, as in `next'. 4082 4083 4084File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping 4085 40865.3 Signals 4087=========== 4088 4089A signal is an asynchronous event that can happen in a program. The 4090operating system defines the possible kinds of signals, and gives each 4091kind a name and a number. For example, in Unix `SIGINT' is the signal 4092a program gets when you type an interrupt character (often `Ctrl-c'); 4093`SIGSEGV' is the signal a program gets from referencing a place in 4094memory far away from all the areas in use; `SIGALRM' occurs when the 4095alarm clock timer goes off (which happens only if your program has 4096requested an alarm). 4097 4098 Some signals, including `SIGALRM', are a normal part of the 4099functioning of your program. Others, such as `SIGSEGV', indicate 4100errors; these signals are "fatal" (they kill your program immediately) 4101if the program has not specified in advance some other way to handle 4102the signal. `SIGINT' does not indicate an error in your program, but 4103it is normally fatal so it can carry out the purpose of the interrupt: 4104to kill the program. 4105 4106 GDB has the ability to detect any occurrence of a signal in your 4107program. You can tell GDB in advance what to do for each kind of 4108signal. 4109 4110 Normally, GDB is set up to let the non-erroneous signals like 4111`SIGALRM' be silently passed to your program (so as not to interfere 4112with their role in the program's functioning) but to stop your program 4113immediately whenever an error signal happens. You can change these 4114settings with the `handle' command. 4115 4116`info signals' 4117`info handle' 4118 Print a table of all the kinds of signals and how GDB has been 4119 told to handle each one. You can use this to see the signal 4120 numbers of all the defined types of signals. 4121 4122`info signals SIG' 4123 Similar, but print information only about the specified signal 4124 number. 4125 4126 `info handle' is an alias for `info signals'. 4127 4128`handle SIGNAL [KEYWORDS...]' 4129 Change the way GDB handles signal SIGNAL. SIGNAL can be the 4130 number of a signal or its name (with or without the `SIG' at the 4131 beginning); a list of signal numbers of the form `LOW-HIGH'; or 4132 the word `all', meaning all the known signals. Optional arguments 4133 KEYWORDS, described below, say what change to make. 4134 4135 The keywords allowed by the `handle' command can be abbreviated. 4136Their full names are: 4137 4138`nostop' 4139 GDB should not stop your program when this signal happens. It may 4140 still print a message telling you that the signal has come in. 4141 4142`stop' 4143 GDB should stop your program when this signal happens. This 4144 implies the `print' keyword as well. 4145 4146`print' 4147 GDB should print a message when this signal happens. 4148 4149`noprint' 4150 GDB should not mention the occurrence of the signal at all. This 4151 implies the `nostop' keyword as well. 4152 4153`pass' 4154`noignore' 4155 GDB should allow your program to see this signal; your program can 4156 handle the signal, or else it may terminate if the signal is fatal 4157 and not handled. `pass' and `noignore' are synonyms. 4158 4159`nopass' 4160`ignore' 4161 GDB should not allow your program to see this signal. `nopass' 4162 and `ignore' are synonyms. 4163 4164 When a signal stops your program, the signal is not visible to the 4165program until you continue. Your program sees the signal then, if 4166`pass' is in effect for the signal in question _at that time_. In 4167other words, after GDB reports a signal, you can use the `handle' 4168command with `pass' or `nopass' to control whether your program sees 4169that signal when you continue. 4170 4171 The default is set to `nostop', `noprint', `pass' for non-erroneous 4172signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop', 4173`print', `pass' for the erroneous signals. 4174 4175 You can also use the `signal' command to prevent your program from 4176seeing a signal, or cause it to see a signal it normally would not see, 4177or to give it any signal at any time. For example, if your program 4178stopped due to some sort of memory reference error, you might store 4179correct values into the erroneous variables and continue, hoping to see 4180more execution; but your program would probably terminate immediately as 4181a result of the fatal signal once it saw the signal. To prevent this, 4182you can continue with `signal 0'. *Note Giving your Program a Signal: 4183Signaling. 4184 4185 On some targets, GDB can inspect extra signal information associated 4186with the intercepted signal, before it is actually delivered to the 4187program being debugged. This information is exported by the 4188convenience variable `$_siginfo', and consists of data that is passed 4189by the kernel to the signal handler at the time of the receipt of a 4190signal. The data type of the information itself is target dependent. 4191You can see the data type using the `ptype $_siginfo' command. On Unix 4192systems, it typically corresponds to the standard `siginfo_t' type, as 4193defined in the `signal.h' system header. 4194 4195 Here's an example, on a GNU/Linux system, printing the stray 4196referenced address that raised a segmentation fault. 4197 4198 (gdb) continue 4199 Program received signal SIGSEGV, Segmentation fault. 4200 0x0000000000400766 in main () 4201 69 *(int *)p = 0; 4202 (gdb) ptype $_siginfo 4203 type = struct { 4204 int si_signo; 4205 int si_errno; 4206 int si_code; 4207 union { 4208 int _pad[28]; 4209 struct {...} _kill; 4210 struct {...} _timer; 4211 struct {...} _rt; 4212 struct {...} _sigchld; 4213 struct {...} _sigfault; 4214 struct {...} _sigpoll; 4215 } _sifields; 4216 } 4217 (gdb) ptype $_siginfo._sifields._sigfault 4218 type = struct { 4219 void *si_addr; 4220 } 4221 (gdb) p $_siginfo._sifields._sigfault.si_addr 4222 $1 = (void *) 0x7ffff7ff7000 4223 4224 Depending on target support, `$_siginfo' may also be writable. 4225 4226 4227File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping 4228 42295.4 Stopping and Starting Multi-thread Programs 4230=============================================== 4231 4232GDB supports debugging programs with multiple threads (*note Debugging 4233Programs with Multiple Threads: Threads.). There are two modes of 4234controlling execution of your program within the debugger. In the 4235default mode, referred to as "all-stop mode", when any thread in your 4236program stops (for example, at a breakpoint or while being stepped), 4237all other threads in the program are also stopped by GDB. On some 4238targets, GDB also supports "non-stop mode", in which other threads can 4239continue to run freely while you examine the stopped thread in the 4240debugger. 4241 4242* Menu: 4243 4244* All-Stop Mode:: All threads stop when GDB takes control 4245* Non-Stop Mode:: Other threads continue to execute 4246* Background Execution:: Running your program asynchronously 4247* Thread-Specific Breakpoints:: Controlling breakpoints 4248* Interrupted System Calls:: GDB may interfere with system calls 4249* Observer Mode:: GDB does not alter program behavior 4250 4251 4252File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops 4253 42545.4.1 All-Stop Mode 4255------------------- 4256 4257In all-stop mode, whenever your program stops under GDB for any reason, 4258_all_ threads of execution stop, not just the current thread. This 4259allows you to examine the overall state of the program, including 4260switching between threads, without worrying that things may change 4261underfoot. 4262 4263 Conversely, whenever you restart the program, _all_ threads start 4264executing. _This is true even when single-stepping_ with commands like 4265`step' or `next'. 4266 4267 In particular, GDB cannot single-step all threads in lockstep. 4268Since thread scheduling is up to your debugging target's operating 4269system (not controlled by GDB), other threads may execute more than one 4270statement while the current thread completes a single step. Moreover, 4271in general other threads stop in the middle of a statement, rather than 4272at a clean statement boundary, when the program stops. 4273 4274 You might even find your program stopped in another thread after 4275continuing or even single-stepping. This happens whenever some other 4276thread runs into a breakpoint, a signal, or an exception before the 4277first thread completes whatever you requested. 4278 4279 Whenever GDB stops your program, due to a breakpoint or a signal, it 4280automatically selects the thread where that breakpoint or signal 4281happened. GDB alerts you to the context switch with a message such as 4282`[Switching to Thread N]' to identify the thread. 4283 4284 On some OSes, you can modify GDB's default behavior by locking the 4285OS scheduler to allow only a single thread to run. 4286 4287`set scheduler-locking MODE' 4288 Set the scheduler locking mode. If it is `off', then there is no 4289 locking and any thread may run at any time. If `on', then only the 4290 current thread may run when the inferior is resumed. The `step' 4291 mode optimizes for single-stepping; it prevents other threads from 4292 preempting the current thread while you are stepping, so that the 4293 focus of debugging does not change unexpectedly. Other threads 4294 only rarely (or never) get a chance to run when you step. They 4295 are more likely to run when you `next' over a function call, and 4296 they are completely free to run when you use commands like 4297 `continue', `until', or `finish'. However, unless another thread 4298 hits a breakpoint during its timeslice, GDB does not change the 4299 current thread away from the thread that you are debugging. 4300 4301`show scheduler-locking' 4302 Display the current scheduler locking mode. 4303 4304 By default, when you issue one of the execution commands such as 4305`continue', `next' or `step', GDB allows only threads of the current 4306inferior to run. For example, if GDB is attached to two inferiors, 4307each with two threads, the `continue' command resumes only the two 4308threads of the current inferior. This is useful, for example, when you 4309debug a program that forks and you want to hold the parent stopped (so 4310that, for instance, it doesn't run to exit), while you debug the child. 4311In other situations, you may not be interested in inspecting the 4312current state of any of the processes GDB is attached to, and you may 4313want to resume them all until some breakpoint is hit. In the latter 4314case, you can instruct GDB to allow all threads of all the inferiors to 4315run with the `set schedule-multiple' command. 4316 4317`set schedule-multiple' 4318 Set the mode for allowing threads of multiple processes to be 4319 resumed when an execution command is issued. When `on', all 4320 threads of all processes are allowed to run. When `off', only the 4321 threads of the current process are resumed. The default is `off'. 4322 The `scheduler-locking' mode takes precedence when set to `on', or 4323 while you are stepping and set to `step'. 4324 4325`show schedule-multiple' 4326 Display the current mode for resuming the execution of threads of 4327 multiple processes. 4328 4329 4330File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops 4331 43325.4.2 Non-Stop Mode 4333------------------- 4334 4335For some multi-threaded targets, GDB supports an optional mode of 4336operation in which you can examine stopped program threads in the 4337debugger while other threads continue to execute freely. This 4338minimizes intrusion when debugging live systems, such as programs where 4339some threads have real-time constraints or must continue to respond to 4340external events. This is referred to as "non-stop" mode. 4341 4342 In non-stop mode, when a thread stops to report a debugging event, 4343_only_ that thread is stopped; GDB does not stop other threads as well, 4344in contrast to the all-stop mode behavior. Additionally, execution 4345commands such as `continue' and `step' apply by default only to the 4346current thread in non-stop mode, rather than all threads as in all-stop 4347mode. This allows you to control threads explicitly in ways that are 4348not possible in all-stop mode -- for example, stepping one thread while 4349allowing others to run freely, stepping one thread while holding all 4350others stopped, or stepping several threads independently and 4351simultaneously. 4352 4353 To enter non-stop mode, use this sequence of commands before you run 4354or attach to your program: 4355 4356 # Enable the async interface. 4357 set target-async 1 4358 4359 # If using the CLI, pagination breaks non-stop. 4360 set pagination off 4361 4362 # Finally, turn it on! 4363 set non-stop on 4364 4365 You can use these commands to manipulate the non-stop mode setting: 4366 4367`set non-stop on' 4368 Enable selection of non-stop mode. 4369 4370`set non-stop off' 4371 Disable selection of non-stop mode. 4372 4373`show non-stop' 4374 Show the current non-stop enablement setting. 4375 4376 Note these commands only reflect whether non-stop mode is enabled, 4377not whether the currently-executing program is being run in non-stop 4378mode. In particular, the `set non-stop' preference is only consulted 4379when GDB starts or connects to the target program, and it is generally 4380not possible to switch modes once debugging has started. Furthermore, 4381since not all targets support non-stop mode, even when you have enabled 4382non-stop mode, GDB may still fall back to all-stop operation by default. 4383 4384 In non-stop mode, all execution commands apply only to the current 4385thread by default. That is, `continue' only continues one thread. To 4386continue all threads, issue `continue -a' or `c -a'. 4387 4388 You can use GDB's background execution commands (*note Background 4389Execution::) to run some threads in the background while you continue 4390to examine or step others from GDB. The MI execution commands (*note 4391GDB/MI Program Execution::) are always executed asynchronously in 4392non-stop mode. 4393 4394 Suspending execution is done with the `interrupt' command when 4395running in the background, or `Ctrl-c' during foreground execution. In 4396all-stop mode, this stops the whole process; but in non-stop mode the 4397interrupt applies only to the current thread. To stop the whole 4398program, use `interrupt -a'. 4399 4400 Other execution commands do not currently support the `-a' option. 4401 4402 In non-stop mode, when a thread stops, GDB doesn't automatically make 4403that thread current, as it does in all-stop mode. This is because the 4404thread stop notifications are asynchronous with respect to GDB's 4405command interpreter, and it would be confusing if GDB unexpectedly 4406changed to a different thread just as you entered a command to operate 4407on the previously current thread. 4408 4409 4410File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops 4411 44125.4.3 Background Execution 4413-------------------------- 4414 4415GDB's execution commands have two variants: the normal foreground 4416(synchronous) behavior, and a background (asynchronous) behavior. In 4417foreground execution, GDB waits for the program to report that some 4418thread has stopped before prompting for another command. In background 4419execution, GDB immediately gives a command prompt so that you can issue 4420other commands while your program runs. 4421 4422 You need to explicitly enable asynchronous mode before you can use 4423background execution commands. You can use these commands to 4424manipulate the asynchronous mode setting: 4425 4426`set target-async on' 4427 Enable asynchronous mode. 4428 4429`set target-async off' 4430 Disable asynchronous mode. 4431 4432`show target-async' 4433 Show the current target-async setting. 4434 4435 If the target doesn't support async mode, GDB issues an error 4436message if you attempt to use the background execution commands. 4437 4438 To specify background execution, add a `&' to the command. For 4439example, the background form of the `continue' command is `continue&', 4440or just `c&'. The execution commands that accept background execution 4441are: 4442 4443`run' 4444 *Note Starting your Program: Starting. 4445 4446`attach' 4447 *Note Debugging an Already-running Process: Attach. 4448 4449`step' 4450 *Note step: Continuing and Stepping. 4451 4452`stepi' 4453 *Note stepi: Continuing and Stepping. 4454 4455`next' 4456 *Note next: Continuing and Stepping. 4457 4458`nexti' 4459 *Note nexti: Continuing and Stepping. 4460 4461`continue' 4462 *Note continue: Continuing and Stepping. 4463 4464`finish' 4465 *Note finish: Continuing and Stepping. 4466 4467`until' 4468 *Note until: Continuing and Stepping. 4469 4470 4471 Background execution is especially useful in conjunction with 4472non-stop mode for debugging programs with multiple threads; see *note 4473Non-Stop Mode::. However, you can also use these commands in the 4474normal all-stop mode with the restriction that you cannot issue another 4475execution command until the previous one finishes. Examples of 4476commands that are valid in all-stop mode while the program is running 4477include `help' and `info break'. 4478 4479 You can interrupt your program while it is running in the background 4480by using the `interrupt' command. 4481 4482`interrupt' 4483`interrupt -a' 4484 Suspend execution of the running program. In all-stop mode, 4485 `interrupt' stops the whole process, but in non-stop mode, it stops 4486 only the current thread. To stop the whole program in non-stop 4487 mode, use `interrupt -a'. 4488 4489 4490File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops 4491 44925.4.4 Thread-Specific Breakpoints 4493--------------------------------- 4494 4495When your program has multiple threads (*note Debugging Programs with 4496Multiple Threads: Threads.), you can choose whether to set breakpoints 4497on all threads, or on a particular thread. 4498 4499`break LINESPEC thread THREADNO' 4500`break LINESPEC thread THREADNO if ...' 4501 LINESPEC specifies source lines; there are several ways of writing 4502 them (*note Specify Location::), but the effect is always to 4503 specify some source line. 4504 4505 Use the qualifier `thread THREADNO' with a breakpoint command to 4506 specify that you only want GDB to stop the program when a 4507 particular thread reaches this breakpoint. THREADNO is one of the 4508 numeric thread identifiers assigned by GDB, shown in the first 4509 column of the `info threads' display. 4510 4511 If you do not specify `thread THREADNO' when you set a breakpoint, 4512 the breakpoint applies to _all_ threads of your program. 4513 4514 You can use the `thread' qualifier on conditional breakpoints as 4515 well; in this case, place `thread THREADNO' before or after the 4516 breakpoint condition, like this: 4517 4518 (gdb) break frik.c:13 thread 28 if bartab > lim 4519 4520 4521 4522File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops 4523 45245.4.5 Interrupted System Calls 4525------------------------------ 4526 4527There is an unfortunate side effect when using GDB to debug 4528multi-threaded programs. If one thread stops for a breakpoint, or for 4529some other reason, and another thread is blocked in a system call, then 4530the system call may return prematurely. This is a consequence of the 4531interaction between multiple threads and the signals that GDB uses to 4532implement breakpoints and other events that stop execution. 4533 4534 To handle this problem, your program should check the return value of 4535each system call and react appropriately. This is good programming 4536style anyways. 4537 4538 For example, do not write code like this: 4539 4540 sleep (10); 4541 4542 The call to `sleep' will return early if a different thread stops at 4543a breakpoint or for some other reason. 4544 4545 Instead, write this: 4546 4547 int unslept = 10; 4548 while (unslept > 0) 4549 unslept = sleep (unslept); 4550 4551 A system call is allowed to return early, so the system is still 4552conforming to its specification. But GDB does cause your 4553multi-threaded program to behave differently than it would without GDB. 4554 4555 Also, GDB uses internal breakpoints in the thread library to monitor 4556certain events such as thread creation and thread destruction. When 4557such an event happens, a system call in another thread may return 4558prematurely, even though your program does not appear to stop. 4559 4560 4561File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops 4562 45635.4.6 Observer Mode 4564------------------- 4565 4566If you want to build on non-stop mode and observe program behavior 4567without any chance of disruption by GDB, you can set variables to 4568disable all of the debugger's attempts to modify state, whether by 4569writing memory, inserting breakpoints, etc. These operate at a low 4570level, intercepting operations from all commands. 4571 4572 When all of these are set to `off', then GDB is said to be "observer 4573mode". As a convenience, the variable `observer' can be set to disable 4574these, plus enable non-stop mode. 4575 4576 Note that GDB will not prevent you from making nonsensical 4577combinations of these settings. For instance, if you have enabled 4578`may-insert-breakpoints' but disabled `may-write-memory', then 4579breakpoints that work by writing trap instructions into the code stream 4580will still not be able to be placed. 4581 4582`set observer on' 4583`set observer off' 4584 When set to `on', this disables all the permission variables below 4585 (except for `insert-fast-tracepoints'), plus enables non-stop 4586 debugging. Setting this to `off' switches back to normal 4587 debugging, though remaining in non-stop mode. 4588 4589`show observer' 4590 Show whether observer mode is on or off. 4591 4592`set may-write-registers on' 4593`set may-write-registers off' 4594 This controls whether GDB will attempt to alter the values of 4595 registers, such as with assignment expressions in `print', or the 4596 `jump' command. It defaults to `on'. 4597 4598`show may-write-registers' 4599 Show the current permission to write registers. 4600 4601`set may-write-memory on' 4602`set may-write-memory off' 4603 This controls whether GDB will attempt to alter the contents of 4604 memory, such as with assignment expressions in `print'. It 4605 defaults to `on'. 4606 4607`show may-write-memory' 4608 Show the current permission to write memory. 4609 4610`set may-insert-breakpoints on' 4611`set may-insert-breakpoints off' 4612 This controls whether GDB will attempt to insert breakpoints. 4613 This affects all breakpoints, including internal breakpoints 4614 defined by GDB. It defaults to `on'. 4615 4616`show may-insert-breakpoints' 4617 Show the current permission to insert breakpoints. 4618 4619`set may-insert-tracepoints on' 4620`set may-insert-tracepoints off' 4621 This controls whether GDB will attempt to insert (regular) 4622 tracepoints at the beginning of a tracing experiment. It affects 4623 only non-fast tracepoints, fast tracepoints being under the 4624 control of `may-insert-fast-tracepoints'. It defaults to `on'. 4625 4626`show may-insert-tracepoints' 4627 Show the current permission to insert tracepoints. 4628 4629`set may-insert-fast-tracepoints on' 4630`set may-insert-fast-tracepoints off' 4631 This controls whether GDB will attempt to insert fast tracepoints 4632 at the beginning of a tracing experiment. It affects only fast 4633 tracepoints, regular (non-fast) tracepoints being under the 4634 control of `may-insert-tracepoints'. It defaults to `on'. 4635 4636`show may-insert-fast-tracepoints' 4637 Show the current permission to insert fast tracepoints. 4638 4639`set may-interrupt on' 4640`set may-interrupt off' 4641 This controls whether GDB will attempt to interrupt or stop 4642 program execution. When this variable is `off', the `interrupt' 4643 command will have no effect, nor will `Ctrl-c'. It defaults to 4644 `on'. 4645 4646`show may-interrupt' 4647 Show the current permission to interrupt or stop the program. 4648 4649 4650 4651File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top 4652 46536 Running programs backward 4654*************************** 4655 4656When you are debugging a program, it is not unusual to realize that you 4657have gone too far, and some event of interest has already happened. If 4658the target environment supports it, GDB can allow you to "rewind" the 4659program by running it backward. 4660 4661 A target environment that supports reverse execution should be able 4662to "undo" the changes in machine state that have taken place as the 4663program was executing normally. Variables, registers etc. should 4664revert to their previous values. Obviously this requires a great deal 4665of sophistication on the part of the target environment; not all target 4666environments can support reverse execution. 4667 4668 When a program is executed in reverse, the instructions that have 4669most recently been executed are "un-executed", in reverse order. The 4670program counter runs backward, following the previous thread of 4671execution in reverse. As each instruction is "un-executed", the values 4672of memory and/or registers that were changed by that instruction are 4673reverted to their previous states. After executing a piece of source 4674code in reverse, all side effects of that code should be "undone", and 4675all variables should be returned to their prior values(1). 4676 4677 If you are debugging in a target environment that supports reverse 4678execution, GDB provides the following commands. 4679 4680`reverse-continue [IGNORE-COUNT]' 4681`rc [IGNORE-COUNT]' 4682 Beginning at the point where your program last stopped, start 4683 executing in reverse. Reverse execution will stop for breakpoints 4684 and synchronous exceptions (signals), just like normal execution. 4685 Behavior of asynchronous signals depends on the target environment. 4686 4687`reverse-step [COUNT]' 4688 Run the program backward until control reaches the start of a 4689 different source line; then stop it, and return control to GDB. 4690 4691 Like the `step' command, `reverse-step' will only stop at the 4692 beginning of a source line. It "un-executes" the previously 4693 executed source line. If the previous source line included calls 4694 to debuggable functions, `reverse-step' will step (backward) into 4695 the called function, stopping at the beginning of the _last_ 4696 statement in the called function (typically a return statement). 4697 4698 Also, as with the `step' command, if non-debuggable functions are 4699 called, `reverse-step' will run thru them backward without 4700 stopping. 4701 4702`reverse-stepi [COUNT]' 4703 Reverse-execute one machine instruction. Note that the instruction 4704 to be reverse-executed is _not_ the one pointed to by the program 4705 counter, but the instruction executed prior to that one. For 4706 instance, if the last instruction was a jump, `reverse-stepi' will 4707 take you back from the destination of the jump to the jump 4708 instruction itself. 4709 4710`reverse-next [COUNT]' 4711 Run backward to the beginning of the previous line executed in the 4712 current (innermost) stack frame. If the line contains function 4713 calls, they will be "un-executed" without stopping. Starting from 4714 the first line of a function, `reverse-next' will take you back to 4715 the caller of that function, _before_ the function was called, 4716 just as the normal `next' command would take you from the last 4717 line of a function back to its return to its caller (2). 4718 4719`reverse-nexti [COUNT]' 4720 Like `nexti', `reverse-nexti' executes a single instruction in 4721 reverse, except that called functions are "un-executed" atomically. 4722 That is, if the previously executed instruction was a return from 4723 another function, `reverse-nexti' will continue to execute in 4724 reverse until the call to that function (from the current stack 4725 frame) is reached. 4726 4727`reverse-finish' 4728 Just as the `finish' command takes you to the point where the 4729 current function returns, `reverse-finish' takes you to the point 4730 where it was called. Instead of ending up at the end of the 4731 current function invocation, you end up at the beginning. 4732 4733`set exec-direction' 4734 Set the direction of target execution. 4735 4736`set exec-direction reverse' 4737 GDB will perform all execution commands in reverse, until the 4738 exec-direction mode is changed to "forward". Affected commands 4739 include `step, stepi, next, nexti, continue, and finish'. The 4740 `return' command cannot be used in reverse mode. 4741 4742`set exec-direction forward' 4743 GDB will perform all execution commands in the normal fashion. 4744 This is the default. 4745 4746 ---------- Footnotes ---------- 4747 4748 (1) Note that some side effects are easier to undo than others. For 4749instance, memory and registers are relatively easy, but device I/O is 4750hard. Some targets may be able undo things like device I/O, and some 4751may not. 4752 4753 The contract between GDB and the reverse executing target requires 4754only that the target do something reasonable when GDB tells it to 4755execute backwards, and then report the results back to GDB. Whatever 4756the target reports back to GDB, GDB will report back to the user. GDB 4757assumes that the memory and registers that the target reports are in a 4758consistant state, but GDB accepts whatever it is given. 4759 4760 (2) Unless the code is too heavily optimized. 4761 4762 4763File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top 4764 47657 Recording Inferior's Execution and Replaying It 4766************************************************* 4767 4768On some platforms, GDB provides a special "process record and replay" 4769target that can record a log of the process execution, and replay it 4770later with both forward and reverse execution commands. 4771 4772 When this target is in use, if the execution log includes the record 4773for the next instruction, GDB will debug in "replay mode". In the 4774replay mode, the inferior does not really execute code instructions. 4775Instead, all the events that normally happen during code execution are 4776taken from the execution log. While code is not really executed in 4777replay mode, the values of registers (including the program counter 4778register) and the memory of the inferior are still changed as they 4779normally would. Their contents are taken from the execution log. 4780 4781 If the record for the next instruction is not in the execution log, 4782GDB will debug in "record mode". In this mode, the inferior executes 4783normally, and GDB records the execution log for future replay. 4784 4785 The process record and replay target supports reverse execution 4786(*note Reverse Execution::), even if the platform on which the inferior 4787runs does not. However, the reverse execution is limited in this case 4788by the range of the instructions recorded in the execution log. In 4789other words, reverse execution on platforms that don't support it 4790directly can only be done in the replay mode. 4791 4792 When debugging in the reverse direction, GDB will work in replay 4793mode as long as the execution log includes the record for the previous 4794instruction; otherwise, it will work in record mode, if the platform 4795supports reverse execution, or stop if not. 4796 4797 For architecture environments that support process record and replay, 4798GDB provides the following commands: 4799 4800`target record' 4801 This command starts the process record and replay target. The 4802 process record and replay target can only debug a process that is 4803 already running. Therefore, you need first to start the process 4804 with the `run' or `start' commands, and then start the recording 4805 with the `target record' command. 4806 4807 Both `record' and `rec' are aliases of `target record'. 4808 4809 Displaced stepping (*note displaced stepping: Maintenance 4810 Commands.) will be automatically disabled when process record and 4811 replay target is started. That's because the process record and 4812 replay target doesn't support displaced stepping. 4813 4814 If the inferior is in the non-stop mode (*note Non-Stop Mode::) or 4815 in the asynchronous execution mode (*note Background Execution::), 4816 the process record and replay target cannot be started because it 4817 doesn't support these two modes. 4818 4819`record stop' 4820 Stop the process record and replay target. When process record and 4821 replay target stops, the entire execution log will be deleted and 4822 the inferior will either be terminated, or will remain in its 4823 final state. 4824 4825 When you stop the process record and replay target in record mode 4826 (at the end of the execution log), the inferior will be stopped at 4827 the next instruction that would have been recorded. In other 4828 words, if you record for a while and then stop recording, the 4829 inferior process will be left in the same state as if the 4830 recording never happened. 4831 4832 On the other hand, if the process record and replay target is 4833 stopped while in replay mode (that is, not at the end of the 4834 execution log, but at some earlier point), the inferior process 4835 will become "live" at that earlier state, and it will then be 4836 possible to continue the usual "live" debugging of the process 4837 from that state. 4838 4839 When the inferior process exits, or GDB detaches from it, process 4840 record and replay target will automatically stop itself. 4841 4842`record save FILENAME' 4843 Save the execution log to a file `FILENAME'. Default filename is 4844 `gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the 4845 inferior. 4846 4847`record restore FILENAME' 4848 Restore the execution log from a file `FILENAME'. File must have 4849 been created with `record save'. 4850 4851`set record insn-number-max LIMIT' 4852 Set the limit of instructions to be recorded. Default value is 4853 200000. 4854 4855 If LIMIT is a positive number, then GDB will start deleting 4856 instructions from the log once the number of the record 4857 instructions becomes greater than LIMIT. For every new recorded 4858 instruction, GDB will delete the earliest recorded instruction to 4859 keep the number of recorded instructions at the limit. (Since 4860 deleting recorded instructions loses information, GDB lets you 4861 control what happens when the limit is reached, by means of the 4862 `stop-at-limit' option, described below.) 4863 4864 If LIMIT is zero, GDB will never delete recorded instructions from 4865 the execution log. The number of recorded instructions is 4866 unlimited in this case. 4867 4868`show record insn-number-max' 4869 Show the limit of instructions to be recorded. 4870 4871`set record stop-at-limit' 4872 Control the behavior when the number of recorded instructions 4873 reaches the limit. If ON (the default), GDB will stop when the 4874 limit is reached for the first time and ask you whether you want 4875 to stop the inferior or continue running it and recording the 4876 execution log. If you decide to continue recording, each new 4877 recorded instruction will cause the oldest one to be deleted. 4878 4879 If this option is OFF, GDB will automatically delete the oldest 4880 record to make room for each new one, without asking. 4881 4882`show record stop-at-limit' 4883 Show the current setting of `stop-at-limit'. 4884 4885`set record memory-query' 4886 Control the behavior when GDB is unable to record memory changes 4887 caused by an instruction. If ON, GDB will query whether to stop 4888 the inferior in that case. 4889 4890 If this option is OFF (the default), GDB will automatically ignore 4891 the effect of such instructions on memory. Later, when GDB 4892 replays this execution log, it will mark the log of this 4893 instruction as not accessible, and it will not affect the replay 4894 results. 4895 4896`show record memory-query' 4897 Show the current setting of `memory-query'. 4898 4899`info record' 4900 Show various statistics about the state of process record and its 4901 in-memory execution log buffer, including: 4902 4903 * Whether in record mode or replay mode. 4904 4905 * Lowest recorded instruction number (counting from when the 4906 current execution log started recording instructions). 4907 4908 * Highest recorded instruction number. 4909 4910 * Current instruction about to be replayed (if in replay mode). 4911 4912 * Number of instructions contained in the execution log. 4913 4914 * Maximum number of instructions that may be contained in the 4915 execution log. 4916 4917`record delete' 4918 When record target runs in replay mode ("in the past"), delete the 4919 subsequent execution log and begin to record a new execution log 4920 starting from the current address. This means you will abandon 4921 the previously recorded "future" and begin recording a new 4922 "future". 4923 4924 4925File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top 4926 49278 Examining the Stack 4928********************* 4929 4930When your program has stopped, the first thing you need to know is 4931where it stopped and how it got there. 4932 4933 Each time your program performs a function call, information about 4934the call is generated. That information includes the location of the 4935call in your program, the arguments of the call, and the local 4936variables of the function being called. The information is saved in a 4937block of data called a "stack frame". The stack frames are allocated 4938in a region of memory called the "call stack". 4939 4940 When your program stops, the GDB commands for examining the stack 4941allow you to see all of this information. 4942 4943 One of the stack frames is "selected" by GDB and many GDB commands 4944refer implicitly to the selected frame. In particular, whenever you 4945ask GDB for the value of a variable in your program, the value is found 4946in the selected frame. There are special GDB commands to select 4947whichever frame you are interested in. *Note Selecting a Frame: 4948Selection. 4949 4950 When your program stops, GDB automatically selects the currently 4951executing frame and describes it briefly, similar to the `frame' 4952command (*note Information about a Frame: Frame Info.). 4953 4954* Menu: 4955 4956* Frames:: Stack frames 4957* Backtrace:: Backtraces 4958* Selection:: Selecting a frame 4959* Frame Info:: Information on a frame 4960 4961 4962File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack 4963 49648.1 Stack Frames 4965================ 4966 4967The call stack is divided up into contiguous pieces called "stack 4968frames", or "frames" for short; each frame is the data associated with 4969one call to one function. The frame contains the arguments given to 4970the function, the function's local variables, and the address at which 4971the function is executing. 4972 4973 When your program is started, the stack has only one frame, that of 4974the function `main'. This is called the "initial" frame or the 4975"outermost" frame. Each time a function is called, a new frame is 4976made. Each time a function returns, the frame for that function 4977invocation is eliminated. If a function is recursive, there can be 4978many frames for the same function. The frame for the function in which 4979execution is actually occurring is called the "innermost" frame. This 4980is the most recently created of all the stack frames that still exist. 4981 4982 Inside your program, stack frames are identified by their addresses. 4983A stack frame consists of many bytes, each of which has its own 4984address; each kind of computer has a convention for choosing one byte 4985whose address serves as the address of the frame. Usually this address 4986is kept in a register called the "frame pointer register" (*note $fp: 4987Registers.) while execution is going on in that frame. 4988 4989 GDB assigns numbers to all existing stack frames, starting with zero 4990for the innermost frame, one for the frame that called it, and so on 4991upward. These numbers do not really exist in your program; they are 4992assigned by GDB to give you a way of designating stack frames in GDB 4993commands. 4994 4995 Some compilers provide a way to compile functions so that they 4996operate without stack frames. (For example, the GCC option 4997 `-fomit-frame-pointer' 4998 generates functions without a frame.) This is occasionally done 4999with heavily used library functions to save the frame setup time. GDB 5000has limited facilities for dealing with these function invocations. If 5001the innermost function invocation has no stack frame, GDB nevertheless 5002regards it as though it had a separate frame, which is numbered zero as 5003usual, allowing correct tracing of the function call chain. However, 5004GDB has no provision for frameless functions elsewhere in the stack. 5005 5006`frame ARGS' 5007 The `frame' command allows you to move from one stack frame to 5008 another, and to print the stack frame you select. ARGS may be 5009 either the address of the frame or the stack frame number. 5010 Without an argument, `frame' prints the current stack frame. 5011 5012`select-frame' 5013 The `select-frame' command allows you to move from one stack frame 5014 to another without printing the frame. This is the silent version 5015 of `frame'. 5016 5017 5018File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack 5019 50208.2 Backtraces 5021============== 5022 5023A backtrace is a summary of how your program got where it is. It shows 5024one line per frame, for many frames, starting with the currently 5025executing frame (frame zero), followed by its caller (frame one), and 5026on up the stack. 5027 5028`backtrace' 5029`bt' 5030 Print a backtrace of the entire stack: one line per frame for all 5031 frames in the stack. 5032 5033 You can stop the backtrace at any time by typing the system 5034 interrupt character, normally `Ctrl-c'. 5035 5036`backtrace N' 5037`bt N' 5038 Similar, but print only the innermost N frames. 5039 5040`backtrace -N' 5041`bt -N' 5042 Similar, but print only the outermost N frames. 5043 5044`backtrace full' 5045`bt full' 5046`bt full N' 5047`bt full -N' 5048 Print the values of the local variables also. N specifies the 5049 number of frames to print, as described above. 5050 5051 The names `where' and `info stack' (abbreviated `info s') are 5052additional aliases for `backtrace'. 5053 5054 In a multi-threaded program, GDB by default shows the backtrace only 5055for the current thread. To display the backtrace for several or all of 5056the threads, use the command `thread apply' (*note thread apply: 5057Threads.). For example, if you type `thread apply all backtrace', GDB 5058will display the backtrace for all the threads; this is handy when you 5059debug a core dump of a multi-threaded program. 5060 5061 Each line in the backtrace shows the frame number and the function 5062name. The program counter value is also shown--unless you use `set 5063print address off'. The backtrace also shows the source file name and 5064line number, as well as the arguments to the function. The program 5065counter value is omitted if it is at the beginning of the code for that 5066line number. 5067 5068 Here is an example of a backtrace. It was made with the command `bt 50693', so it shows the innermost three frames. 5070 5071 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 5072 at builtin.c:993 5073 #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 5074 #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 5075 at macro.c:71 5076 (More stack frames follow...) 5077 5078The display for frame zero does not begin with a program counter value, 5079indicating that your program has stopped at the beginning of the code 5080for line `993' of `builtin.c'. 5081 5082The value of parameter `data' in frame 1 has been replaced by `...'. 5083By default, GDB prints the value of a parameter only if it is a scalar 5084(integer, pointer, enumeration, etc). See command `set print 5085frame-arguments' in *note Print Settings:: for more details on how to 5086configure the way function parameter values are printed. 5087 5088 If your program was compiled with optimizations, some compilers will 5089optimize away arguments passed to functions if those arguments are 5090never used after the call. Such optimizations generate code that 5091passes arguments through registers, but doesn't store those arguments 5092in the stack frame. GDB has no way of displaying such arguments in 5093stack frames other than the innermost one. Here's what such a 5094backtrace might look like: 5095 5096 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) 5097 at builtin.c:993 5098 #1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242 5099 #2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08) 5100 at macro.c:71 5101 (More stack frames follow...) 5102 5103The values of arguments that were not saved in their stack frames are 5104shown as `<value optimized out>'. 5105 5106 If you need to display the values of such optimized-out arguments, 5107either deduce that from other variables whose values depend on the one 5108you are interested in, or recompile without optimizations. 5109 5110 Most programs have a standard user entry point--a place where system 5111libraries and startup code transition into user code. For C this is 5112`main'(1). When GDB finds the entry function in a backtrace it will 5113terminate the backtrace, to avoid tracing into highly system-specific 5114(and generally uninteresting) code. 5115 5116 If you need to examine the startup code, or limit the number of 5117levels in a backtrace, you can change this behavior: 5118 5119`set backtrace past-main' 5120`set backtrace past-main on' 5121 Backtraces will continue past the user entry point. 5122 5123`set backtrace past-main off' 5124 Backtraces will stop when they encounter the user entry point. 5125 This is the default. 5126 5127`show backtrace past-main' 5128 Display the current user entry point backtrace policy. 5129 5130`set backtrace past-entry' 5131`set backtrace past-entry on' 5132 Backtraces will continue past the internal entry point of an 5133 application. This entry point is encoded by the linker when the 5134 application is built, and is likely before the user entry point 5135 `main' (or equivalent) is called. 5136 5137`set backtrace past-entry off' 5138 Backtraces will stop when they encounter the internal entry point 5139 of an application. This is the default. 5140 5141`show backtrace past-entry' 5142 Display the current internal entry point backtrace policy. 5143 5144`set backtrace limit N' 5145`set backtrace limit 0' 5146 Limit the backtrace to N levels. A value of zero means unlimited. 5147 5148`show backtrace limit' 5149 Display the current limit on backtrace levels. 5150 5151 ---------- Footnotes ---------- 5152 5153 (1) Note that embedded programs (the so-called "free-standing" 5154environment) are not required to have a `main' function as the entry 5155point. They could even have multiple entry points. 5156 5157 5158File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack 5159 51608.3 Selecting a Frame 5161===================== 5162 5163Most commands for examining the stack and other data in your program 5164work on whichever stack frame is selected at the moment. Here are the 5165commands for selecting a stack frame; all of them finish by printing a 5166brief description of the stack frame just selected. 5167 5168`frame N' 5169`f N' 5170 Select frame number N. Recall that frame zero is the innermost 5171 (currently executing) frame, frame one is the frame that called the 5172 innermost one, and so on. The highest-numbered frame is the one 5173 for `main'. 5174 5175`frame ADDR' 5176`f ADDR' 5177 Select the frame at address ADDR. This is useful mainly if the 5178 chaining of stack frames has been damaged by a bug, making it 5179 impossible for GDB to assign numbers properly to all frames. In 5180 addition, this can be useful when your program has multiple stacks 5181 and switches between them. 5182 5183 On the MIPS and Alpha architectures, `frame' needs two addresses to 5184 select an arbitrary frame: a stack pointer and a program counter. 5185 5186`up N' 5187 Move N frames up the stack. For positive numbers N, this advances 5188 toward the outermost frame, to higher frame numbers, to frames 5189 that have existed longer. N defaults to one. 5190 5191`down N' 5192 Move N frames down the stack. For positive numbers N, this 5193 advances toward the innermost frame, to lower frame numbers, to 5194 frames that were created more recently. N defaults to one. You 5195 may abbreviate `down' as `do'. 5196 5197 All of these commands end by printing two lines of output describing 5198the frame. The first line shows the frame number, the function name, 5199the arguments, and the source file and line number of execution in that 5200frame. The second line shows the text of that source line. 5201 5202 For example: 5203 5204 (gdb) up 5205 #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) 5206 at env.c:10 5207 10 read_input_file (argv[i]); 5208 5209 After such a printout, the `list' command with no arguments prints 5210ten lines centered on the point of execution in the frame. You can 5211also edit the program at the point of execution with your favorite 5212editing program by typing `edit'. *Note Printing Source Lines: List, 5213for details. 5214 5215`up-silently N' 5216`down-silently N' 5217 These two commands are variants of `up' and `down', respectively; 5218 they differ in that they do their work silently, without causing 5219 display of the new frame. They are intended primarily for use in 5220 GDB command scripts, where the output might be unnecessary and 5221 distracting. 5222 5223 5224File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack 5225 52268.4 Information About a Frame 5227============================= 5228 5229There are several other commands to print information about the selected 5230stack frame. 5231 5232`frame' 5233`f' 5234 When used without any argument, this command does not change which 5235 frame is selected, but prints a brief description of the currently 5236 selected stack frame. It can be abbreviated `f'. With an 5237 argument, this command is used to select a stack frame. *Note 5238 Selecting a Frame: Selection. 5239 5240`info frame' 5241`info f' 5242 This command prints a verbose description of the selected stack 5243 frame, including: 5244 5245 * the address of the frame 5246 5247 * the address of the next frame down (called by this frame) 5248 5249 * the address of the next frame up (caller of this frame) 5250 5251 * the language in which the source code corresponding to this 5252 frame is written 5253 5254 * the address of the frame's arguments 5255 5256 * the address of the frame's local variables 5257 5258 * the program counter saved in it (the address of execution in 5259 the caller frame) 5260 5261 * which registers were saved in the frame 5262 5263 The verbose description is useful when something has gone wrong 5264 that has made the stack format fail to fit the usual conventions. 5265 5266`info frame ADDR' 5267`info f ADDR' 5268 Print a verbose description of the frame at address ADDR, without 5269 selecting that frame. The selected frame remains unchanged by this 5270 command. This requires the same kind of address (more than one 5271 for some architectures) that you specify in the `frame' command. 5272 *Note Selecting a Frame: Selection. 5273 5274`info args' 5275 Print the arguments of the selected frame, each on a separate line. 5276 5277`info locals' 5278 Print the local variables of the selected frame, each on a separate 5279 line. These are all variables (declared either static or 5280 automatic) accessible at the point of execution of the selected 5281 frame. 5282 5283`info catch' 5284 Print a list of all the exception handlers that are active in the 5285 current stack frame at the current point of execution. To see 5286 other exception handlers, visit the associated frame (using the 5287 `up', `down', or `frame' commands); then type `info catch'. *Note 5288 Setting Catchpoints: Set Catchpoints. 5289 5290 5291 5292File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top 5293 52949 Examining Source Files 5295************************ 5296 5297GDB can print parts of your program's source, since the debugging 5298information recorded in the program tells GDB what source files were 5299used to build it. When your program stops, GDB spontaneously prints 5300the line where it stopped. Likewise, when you select a stack frame 5301(*note Selecting a Frame: Selection.), GDB prints the line where 5302execution in that frame has stopped. You can print other portions of 5303source files by explicit command. 5304 5305 If you use GDB through its GNU Emacs interface, you may prefer to 5306use Emacs facilities to view source; see *note Using GDB under GNU 5307Emacs: Emacs. 5308 5309* Menu: 5310 5311* List:: Printing source lines 5312* Specify Location:: How to specify code locations 5313* Edit:: Editing source files 5314* Search:: Searching source files 5315* Source Path:: Specifying source directories 5316* Machine Code:: Source and machine code 5317 5318 5319File: gdb.info, Node: List, Next: Specify Location, Up: Source 5320 53219.1 Printing Source Lines 5322========================= 5323 5324To print lines from a source file, use the `list' command (abbreviated 5325`l'). By default, ten lines are printed. There are several ways to 5326specify what part of the file you want to print; see *note Specify 5327Location::, for the full list. 5328 5329 Here are the forms of the `list' command most commonly used: 5330 5331`list LINENUM' 5332 Print lines centered around line number LINENUM in the current 5333 source file. 5334 5335`list FUNCTION' 5336 Print lines centered around the beginning of function FUNCTION. 5337 5338`list' 5339 Print more lines. If the last lines printed were printed with a 5340 `list' command, this prints lines following the last lines 5341 printed; however, if the last line printed was a solitary line 5342 printed as part of displaying a stack frame (*note Examining the 5343 Stack: Stack.), this prints lines centered around that line. 5344 5345`list -' 5346 Print lines just before the lines last printed. 5347 5348 By default, GDB prints ten source lines with any of these forms of 5349the `list' command. You can change this using `set listsize': 5350 5351`set listsize COUNT' 5352 Make the `list' command display COUNT source lines (unless the 5353 `list' argument explicitly specifies some other number). 5354 5355`show listsize' 5356 Display the number of lines that `list' prints. 5357 5358 Repeating a `list' command with <RET> discards the argument, so it 5359is equivalent to typing just `list'. This is more useful than listing 5360the same lines again. An exception is made for an argument of `-'; 5361that argument is preserved in repetition so that each repetition moves 5362up in the source file. 5363 5364 In general, the `list' command expects you to supply zero, one or two 5365"linespecs". Linespecs specify source lines; there are several ways of 5366writing them (*note Specify Location::), but the effect is always to 5367specify some source line. 5368 5369 Here is a complete description of the possible arguments for `list': 5370 5371`list LINESPEC' 5372 Print lines centered around the line specified by LINESPEC. 5373 5374`list FIRST,LAST' 5375 Print lines from FIRST to LAST. Both arguments are linespecs. 5376 When a `list' command has two linespecs, and the source file of 5377 the second linespec is omitted, this refers to the same source 5378 file as the first linespec. 5379 5380`list ,LAST' 5381 Print lines ending with LAST. 5382 5383`list FIRST,' 5384 Print lines starting with FIRST. 5385 5386`list +' 5387 Print lines just after the lines last printed. 5388 5389`list -' 5390 Print lines just before the lines last printed. 5391 5392`list' 5393 As described in the preceding table. 5394 5395 5396File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source 5397 53989.2 Specifying a Location 5399========================= 5400 5401Several GDB commands accept arguments that specify a location of your 5402program's code. Since GDB is a source-level debugger, a location 5403usually specifies some line in the source code; for that reason, 5404locations are also known as "linespecs". 5405 5406 Here are all the different ways of specifying a code location that 5407GDB understands: 5408 5409`LINENUM' 5410 Specifies the line number LINENUM of the current source file. 5411 5412`-OFFSET' 5413`+OFFSET' 5414 Specifies the line OFFSET lines before or after the "current 5415 line". For the `list' command, the current line is the last one 5416 printed; for the breakpoint commands, this is the line at which 5417 execution stopped in the currently selected "stack frame" (*note 5418 Frames: Frames, for a description of stack frames.) When used as 5419 the second of the two linespecs in a `list' command, this 5420 specifies the line OFFSET lines up or down from the first linespec. 5421 5422`FILENAME:LINENUM' 5423 Specifies the line LINENUM in the source file FILENAME. 5424 5425`FUNCTION' 5426 Specifies the line that begins the body of the function FUNCTION. 5427 For example, in C, this is the line with the open brace. 5428 5429`FILENAME:FUNCTION' 5430 Specifies the line that begins the body of the function FUNCTION 5431 in the file FILENAME. You only need the file name with a function 5432 name to avoid ambiguity when there are identically named functions 5433 in different source files. 5434 5435`LABEL' 5436 Specifies the line at which the label named LABEL appears. GDB 5437 searches for the label in the function corresponding to the 5438 currently selected stack frame. If there is no current selected 5439 stack frame (for instance, if the inferior is not running), then 5440 GDB will not search for a label. 5441 5442`*ADDRESS' 5443 Specifies the program address ADDRESS. For line-oriented 5444 commands, such as `list' and `edit', this specifies a source line 5445 that contains ADDRESS. For `break' and other breakpoint oriented 5446 commands, this can be used to set breakpoints in parts of your 5447 program which do not have debugging information or source files. 5448 5449 Here ADDRESS may be any expression valid in the current working 5450 language (*note working language: Languages.) that specifies a code 5451 address. In addition, as a convenience, GDB extends the semantics 5452 of expressions used in locations to cover the situations that 5453 frequently happen during debugging. Here are the various forms of 5454 ADDRESS: 5455 5456 `EXPRESSION' 5457 Any expression valid in the current working language. 5458 5459 `FUNCADDR' 5460 An address of a function or procedure derived from its name. 5461 In C, C++, Java, Objective-C, Fortran, minimal, and assembly, 5462 this is simply the function's name FUNCTION (and actually a 5463 special case of a valid expression). In Pascal and Modula-2, 5464 this is `&FUNCTION'. In Ada, this is `FUNCTION'Address' 5465 (although the Pascal form also works). 5466 5467 This form specifies the address of the function's first 5468 instruction, before the stack frame and arguments have been 5469 set up. 5470 5471 `'FILENAME'::FUNCADDR' 5472 Like FUNCADDR above, but also specifies the name of the source 5473 file explicitly. This is useful if the name of the function 5474 does not specify the function unambiguously, e.g., if there 5475 are several functions with identical names in different 5476 source files. 5477 5478 5479 5480File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source 5481 54829.3 Editing Source Files 5483======================== 5484 5485To edit the lines in a source file, use the `edit' command. The 5486editing program of your choice is invoked with the current line set to 5487the active line in the program. Alternatively, there are several ways 5488to specify what part of the file you want to print if you want to see 5489other parts of the program: 5490 5491`edit LOCATION' 5492 Edit the source file specified by `location'. Editing starts at 5493 that LOCATION, e.g., at the specified source line of the specified 5494 file. *Note Specify Location::, for all the possible forms of the 5495 LOCATION argument; here are the forms of the `edit' command most 5496 commonly used: 5497 5498 `edit NUMBER' 5499 Edit the current source file with NUMBER as the active line 5500 number. 5501 5502 `edit FUNCTION' 5503 Edit the file containing FUNCTION at the beginning of its 5504 definition. 5505 5506 55079.3.1 Choosing your Editor 5508-------------------------- 5509 5510You can customize GDB to use any editor you want (1). By default, it 5511is `/bin/ex', but you can change this by setting the environment 5512variable `EDITOR' before using GDB. For example, to configure GDB to 5513use the `vi' editor, you could use these commands with the `sh' shell: 5514 EDITOR=/usr/bin/vi 5515 export EDITOR 5516 gdb ... 5517 or in the `csh' shell, 5518 setenv EDITOR /usr/bin/vi 5519 gdb ... 5520 5521 ---------- Footnotes ---------- 5522 5523 (1) The only restriction is that your editor (say `ex'), recognizes 5524the following command-line syntax: 5525 ex +NUMBER file 5526 The optional numeric value +NUMBER specifies the number of the line 5527in the file where to start editing. 5528 5529 5530File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source 5531 55329.4 Searching Source Files 5533========================== 5534 5535There are two commands for searching through the current source file 5536for a regular expression. 5537 5538`forward-search REGEXP' 5539`search REGEXP' 5540 The command `forward-search REGEXP' checks each line, starting 5541 with the one following the last line listed, for a match for 5542 REGEXP. It lists the line that is found. You can use the synonym 5543 `search REGEXP' or abbreviate the command name as `fo'. 5544 5545`reverse-search REGEXP' 5546 The command `reverse-search REGEXP' checks each line, starting 5547 with the one before the last line listed and going backward, for a 5548 match for REGEXP. It lists the line that is found. You can 5549 abbreviate this command as `rev'. 5550 5551 5552File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source 5553 55549.5 Specifying Source Directories 5555================================= 5556 5557Executable programs sometimes do not record the directories of the 5558source files from which they were compiled, just the names. Even when 5559they do, the directories could be moved between the compilation and 5560your debugging session. GDB has a list of directories to search for 5561source files; this is called the "source path". Each time GDB wants a 5562source file, it tries all the directories in the list, in the order 5563they are present in the list, until it finds a file with the desired 5564name. 5565 5566 For example, suppose an executable references the file 5567`/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The 5568file is first looked up literally; if this fails, 5569`/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails, 5570`/mnt/cross/foo.c' is opened; if this fails, an error message is 5571printed. GDB does not look up the parts of the source file name, such 5572as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of 5573the source path are not searched: if the source path is `/mnt/cross', 5574and the binary refers to `foo.c', GDB would not find it under 5575`/mnt/cross/usr/src/foo-1.0/lib'. 5576 5577 Plain file names, relative file names with leading directories, file 5578names containing dots, etc. are all treated as described above; for 5579instance, if the source path is `/mnt/cross', and the source file is 5580recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then 5581`/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'. 5582 5583 Note that the executable search path is _not_ used to locate the 5584source files. 5585 5586 Whenever you reset or rearrange the source path, GDB clears out any 5587information it has cached about where source files are found and where 5588each line is in the file. 5589 5590 When you start GDB, its source path includes only `cdir' and `cwd', 5591in that order. To add other directories, use the `directory' command. 5592 5593 The search path is used to find both program source files and GDB 5594script files (read using the `-command' option and `source' command). 5595 5596 In addition to the source path, GDB provides a set of commands that 5597manage a list of source path substitution rules. A "substitution rule" 5598specifies how to rewrite source directories stored in the program's 5599debug information in case the sources were moved to a different 5600directory between compilation and debugging. A rule is made of two 5601strings, the first specifying what needs to be rewritten in the path, 5602and the second specifying how it should be rewritten. In *note set 5603substitute-path::, we name these two parts FROM and TO respectively. 5604GDB does a simple string replacement of FROM with TO at the start of 5605the directory part of the source file name, and uses that result 5606instead of the original file name to look up the sources. 5607 5608 Using the previous example, suppose the `foo-1.0' tree has been 5609moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace 5610`/usr/src' in all source path names with `/mnt/cross'. The first 5611lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the 5612original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source 5613path substitution rule, use the `set substitute-path' command (*note 5614set substitute-path::). 5615 5616 To avoid unexpected substitution results, a rule is applied only if 5617the FROM part of the directory name ends at a directory separator. For 5618instance, a rule substituting `/usr/source' into `/mnt/cross' will be 5619applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'. 5620And because the substitution is applied only at the beginning of the 5621directory name, this rule will not be applied to 5622`/root/usr/source/baz.c' either. 5623 5624 In many cases, you can achieve the same result using the `directory' 5625command. However, `set substitute-path' can be more efficient in the 5626case where the sources are organized in a complex tree with multiple 5627subdirectories. With the `directory' command, you need to add each 5628subdirectory of your project. If you moved the entire tree while 5629preserving its internal organization, then `set substitute-path' allows 5630you to direct the debugger to all the sources with one single command. 5631 5632 `set substitute-path' is also more than just a shortcut command. 5633The source path is only used if the file at the original location no 5634longer exists. On the other hand, `set substitute-path' modifies the 5635debugger behavior to look at the rewritten location instead. So, if 5636for any reason a source file that is not relevant to your executable is 5637located at the original location, a substitution rule is the only 5638method available to point GDB at the new location. 5639 5640 You can configure a default source path substitution rule by 5641configuring GDB with the `--with-relocated-sources=DIR' option. The DIR 5642should be the name of a directory under GDB's configured prefix (set 5643with `--prefix' or `--exec-prefix'), and directory names in debug 5644information under DIR will be adjusted automatically if the installed 5645GDB is moved to a new location. This is useful if GDB, libraries or 5646executables with debug information and corresponding source code are 5647being moved together. 5648 5649`directory DIRNAME ...' 5650 5651`dir DIRNAME ...' 5652 Add directory DIRNAME to the front of the source path. Several 5653 directory names may be given to this command, separated by `:' 5654 (`;' on MS-DOS and MS-Windows, where `:' usually appears as part 5655 of absolute file names) or whitespace. You may specify a 5656 directory that is already in the source path; this moves it 5657 forward, so GDB searches it sooner. 5658 5659 You can use the string `$cdir' to refer to the compilation 5660 directory (if one is recorded), and `$cwd' to refer to the current 5661 working directory. `$cwd' is not the same as `.'--the former 5662 tracks the current working directory as it changes during your GDB 5663 session, while the latter is immediately expanded to the current 5664 directory at the time you add an entry to the source path. 5665 5666`directory' 5667 Reset the source path to its default value (`$cdir:$cwd' on Unix 5668 systems). This requires confirmation. 5669 5670`show directories' 5671 Print the source path: show which directories it contains. 5672 5673`set substitute-path FROM TO' 5674 Define a source path substitution rule, and add it at the end of 5675 the current list of existing substitution rules. If a rule with 5676 the same FROM was already defined, then the old rule is also 5677 deleted. 5678 5679 For example, if the file `/foo/bar/baz.c' was moved to 5680 `/mnt/cross/baz.c', then the command 5681 5682 (gdb) set substitute-path /usr/src /mnt/cross 5683 5684 will tell GDB to replace `/usr/src' with `/mnt/cross', which will 5685 allow GDB to find the file `baz.c' even though it was moved. 5686 5687 In the case when more than one substitution rule have been defined, 5688 the rules are evaluated one by one in the order where they have 5689 been defined. The first one matching, if any, is selected to 5690 perform the substitution. 5691 5692 For instance, if we had entered the following commands: 5693 5694 (gdb) set substitute-path /usr/src/include /mnt/include 5695 (gdb) set substitute-path /usr/src /mnt/src 5696 5697 GDB would then rewrite `/usr/src/include/defs.h' into 5698 `/mnt/include/defs.h' by using the first rule. However, it would 5699 use the second rule to rewrite `/usr/src/lib/foo.c' into 5700 `/mnt/src/lib/foo.c'. 5701 5702`unset substitute-path [path]' 5703 If a path is specified, search the current list of substitution 5704 rules for a rule that would rewrite that path. Delete that rule 5705 if found. A warning is emitted by the debugger if no rule could 5706 be found. 5707 5708 If no path is specified, then all substitution rules are deleted. 5709 5710`show substitute-path [path]' 5711 If a path is specified, then print the source path substitution 5712 rule which would rewrite that path, if any. 5713 5714 If no path is specified, then print all existing source path 5715 substitution rules. 5716 5717 5718 If your source path is cluttered with directories that are no longer 5719of interest, GDB may sometimes cause confusion by finding the wrong 5720versions of source. You can correct the situation as follows: 5721 5722 1. Use `directory' with no argument to reset the source path to its 5723 default value. 5724 5725 2. Use `directory' with suitable arguments to reinstall the 5726 directories you want in the source path. You can add all the 5727 directories in one command. 5728 5729 5730File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source 5731 57329.6 Source and Machine Code 5733=========================== 5734 5735You can use the command `info line' to map source lines to program 5736addresses (and vice versa), and the command `disassemble' to display a 5737range of addresses as machine instructions. You can use the command 5738`set disassemble-next-line' to set whether to disassemble next source 5739line when execution stops. When run under GNU Emacs mode, the `info 5740line' command causes the arrow to point to the line specified. Also, 5741`info line' prints addresses in symbolic form as well as hex. 5742 5743`info line LINESPEC' 5744 Print the starting and ending addresses of the compiled code for 5745 source line LINESPEC. You can specify source lines in any of the 5746 ways documented in *note Specify Location::. 5747 5748 For example, we can use `info line' to discover the location of the 5749object code for the first line of function `m4_changequote': 5750 5751 (gdb) info line m4_changequote 5752 Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. 5753 5754We can also inquire (using `*ADDR' as the form for LINESPEC) what 5755source line covers a particular address: 5756 (gdb) info line *0x63ff 5757 Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. 5758 5759 After `info line', the default address for the `x' command is 5760changed to the starting address of the line, so that `x/i' is 5761sufficient to begin examining the machine code (*note Examining Memory: 5762Memory.). Also, this address is saved as the value of the convenience 5763variable `$_' (*note Convenience Variables: Convenience Vars.). 5764 5765`disassemble' 5766`disassemble /m' 5767`disassemble /r' 5768 This specialized command dumps a range of memory as machine 5769 instructions. It can also print mixed source+disassembly by 5770 specifying the `/m' modifier and print the raw instructions in hex 5771 as well as in symbolic form by specifying the `/r'. The default 5772 memory range is the function surrounding the program counter of 5773 the selected frame. A single argument to this command is a 5774 program counter value; GDB dumps the function surrounding this 5775 value. When two arguments are given, they should be separated by 5776 a comma, possibly surrounded by whitespace. The arguments specify 5777 a range of addresses to dump, in one of two forms: 5778 5779 `START,END' 5780 the addresses from START (inclusive) to END (exclusive) 5781 5782 `START,+LENGTH' 5783 the addresses from START (inclusive) to `START+LENGTH' 5784 (exclusive). 5785 5786 When 2 arguments are specified, the name of the function is also 5787 printed (since there could be several functions in the given 5788 range). 5789 5790 The argument(s) can be any expression yielding a numeric value, 5791 such as `0x32c4', `&main+10' or `$pc - 8'. 5792 5793 If the range of memory being disassembled contains current program 5794 counter, the instruction at that location is shown with a `=>' 5795 marker. 5796 5797 The following example shows the disassembly of a range of addresses 5798of HP PA-RISC 2.0 code: 5799 5800 (gdb) disas 0x32c4, 0x32e4 5801 Dump of assembler code from 0x32c4 to 0x32e4: 5802 0x32c4 <main+204>: addil 0,dp 5803 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 5804 0x32cc <main+212>: ldil 0x3000,r31 5805 0x32d0 <main+216>: ble 0x3f8(sr4,r31) 5806 0x32d4 <main+220>: ldo 0(r31),rp 5807 0x32d8 <main+224>: addil -0x800,dp 5808 0x32dc <main+228>: ldo 0x588(r1),r26 5809 0x32e0 <main+232>: ldil 0x3000,r31 5810 End of assembler dump. 5811 5812 Here is an example showing mixed source+assembly for Intel x86, when 5813the program is stopped just after function prologue: 5814 5815 (gdb) disas /m main 5816 Dump of assembler code for function main: 5817 5 { 5818 0x08048330 <+0>: push %ebp 5819 0x08048331 <+1>: mov %esp,%ebp 5820 0x08048333 <+3>: sub $0x8,%esp 5821 0x08048336 <+6>: and $0xfffffff0,%esp 5822 0x08048339 <+9>: sub $0x10,%esp 5823 5824 6 printf ("Hello.\n"); 5825 => 0x0804833c <+12>: movl $0x8048440,(%esp) 5826 0x08048343 <+19>: call 0x8048284 <puts@plt> 5827 5828 7 return 0; 5829 8 } 5830 0x08048348 <+24>: mov $0x0,%eax 5831 0x0804834d <+29>: leave 5832 0x0804834e <+30>: ret 5833 5834 End of assembler dump. 5835 5836 Here is another example showing raw instructions in hex for AMD 5837x86-64, 5838 5839 (gdb) disas /r 0x400281,+10 5840 Dump of assembler code from 0x400281 to 0x40028b: 5841 0x0000000000400281: 38 36 cmp %dh,(%rsi) 5842 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax 5843 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) 5844 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al 5845 End of assembler dump. 5846 5847 Some architectures have more than one commonly-used set of 5848instruction mnemonics or other syntax. 5849 5850 For programs that were dynamically linked and use shared libraries, 5851instructions that call functions or branch to locations in the shared 5852libraries might show a seemingly bogus location--it's actually a 5853location of the relocation table. On some architectures, GDB might be 5854able to resolve these to actual function names. 5855 5856`set disassembly-flavor INSTRUCTION-SET' 5857 Select the instruction set to use when disassembling the program 5858 via the `disassemble' or `x/i' commands. 5859 5860 Currently this command is only defined for the Intel x86 family. 5861 You can set INSTRUCTION-SET to either `intel' or `att'. The 5862 default is `att', the AT&T flavor used by default by Unix 5863 assemblers for x86-based targets. 5864 5865`show disassembly-flavor' 5866 Show the current setting of the disassembly flavor. 5867 5868`set disassemble-next-line' 5869`show disassemble-next-line' 5870 Control whether or not GDB will disassemble the next source line 5871 or instruction when execution stops. If ON, GDB will display 5872 disassembly of the next source line when execution of the program 5873 being debugged stops. This is _in addition_ to displaying the 5874 source line itself, which GDB always does if possible. If the 5875 next source line cannot be displayed for some reason (e.g., if GDB 5876 cannot find the source file, or there's no line info in the debug 5877 info), GDB will display disassembly of the next _instruction_ 5878 instead of showing the next source line. If AUTO, GDB will 5879 display disassembly of next instruction only if the source line 5880 cannot be displayed. This setting causes GDB to display some 5881 feedback when you step through a function with no line info or 5882 whose source file is unavailable. The default is OFF, which means 5883 never display the disassembly of the next line or instruction. 5884 5885 5886File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top 5887 588810 Examining Data 5889***************** 5890 5891The usual way to examine data in your program is with the `print' 5892command (abbreviated `p'), or its synonym `inspect'. It evaluates and 5893prints the value of an expression of the language your program is 5894written in (*note Using GDB with Different Languages: Languages.). It 5895may also print the expression using a Python-based pretty-printer 5896(*note Pretty Printing::). 5897 5898`print EXPR' 5899`print /F EXPR' 5900 EXPR is an expression (in the source language). By default the 5901 value of EXPR is printed in a format appropriate to its data type; 5902 you can choose a different format by specifying `/F', where F is a 5903 letter specifying the format; see *note Output Formats: Output 5904 Formats. 5905 5906`print' 5907`print /F' 5908 If you omit EXPR, GDB displays the last value again (from the 5909 "value history"; *note Value History: Value History.). This 5910 allows you to conveniently inspect the same value in an 5911 alternative format. 5912 5913 A more low-level way of examining data is with the `x' command. It 5914examines data in memory at a specified address and prints it in a 5915specified format. *Note Examining Memory: Memory. 5916 5917 If you are interested in information about types, or about how the 5918fields of a struct or a class are declared, use the `ptype EXP' command 5919rather than `print'. *Note Examining the Symbol Table: Symbols. 5920 5921* Menu: 5922 5923* Expressions:: Expressions 5924* Ambiguous Expressions:: Ambiguous Expressions 5925* Variables:: Program variables 5926* Arrays:: Artificial arrays 5927* Output Formats:: Output formats 5928* Memory:: Examining memory 5929* Auto Display:: Automatic display 5930* Print Settings:: Print settings 5931* Pretty Printing:: Python pretty printing 5932* Value History:: Value history 5933* Convenience Vars:: Convenience variables 5934* Registers:: Registers 5935* Floating Point Hardware:: Floating point hardware 5936* Vector Unit:: Vector Unit 5937* OS Information:: Auxiliary data provided by operating system 5938* Memory Region Attributes:: Memory region attributes 5939* Dump/Restore Files:: Copy between memory and a file 5940* Core File Generation:: Cause a program dump its core 5941* Character Sets:: Debugging programs that use a different 5942 character set than GDB does 5943* Caching Remote Data:: Data caching for remote targets 5944* Searching Memory:: Searching memory for a sequence of bytes 5945 5946 5947File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data 5948 594910.1 Expressions 5950================ 5951 5952`print' and many other GDB commands accept an expression and compute 5953its value. Any kind of constant, variable or operator defined by the 5954programming language you are using is valid in an expression in GDB. 5955This includes conditional expressions, function calls, casts, and 5956string constants. It also includes preprocessor macros, if you 5957compiled your program to include this information; see *note 5958Compilation::. 5959 5960 GDB supports array constants in expressions input by the user. The 5961syntax is {ELEMENT, ELEMENT...}. For example, you can use the command 5962`print {1, 2, 3}' to create an array of three integers. If you pass an 5963array to a function or assign it to a program variable, GDB copies the 5964array to memory that is `malloc'ed in the target program. 5965 5966 Because C is so widespread, most of the expressions shown in 5967examples in this manual are in C. *Note Using GDB with Different 5968Languages: Languages, for information on how to use expressions in other 5969languages. 5970 5971 In this section, we discuss operators that you can use in GDB 5972expressions regardless of your programming language. 5973 5974 Casts are supported in all languages, not just in C, because it is so 5975useful to cast a number into a pointer in order to examine a structure 5976at that address in memory. 5977 5978 GDB supports these operators, in addition to those common to 5979programming languages: 5980 5981`@' 5982 `@' is a binary operator for treating parts of memory as arrays. 5983 *Note Artificial Arrays: Arrays, for more information. 5984 5985`::' 5986 `::' allows you to specify a variable in terms of the file or 5987 function where it is defined. *Note Program Variables: Variables. 5988 5989`{TYPE} ADDR' 5990 Refers to an object of type TYPE stored at address ADDR in memory. 5991 ADDR may be any expression whose value is an integer or pointer 5992 (but parentheses are required around binary operators, just as in 5993 a cast). This construct is allowed regardless of what kind of 5994 data is normally supposed to reside at ADDR. 5995 5996 5997File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data 5998 599910.2 Ambiguous Expressions 6000========================== 6001 6002Expressions can sometimes contain some ambiguous elements. For 6003instance, some programming languages (notably Ada, C++ and Objective-C) 6004permit a single function name to be defined several times, for 6005application in different contexts. This is called "overloading". 6006Another example involving Ada is generics. A "generic package" is 6007similar to C++ templates and is typically instantiated several times, 6008resulting in the same function name being defined in different contexts. 6009 6010 In some cases and depending on the language, it is possible to adjust 6011the expression to remove the ambiguity. For instance in C++, you can 6012specify the signature of the function you want to break on, as in 6013`break FUNCTION(TYPES)'. In Ada, using the fully qualified name of 6014your function often makes the expression unambiguous as well. 6015 6016 When an ambiguity that needs to be resolved is detected, the debugger 6017has the capability to display a menu of numbered choices for each 6018possibility, and then waits for the selection with the prompt `>'. The 6019first option is always `[0] cancel', and typing `0 <RET>' aborts the 6020current command. If the command in which the expression was used 6021allows more than one choice to be selected, the next option in the menu 6022is `[1] all', and typing `1 <RET>' selects all possible choices. 6023 6024 For example, the following session excerpt shows an attempt to set a 6025breakpoint at the overloaded symbol `String::after'. We choose three 6026particular definitions of that function name: 6027 6028 (gdb) b String::after 6029 [0] cancel 6030 [1] all 6031 [2] file:String.cc; line number:867 6032 [3] file:String.cc; line number:860 6033 [4] file:String.cc; line number:875 6034 [5] file:String.cc; line number:853 6035 [6] file:String.cc; line number:846 6036 [7] file:String.cc; line number:735 6037 > 2 4 6 6038 Breakpoint 1 at 0xb26c: file String.cc, line 867. 6039 Breakpoint 2 at 0xb344: file String.cc, line 875. 6040 Breakpoint 3 at 0xafcc: file String.cc, line 846. 6041 Multiple breakpoints were set. 6042 Use the "delete" command to delete unwanted 6043 breakpoints. 6044 (gdb) 6045 6046`set multiple-symbols MODE' 6047 This option allows you to adjust the debugger behavior when an 6048 expression is ambiguous. 6049 6050 By default, MODE is set to `all'. If the command with which the 6051 expression is used allows more than one choice, then GDB 6052 automatically selects all possible choices. For instance, 6053 inserting a breakpoint on a function using an ambiguous name 6054 results in a breakpoint inserted on each possible match. However, 6055 if a unique choice must be made, then GDB uses the menu to help 6056 you disambiguate the expression. For instance, printing the 6057 address of an overloaded function will result in the use of the 6058 menu. 6059 6060 When MODE is set to `ask', the debugger always uses the menu when 6061 an ambiguity is detected. 6062 6063 Finally, when MODE is set to `cancel', the debugger reports an 6064 error due to the ambiguity and the command is aborted. 6065 6066`show multiple-symbols' 6067 Show the current value of the `multiple-symbols' setting. 6068 6069 6070File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data 6071 607210.3 Program Variables 6073====================== 6074 6075The most common kind of expression to use is the name of a variable in 6076your program. 6077 6078 Variables in expressions are understood in the selected stack frame 6079(*note Selecting a Frame: Selection.); they must be either: 6080 6081 * global (or file-static) 6082 6083or 6084 6085 * visible according to the scope rules of the programming language 6086 from the point of execution in that frame 6087 6088This means that in the function 6089 6090 foo (a) 6091 int a; 6092 { 6093 bar (a); 6094 { 6095 int b = test (); 6096 bar (b); 6097 } 6098 } 6099 6100you can examine and use the variable `a' whenever your program is 6101executing within the function `foo', but you can only use or examine 6102the variable `b' while your program is executing inside the block where 6103`b' is declared. 6104 6105 There is an exception: you can refer to a variable or function whose 6106scope is a single source file even if the current execution point is not 6107in this file. But it is possible to have more than one such variable or 6108function with the same name (in different source files). If that 6109happens, referring to that name has unpredictable effects. If you wish, 6110you can specify a static variable in a particular function or file, 6111using the colon-colon (`::') notation: 6112 6113 FILE::VARIABLE 6114 FUNCTION::VARIABLE 6115 6116Here FILE or FUNCTION is the name of the context for the static 6117VARIABLE. In the case of file names, you can use quotes to make sure 6118GDB parses the file name as a single word--for example, to print a 6119global value of `x' defined in `f2.c': 6120 6121 (gdb) p 'f2.c'::x 6122 6123 This use of `::' is very rarely in conflict with the very similar 6124use of the same notation in C++. GDB also supports use of the C++ 6125scope resolution operator in GDB expressions. 6126 6127 _Warning:_ Occasionally, a local variable may appear to have the 6128 wrong value at certain points in a function--just after entry to a 6129 new scope, and just before exit. 6130 You may see this problem when you are stepping by machine 6131instructions. This is because, on most machines, it takes more than 6132one instruction to set up a stack frame (including local variable 6133definitions); if you are stepping by machine instructions, variables 6134may appear to have the wrong values until the stack frame is completely 6135built. On exit, it usually also takes more than one machine 6136instruction to destroy a stack frame; after you begin stepping through 6137that group of instructions, local variable definitions may be gone. 6138 6139 This may also happen when the compiler does significant 6140optimizations. To be sure of always seeing accurate values, turn off 6141all optimization when compiling. 6142 6143 Another possible effect of compiler optimizations is to optimize 6144unused variables out of existence, or assign variables to registers (as 6145opposed to memory addresses). Depending on the support for such cases 6146offered by the debug info format used by the compiler, GDB might not be 6147able to display values for such local variables. If that happens, GDB 6148will print a message like this: 6149 6150 No symbol "foo" in current context. 6151 6152 To solve such problems, either recompile without optimizations, or 6153use a different debug info format, if the compiler supports several such 6154formats. For example, GCC, the GNU C/C++ compiler, usually supports 6155the `-gstabs+' option. `-gstabs+' produces debug info in a format that 6156is superior to formats such as COFF. You may be able to use DWARF 2 6157(`-gdwarf-2'), which is also an effective form for debug info. *Note 6158Options for Debugging Your Program or GCC: (gcc.info)Debugging Options. 6159*Note C and C++: C, for more information about debug info formats that 6160are best suited to C++ programs. 6161 6162 If you ask to print an object whose contents are unknown to GDB, 6163e.g., because its data type is not completely specified by the debug 6164information, GDB will say `<incomplete type>'. *Note incomplete type: 6165Symbols, for more about this. 6166 6167 Strings are identified as arrays of `char' values without specified 6168signedness. Arrays of either `signed char' or `unsigned char' get 6169printed as arrays of 1 byte sized integers. `-fsigned-char' or 6170`-funsigned-char' GCC options have no effect as GDB defines literal 6171string type `"char"' as `char' without a sign. For program code 6172 6173 char var0[] = "A"; 6174 signed char var1[] = "A"; 6175 6176 You get during debugging 6177 (gdb) print var0 6178 $1 = "A" 6179 (gdb) print var1 6180 $2 = {65 'A', 0 '\0'} 6181 6182 6183File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data 6184 618510.4 Artificial Arrays 6186====================== 6187 6188It is often useful to print out several successive objects of the same 6189type in memory; a section of an array, or an array of dynamically 6190determined size for which only a pointer exists in the program. 6191 6192 You can do this by referring to a contiguous span of memory as an 6193"artificial array", using the binary operator `@'. The left operand of 6194`@' should be the first element of the desired array and be an 6195individual object. The right operand should be the desired length of 6196the array. The result is an array value whose elements are all of the 6197type of the left argument. The first element is actually the left 6198argument; the second element comes from bytes of memory immediately 6199following those that hold the first element, and so on. Here is an 6200example. If a program says 6201 6202 int *array = (int *) malloc (len * sizeof (int)); 6203 6204you can print the contents of `array' with 6205 6206 p *array@len 6207 6208 The left operand of `@' must reside in memory. Array values made 6209with `@' in this way behave just like other arrays in terms of 6210subscripting, and are coerced to pointers when used in expressions. 6211Artificial arrays most often appear in expressions via the value history 6212(*note Value History: Value History.), after printing one out. 6213 6214 Another way to create an artificial array is to use a cast. This 6215re-interprets a value as if it were an array. The value need not be in 6216memory: 6217 (gdb) p/x (short[2])0x12345678 6218 $1 = {0x1234, 0x5678} 6219 6220 As a convenience, if you leave the array length out (as in 6221`(TYPE[])VALUE') GDB calculates the size to fill the value (as 6222`sizeof(VALUE)/sizeof(TYPE)': 6223 (gdb) p/x (short[])0x12345678 6224 $2 = {0x1234, 0x5678} 6225 6226 Sometimes the artificial array mechanism is not quite enough; in 6227moderately complex data structures, the elements of interest may not 6228actually be adjacent--for example, if you are interested in the values 6229of pointers in an array. One useful work-around in this situation is 6230to use a convenience variable (*note Convenience Variables: Convenience 6231Vars.) as a counter in an expression that prints the first interesting 6232value, and then repeat that expression via <RET>. For instance, 6233suppose you have an array `dtab' of pointers to structures, and you are 6234interested in the values of a field `fv' in each structure. Here is an 6235example of what you might type: 6236 6237 set $i = 0 6238 p dtab[$i++]->fv 6239 <RET> 6240 <RET> 6241 ... 6242 6243 6244File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data 6245 624610.5 Output Formats 6247=================== 6248 6249By default, GDB prints a value according to its data type. Sometimes 6250this is not what you want. For example, you might want to print a 6251number in hex, or a pointer in decimal. Or you might want to view data 6252in memory at a certain address as a character string or as an 6253instruction. To do these things, specify an "output format" when you 6254print a value. 6255 6256 The simplest use of output formats is to say how to print a value 6257already computed. This is done by starting the arguments of the 6258`print' command with a slash and a format letter. The format letters 6259supported are: 6260 6261`x' 6262 Regard the bits of the value as an integer, and print the integer 6263 in hexadecimal. 6264 6265`d' 6266 Print as integer in signed decimal. 6267 6268`u' 6269 Print as integer in unsigned decimal. 6270 6271`o' 6272 Print as integer in octal. 6273 6274`t' 6275 Print as integer in binary. The letter `t' stands for "two". (1) 6276 6277`a' 6278 Print as an address, both absolute in hexadecimal and as an offset 6279 from the nearest preceding symbol. You can use this format used 6280 to discover where (in what function) an unknown address is located: 6281 6282 (gdb) p/a 0x54320 6283 $3 = 0x54320 <_initialize_vx+396> 6284 6285 The command `info symbol 0x54320' yields similar results. *Note 6286 info symbol: Symbols. 6287 6288`c' 6289 Regard as an integer and print it as a character constant. This 6290 prints both the numerical value and its character representation. 6291 The character representation is replaced with the octal escape 6292 `\nnn' for characters outside the 7-bit ASCII range. 6293 6294 Without this format, GDB displays `char', `unsigned char', and 6295 `signed char' data as character constants. Single-byte members of 6296 vectors are displayed as integer data. 6297 6298`f' 6299 Regard the bits of the value as a floating point number and print 6300 using typical floating point syntax. 6301 6302`s' 6303 Regard as a string, if possible. With this format, pointers to 6304 single-byte data are displayed as null-terminated strings and 6305 arrays of single-byte data are displayed as fixed-length strings. 6306 Other values are displayed in their natural types. 6307 6308 Without this format, GDB displays pointers to and arrays of 6309 `char', `unsigned char', and `signed char' as strings. 6310 Single-byte members of a vector are displayed as an integer array. 6311 6312`r' 6313 Print using the `raw' formatting. By default, GDB will use a 6314 Python-based pretty-printer, if one is available (*note Pretty 6315 Printing::). This typically results in a higher-level display of 6316 the value's contents. The `r' format bypasses any Python 6317 pretty-printer which might exist. 6318 6319 For example, to print the program counter in hex (*note 6320Registers::), type 6321 6322 p/x $pc 6323 6324Note that no space is required before the slash; this is because command 6325names in GDB cannot contain a slash. 6326 6327 To reprint the last value in the value history with a different 6328format, you can use the `print' command with just a format and no 6329expression. For example, `p/x' reprints the last value in hex. 6330 6331 ---------- Footnotes ---------- 6332 6333 (1) `b' cannot be used because these format letters are also used 6334with the `x' command, where `b' stands for "byte"; see *note Examining 6335Memory: Memory. 6336 6337 6338File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data 6339 634010.6 Examining Memory 6341===================== 6342 6343You can use the command `x' (for "examine") to examine memory in any of 6344several formats, independently of your program's data types. 6345 6346`x/NFU ADDR' 6347`x ADDR' 6348`x' 6349 Use the `x' command to examine memory. 6350 6351 N, F, and U are all optional parameters that specify how much memory 6352to display and how to format it; ADDR is an expression giving the 6353address where you want to start displaying memory. If you use defaults 6354for NFU, you need not type the slash `/'. Several commands set 6355convenient defaults for ADDR. 6356 6357N, the repeat count 6358 The repeat count is a decimal integer; the default is 1. It 6359 specifies how much memory (counting by units U) to display. 6360 6361F, the display format 6362 The display format is one of the formats used by `print' (`x', 6363 `d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for 6364 machine instructions). The default is `x' (hexadecimal) 6365 initially. The default changes each time you use either `x' or 6366 `print'. 6367 6368U, the unit size 6369 The unit size is any of 6370 6371 `b' 6372 Bytes. 6373 6374 `h' 6375 Halfwords (two bytes). 6376 6377 `w' 6378 Words (four bytes). This is the initial default. 6379 6380 `g' 6381 Giant words (eight bytes). 6382 6383 Each time you specify a unit size with `x', that size becomes the 6384 default unit the next time you use `x'. For the `i' format, the 6385 unit size is ignored and is normally not written. For the `s' 6386 format, the unit size defaults to `b', unless it is explicitly 6387 given. Use `x /hs' to display 16-bit char strings and `x /ws' to 6388 display 32-bit strings. The next use of `x /s' will again display 6389 8-bit strings. Note that the results depend on the programming 6390 language of the current compilation unit. If the language is C, 6391 the `s' modifier will use the UTF-16 encoding while `w' will use 6392 UTF-32. The encoding is set by the programming language and cannot 6393 be altered. 6394 6395ADDR, starting display address 6396 ADDR is the address where you want GDB to begin displaying memory. 6397 The expression need not have a pointer value (though it may); it 6398 is always interpreted as an integer address of a byte of memory. 6399 *Note Expressions: Expressions, for more information on 6400 expressions. The default for ADDR is usually just after the last 6401 address examined--but several other commands also set the default 6402 address: `info breakpoints' (to the address of the last breakpoint 6403 listed), `info line' (to the starting address of a line), and 6404 `print' (if you use it to display a value from memory). 6405 6406 For example, `x/3uh 0x54320' is a request to display three halfwords 6407(`h') of memory, formatted as unsigned decimal integers (`u'), starting 6408at address `0x54320'. `x/4xw $sp' prints the four words (`w') of 6409memory above the stack pointer (here, `$sp'; *note Registers: 6410Registers.) in hexadecimal (`x'). 6411 6412 Since the letters indicating unit sizes are all distinct from the 6413letters specifying output formats, you do not have to remember whether 6414unit size or format comes first; either order works. The output 6415specifications `4xw' and `4wx' mean exactly the same thing. (However, 6416the count N must come first; `wx4' does not work.) 6417 6418 Even though the unit size U is ignored for the formats `s' and `i', 6419you might still want to use a count N; for example, `3i' specifies that 6420you want to see three machine instructions, including any operands. 6421For convenience, especially when used with the `display' command, the 6422`i' format also prints branch delay slot instructions, if any, beyond 6423the count specified, which immediately follow the last instruction that 6424is within the count. The command `disassemble' gives an alternative 6425way of inspecting machine instructions; see *note Source and Machine 6426Code: Machine Code. 6427 6428 All the defaults for the arguments to `x' are designed to make it 6429easy to continue scanning memory with minimal specifications each time 6430you use `x'. For example, after you have inspected three machine 6431instructions with `x/3i ADDR', you can inspect the next seven with just 6432`x/7'. If you use <RET> to repeat the `x' command, the repeat count N 6433is used again; the other arguments default as for successive uses of 6434`x'. 6435 6436 When examining machine instructions, the instruction at current 6437program counter is shown with a `=>' marker. For example: 6438 6439 (gdb) x/5i $pc-6 6440 0x804837f <main+11>: mov %esp,%ebp 6441 0x8048381 <main+13>: push %ecx 6442 0x8048382 <main+14>: sub $0x4,%esp 6443 => 0x8048385 <main+17>: movl $0x8048460,(%esp) 6444 0x804838c <main+24>: call 0x80482d4 <puts@plt> 6445 6446 The addresses and contents printed by the `x' command are not saved 6447in the value history because there is often too much of them and they 6448would get in the way. Instead, GDB makes these values available for 6449subsequent use in expressions as values of the convenience variables 6450`$_' and `$__'. After an `x' command, the last address examined is 6451available for use in expressions in the convenience variable `$_'. The 6452contents of that address, as examined, are available in the convenience 6453variable `$__'. 6454 6455 If the `x' command has a repeat count, the address and contents saved 6456are from the last memory unit printed; this is not the same as the last 6457address printed if several units were printed on the last line of 6458output. 6459 6460 When you are debugging a program running on a remote target machine 6461(*note Remote Debugging::), you may wish to verify the program's image 6462in the remote machine's memory against the executable file you 6463downloaded to the target. The `compare-sections' command is provided 6464for such situations. 6465 6466`compare-sections [SECTION-NAME]' 6467 Compare the data of a loadable section SECTION-NAME in the 6468 executable file of the program being debugged with the same 6469 section in the remote machine's memory, and report any mismatches. 6470 With no arguments, compares all loadable sections. This command's 6471 availability depends on the target's support for the `"qCRC"' 6472 remote request. 6473 6474 6475File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data 6476 647710.7 Automatic Display 6478====================== 6479 6480If you find that you want to print the value of an expression frequently 6481(to see how it changes), you might want to add it to the "automatic 6482display list" so that GDB prints its value each time your program stops. 6483Each expression added to the list is given a number to identify it; to 6484remove an expression from the list, you specify that number. The 6485automatic display looks like this: 6486 6487 2: foo = 38 6488 3: bar[5] = (struct hack *) 0x3804 6489 6490This display shows item numbers, expressions and their current values. 6491As with displays you request manually using `x' or `print', you can 6492specify the output format you prefer; in fact, `display' decides 6493whether to use `print' or `x' depending your format specification--it 6494uses `x' if you specify either the `i' or `s' format, or a unit size; 6495otherwise it uses `print'. 6496 6497`display EXPR' 6498 Add the expression EXPR to the list of expressions to display each 6499 time your program stops. *Note Expressions: Expressions. 6500 6501 `display' does not repeat if you press <RET> again after using it. 6502 6503`display/FMT EXPR' 6504 For FMT specifying only a display format and not a size or count, 6505 add the expression EXPR to the auto-display list but arrange to 6506 display it each time in the specified format FMT. *Note Output 6507 Formats: Output Formats. 6508 6509`display/FMT ADDR' 6510 For FMT `i' or `s', or including a unit-size or a number of units, 6511 add the expression ADDR as a memory address to be examined each 6512 time your program stops. Examining means in effect doing `x/FMT 6513 ADDR'. *Note Examining Memory: Memory. 6514 6515 For example, `display/i $pc' can be helpful, to see the machine 6516instruction about to be executed each time execution stops (`$pc' is a 6517common name for the program counter; *note Registers: Registers.). 6518 6519`undisplay DNUMS...' 6520`delete display DNUMS...' 6521 Remove item numbers DNUMS from the list of expressions to display. 6522 6523 `undisplay' does not repeat if you press <RET> after using it. 6524 (Otherwise you would just get the error `No display number ...'.) 6525 6526`disable display DNUMS...' 6527 Disable the display of item numbers DNUMS. A disabled display 6528 item is not printed automatically, but is not forgotten. It may be 6529 enabled again later. 6530 6531`enable display DNUMS...' 6532 Enable display of item numbers DNUMS. It becomes effective once 6533 again in auto display of its expression, until you specify 6534 otherwise. 6535 6536`display' 6537 Display the current values of the expressions on the list, just as 6538 is done when your program stops. 6539 6540`info display' 6541 Print the list of expressions previously set up to display 6542 automatically, each one with its item number, but without showing 6543 the values. This includes disabled expressions, which are marked 6544 as such. It also includes expressions which would not be 6545 displayed right now because they refer to automatic variables not 6546 currently available. 6547 6548 If a display expression refers to local variables, then it does not 6549make sense outside the lexical context for which it was set up. Such an 6550expression is disabled when execution enters a context where one of its 6551variables is not defined. For example, if you give the command 6552`display last_char' while inside a function with an argument 6553`last_char', GDB displays this argument while your program continues to 6554stop inside that function. When it stops elsewhere--where there is no 6555variable `last_char'--the display is disabled automatically. The next 6556time your program stops where `last_char' is meaningful, you can enable 6557the display expression once again. 6558 6559 6560File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data 6561 656210.8 Print Settings 6563=================== 6564 6565GDB provides the following ways to control how arrays, structures, and 6566symbols are printed. 6567 6568These settings are useful for debugging programs in any language: 6569 6570`set print address' 6571`set print address on' 6572 GDB prints memory addresses showing the location of stack traces, 6573 structure values, pointer values, breakpoints, and so forth, even 6574 when it also displays the contents of those addresses. The default 6575 is `on'. For example, this is what a stack frame display looks 6576 like with `set print address on': 6577 6578 (gdb) f 6579 #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") 6580 at input.c:530 6581 530 if (lquote != def_lquote) 6582 6583`set print address off' 6584 Do not print addresses when displaying their contents. For 6585 example, this is the same stack frame displayed with `set print 6586 address off': 6587 6588 (gdb) set print addr off 6589 (gdb) f 6590 #0 set_quotes (lq="<<", rq=">>") at input.c:530 6591 530 if (lquote != def_lquote) 6592 6593 You can use `set print address off' to eliminate all machine 6594 dependent displays from the GDB interface. For example, with 6595 `print address off', you should get the same text for backtraces on 6596 all machines--whether or not they involve pointer arguments. 6597 6598`show print address' 6599 Show whether or not addresses are to be printed. 6600 6601 When GDB prints a symbolic address, it normally prints the closest 6602earlier symbol plus an offset. If that symbol does not uniquely 6603identify the address (for example, it is a name whose scope is a single 6604source file), you may need to clarify. One way to do this is with 6605`info line', for example `info line *0x4537'. Alternately, you can set 6606GDB to print the source file and line number when it prints a symbolic 6607address: 6608 6609`set print symbol-filename on' 6610 Tell GDB to print the source file name and line number of a symbol 6611 in the symbolic form of an address. 6612 6613`set print symbol-filename off' 6614 Do not print source file name and line number of a symbol. This 6615 is the default. 6616 6617`show print symbol-filename' 6618 Show whether or not GDB will print the source file name and line 6619 number of a symbol in the symbolic form of an address. 6620 6621 Another situation where it is helpful to show symbol filenames and 6622line numbers is when disassembling code; GDB shows you the line number 6623and source file that corresponds to each instruction. 6624 6625 Also, you may wish to see the symbolic form only if the address being 6626printed is reasonably close to the closest earlier symbol: 6627 6628`set print max-symbolic-offset MAX-OFFSET' 6629 Tell GDB to only display the symbolic form of an address if the 6630 offset between the closest earlier symbol and the address is less 6631 than MAX-OFFSET. The default is 0, which tells GDB to always 6632 print the symbolic form of an address if any symbol precedes it. 6633 6634`show print max-symbolic-offset' 6635 Ask how large the maximum offset is that GDB prints in a symbolic 6636 address. 6637 6638 If you have a pointer and you are not sure where it points, try `set 6639print symbol-filename on'. Then you can determine the name and source 6640file location of the variable where it points, using `p/a POINTER'. 6641This interprets the address in symbolic form. For example, here GDB 6642shows that a variable `ptt' points at another variable `t', defined in 6643`hi2.c': 6644 6645 (gdb) set print symbol-filename on 6646 (gdb) p/a ptt 6647 $4 = 0xe008 <t in hi2.c> 6648 6649 _Warning:_ For pointers that point to a local variable, `p/a' does 6650 not show the symbol name and filename of the referent, even with 6651 the appropriate `set print' options turned on. 6652 6653 Other settings control how different kinds of objects are printed: 6654 6655`set print array' 6656`set print array on' 6657 Pretty print arrays. This format is more convenient to read, but 6658 uses more space. The default is off. 6659 6660`set print array off' 6661 Return to compressed format for arrays. 6662 6663`show print array' 6664 Show whether compressed or pretty format is selected for displaying 6665 arrays. 6666 6667`set print array-indexes' 6668`set print array-indexes on' 6669 Print the index of each element when displaying arrays. May be 6670 more convenient to locate a given element in the array or quickly 6671 find the index of a given element in that printed array. The 6672 default is off. 6673 6674`set print array-indexes off' 6675 Stop printing element indexes when displaying arrays. 6676 6677`show print array-indexes' 6678 Show whether the index of each element is printed when displaying 6679 arrays. 6680 6681`set print elements NUMBER-OF-ELEMENTS' 6682 Set a limit on how many elements of an array GDB will print. If 6683 GDB is printing a large array, it stops printing after it has 6684 printed the number of elements set by the `set print elements' 6685 command. This limit also applies to the display of strings. When 6686 GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS 6687 to zero means that the printing is unlimited. 6688 6689`show print elements' 6690 Display the number of elements of a large array that GDB will 6691 print. If the number is 0, then the printing is unlimited. 6692 6693`set print frame-arguments VALUE' 6694 This command allows to control how the values of arguments are 6695 printed when the debugger prints a frame (*note Frames::). The 6696 possible values are: 6697 6698 `all' 6699 The values of all arguments are printed. 6700 6701 `scalars' 6702 Print the value of an argument only if it is a scalar. The 6703 value of more complex arguments such as arrays, structures, 6704 unions, etc, is replaced by `...'. This is the default. 6705 Here is an example where only scalar arguments are shown: 6706 6707 #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) 6708 at frame-args.c:23 6709 6710 `none' 6711 None of the argument values are printed. Instead, the value 6712 of each argument is replaced by `...'. In this case, the 6713 example above now becomes: 6714 6715 #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) 6716 at frame-args.c:23 6717 6718 By default, only scalar arguments are printed. This command can 6719 be used to configure the debugger to print the value of all 6720 arguments, regardless of their type. However, it is often 6721 advantageous to not print the value of more complex parameters. 6722 For instance, it reduces the amount of information printed in each 6723 frame, making the backtrace more readable. Also, it improves 6724 performance when displaying Ada frames, because the computation of 6725 large arguments can sometimes be CPU-intensive, especially in 6726 large applications. Setting `print frame-arguments' to `scalars' 6727 (the default) or `none' avoids this computation, thus speeding up 6728 the display of each Ada frame. 6729 6730`show print frame-arguments' 6731 Show how the value of arguments should be displayed when printing 6732 a frame. 6733 6734`set print repeats' 6735 Set the threshold for suppressing display of repeated array 6736 elements. When the number of consecutive identical elements of an 6737 array exceeds the threshold, GDB prints the string `"<repeats N 6738 times>"', where N is the number of identical repetitions, instead 6739 of displaying the identical elements themselves. Setting the 6740 threshold to zero will cause all elements to be individually 6741 printed. The default threshold is 10. 6742 6743`show print repeats' 6744 Display the current threshold for printing repeated identical 6745 elements. 6746 6747`set print null-stop' 6748 Cause GDB to stop printing the characters of an array when the 6749 first NULL is encountered. This is useful when large arrays 6750 actually contain only short strings. The default is off. 6751 6752`show print null-stop' 6753 Show whether GDB stops printing an array on the first NULL 6754 character. 6755 6756`set print pretty on' 6757 Cause GDB to print structures in an indented format with one member 6758 per line, like this: 6759 6760 $1 = { 6761 next = 0x0, 6762 flags = { 6763 sweet = 1, 6764 sour = 1 6765 }, 6766 meat = 0x54 "Pork" 6767 } 6768 6769`set print pretty off' 6770 Cause GDB to print structures in a compact format, like this: 6771 6772 $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ 6773 meat = 0x54 "Pork"} 6774 6775 This is the default format. 6776 6777`show print pretty' 6778 Show which format GDB is using to print structures. 6779 6780`set print sevenbit-strings on' 6781 Print using only seven-bit characters; if this option is set, GDB 6782 displays any eight-bit characters (in strings or character values) 6783 using the notation `\'NNN. This setting is best if you are 6784 working in English (ASCII) and you use the high-order bit of 6785 characters as a marker or "meta" bit. 6786 6787`set print sevenbit-strings off' 6788 Print full eight-bit characters. This allows the use of more 6789 international character sets, and is the default. 6790 6791`show print sevenbit-strings' 6792 Show whether or not GDB is printing only seven-bit characters. 6793 6794`set print union on' 6795 Tell GDB to print unions which are contained in structures and 6796 other unions. This is the default setting. 6797 6798`set print union off' 6799 Tell GDB not to print unions which are contained in structures and 6800 other unions. GDB will print `"{...}"' instead. 6801 6802`show print union' 6803 Ask GDB whether or not it will print unions which are contained in 6804 structures and other unions. 6805 6806 For example, given the declarations 6807 6808 typedef enum {Tree, Bug} Species; 6809 typedef enum {Big_tree, Acorn, Seedling} Tree_forms; 6810 typedef enum {Caterpillar, Cocoon, Butterfly} 6811 Bug_forms; 6812 6813 struct thing { 6814 Species it; 6815 union { 6816 Tree_forms tree; 6817 Bug_forms bug; 6818 } form; 6819 }; 6820 6821 struct thing foo = {Tree, {Acorn}}; 6822 6823 with `set print union on' in effect `p foo' would print 6824 6825 $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} 6826 6827 and with `set print union off' in effect it would print 6828 6829 $1 = {it = Tree, form = {...}} 6830 6831 `set print union' affects programs written in C-like languages and 6832 in Pascal. 6833 6834These settings are of interest when debugging C++ programs: 6835 6836`set print demangle' 6837`set print demangle on' 6838 Print C++ names in their source form rather than in the encoded 6839 ("mangled") form passed to the assembler and linker for type-safe 6840 linkage. The default is on. 6841 6842`show print demangle' 6843 Show whether C++ names are printed in mangled or demangled form. 6844 6845`set print asm-demangle' 6846`set print asm-demangle on' 6847 Print C++ names in their source form rather than their mangled 6848 form, even in assembler code printouts such as instruction 6849 disassemblies. The default is off. 6850 6851`show print asm-demangle' 6852 Show whether C++ names in assembly listings are printed in mangled 6853 or demangled form. 6854 6855`set demangle-style STYLE' 6856 Choose among several encoding schemes used by different compilers 6857 to represent C++ names. The choices for STYLE are currently: 6858 6859 `auto' 6860 Allow GDB to choose a decoding style by inspecting your 6861 program. 6862 6863 `gnu' 6864 Decode based on the GNU C++ compiler (`g++') encoding 6865 algorithm. This is the default. 6866 6867 `hp' 6868 Decode based on the HP ANSI C++ (`aCC') encoding algorithm. 6869 6870 `lucid' 6871 Decode based on the Lucid C++ compiler (`lcc') encoding 6872 algorithm. 6873 6874 `arm' 6875 Decode using the algorithm in the `C++ Annotated Reference 6876 Manual'. *Warning:* this setting alone is not sufficient to 6877 allow debugging `cfront'-generated executables. GDB would 6878 require further enhancement to permit that. 6879 6880 If you omit STYLE, you will see a list of possible formats. 6881 6882`show demangle-style' 6883 Display the encoding style currently in use for decoding C++ 6884 symbols. 6885 6886`set print object' 6887`set print object on' 6888 When displaying a pointer to an object, identify the _actual_ 6889 (derived) type of the object rather than the _declared_ type, using 6890 the virtual function table. 6891 6892`set print object off' 6893 Display only the declared type of objects, without reference to the 6894 virtual function table. This is the default setting. 6895 6896`show print object' 6897 Show whether actual, or declared, object types are displayed. 6898 6899`set print static-members' 6900`set print static-members on' 6901 Print static members when displaying a C++ object. The default is 6902 on. 6903 6904`set print static-members off' 6905 Do not print static members when displaying a C++ object. 6906 6907`show print static-members' 6908 Show whether C++ static members are printed or not. 6909 6910`set print pascal_static-members' 6911`set print pascal_static-members on' 6912 Print static members when displaying a Pascal object. The default 6913 is on. 6914 6915`set print pascal_static-members off' 6916 Do not print static members when displaying a Pascal object. 6917 6918`show print pascal_static-members' 6919 Show whether Pascal static members are printed or not. 6920 6921`set print vtbl' 6922`set print vtbl on' 6923 Pretty print C++ virtual function tables. The default is off. 6924 (The `vtbl' commands do not work on programs compiled with the HP 6925 ANSI C++ compiler (`aCC').) 6926 6927`set print vtbl off' 6928 Do not pretty print C++ virtual function tables. 6929 6930`show print vtbl' 6931 Show whether C++ virtual function tables are pretty printed, or 6932 not. 6933 6934 6935File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data 6936 693710.9 Pretty Printing 6938==================== 6939 6940GDB provides a mechanism to allow pretty-printing of values using 6941Python code. It greatly simplifies the display of complex objects. 6942This mechanism works for both MI and the CLI. 6943 6944 For example, here is how a C++ `std::string' looks without a 6945pretty-printer: 6946 6947 (gdb) print s 6948 $1 = { 6949 static npos = 4294967295, 6950 _M_dataplus = { 6951 <std::allocator<char>> = { 6952 <__gnu_cxx::new_allocator<char>> = { 6953 <No data fields>}, <No data fields> 6954 }, 6955 members of std::basic_string<char, std::char_traits<char>, 6956 std::allocator<char> >::_Alloc_hider: 6957 _M_p = 0x804a014 "abcd" 6958 } 6959 } 6960 6961 With a pretty-printer for `std::string' only the contents are 6962printed: 6963 6964 (gdb) print s 6965 $2 = "abcd" 6966 6967 For implementing pretty printers for new types you should read the 6968Python API details (*note Pretty Printing API::). 6969 6970 6971File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data 6972 697310.10 Value History 6974=================== 6975 6976Values printed by the `print' command are saved in the GDB "value 6977history". This allows you to refer to them in other expressions. 6978Values are kept until the symbol table is re-read or discarded (for 6979example with the `file' or `symbol-file' commands). When the symbol 6980table changes, the value history is discarded, since the values may 6981contain pointers back to the types defined in the symbol table. 6982 6983 The values printed are given "history numbers" by which you can 6984refer to them. These are successive integers starting with one. 6985`print' shows you the history number assigned to a value by printing 6986`$NUM = ' before the value; here NUM is the history number. 6987 6988 To refer to any previous value, use `$' followed by the value's 6989history number. The way `print' labels its output is designed to 6990remind you of this. Just `$' refers to the most recent value in the 6991history, and `$$' refers to the value before that. `$$N' refers to the 6992Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is 6993equivalent to `$$', and `$$0' is equivalent to `$'. 6994 6995 For example, suppose you have just printed a pointer to a structure 6996and want to see the contents of the structure. It suffices to type 6997 6998 p *$ 6999 7000 If you have a chain of structures where the component `next' points 7001to the next one, you can print the contents of the next one with this: 7002 7003 p *$.next 7004 7005You can print successive links in the chain by repeating this 7006command--which you can do by just typing <RET>. 7007 7008 Note that the history records values, not expressions. If the value 7009of `x' is 4 and you type these commands: 7010 7011 print x 7012 set x=5 7013 7014then the value recorded in the value history by the `print' command 7015remains 4 even though the value of `x' has changed. 7016 7017`show values' 7018 Print the last ten values in the value history, with their item 7019 numbers. This is like `p $$9' repeated ten times, except that 7020 `show values' does not change the history. 7021 7022`show values N' 7023 Print ten history values centered on history item number N. 7024 7025`show values +' 7026 Print ten history values just after the values last printed. If 7027 no more values are available, `show values +' produces no display. 7028 7029 Pressing <RET> to repeat `show values N' has exactly the same effect 7030as `show values +'. 7031 7032 7033File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data 7034 703510.11 Convenience Variables 7036=========================== 7037 7038GDB provides "convenience variables" that you can use within GDB to 7039hold on to a value and refer to it later. These variables exist 7040entirely within GDB; they are not part of your program, and setting a 7041convenience variable has no direct effect on further execution of your 7042program. That is why you can use them freely. 7043 7044 Convenience variables are prefixed with `$'. Any name preceded by 7045`$' can be used for a convenience variable, unless it is one of the 7046predefined machine-specific register names (*note Registers: 7047Registers.). (Value history references, in contrast, are _numbers_ 7048preceded by `$'. *Note Value History: Value History.) 7049 7050 You can save a value in a convenience variable with an assignment 7051expression, just as you would set a variable in your program. For 7052example: 7053 7054 set $foo = *object_ptr 7055 7056would save in `$foo' the value contained in the object pointed to by 7057`object_ptr'. 7058 7059 Using a convenience variable for the first time creates it, but its 7060value is `void' until you assign a new value. You can alter the value 7061with another assignment at any time. 7062 7063 Convenience variables have no fixed types. You can assign a 7064convenience variable any type of value, including structures and 7065arrays, even if that variable already has a value of a different type. 7066The convenience variable, when used as an expression, has the type of 7067its current value. 7068 7069`show convenience' 7070 Print a list of convenience variables used so far, and their 7071 values. Abbreviated `show conv'. 7072 7073`init-if-undefined $VARIABLE = EXPRESSION' 7074 Set a convenience variable if it has not already been set. This 7075 is useful for user-defined commands that keep some state. It is 7076 similar, in concept, to using local static variables with 7077 initializers in C (except that convenience variables are global). 7078 It can also be used to allow users to override default values used 7079 in a command script. 7080 7081 If the variable is already defined then the expression is not 7082 evaluated so any side-effects do not occur. 7083 7084 One of the ways to use a convenience variable is as a counter to be 7085incremented or a pointer to be advanced. For example, to print a field 7086from successive elements of an array of structures: 7087 7088 set $i = 0 7089 print bar[$i++]->contents 7090 7091Repeat that command by typing <RET>. 7092 7093 Some convenience variables are created automatically by GDB and given 7094values likely to be useful. 7095 7096`$_' 7097 The variable `$_' is automatically set by the `x' command to the 7098 last address examined (*note Examining Memory: Memory.). Other 7099 commands which provide a default address for `x' to examine also 7100 set `$_' to that address; these commands include `info line' and 7101 `info breakpoint'. The type of `$_' is `void *' except when set 7102 by the `x' command, in which case it is a pointer to the type of 7103 `$__'. 7104 7105`$__' 7106 The variable `$__' is automatically set by the `x' command to the 7107 value found in the last address examined. Its type is chosen to 7108 match the format in which the data was printed. 7109 7110`$_exitcode' 7111 The variable `$_exitcode' is automatically set to the exit code 7112 when the program being debugged terminates. 7113 7114`$_sdata' 7115 The variable `$_sdata' contains extra collected static tracepoint 7116 data. *Note Tracepoint Action Lists: Tracepoint Actions. Note 7117 that `$_sdata' could be empty, if not inspecting a trace buffer, or 7118 if extra static tracepoint data has not been collected. 7119 7120`$_siginfo' 7121 The variable `$_siginfo' contains extra signal information (*note 7122 extra signal information::). Note that `$_siginfo' could be 7123 empty, if the application has not yet received any signals. For 7124 example, it will be empty before you execute the `run' command. 7125 7126`$_tlb' 7127 The variable `$_tlb' is automatically set when debugging 7128 applications running on MS-Windows in native mode or connected to 7129 gdbserver that supports the `qGetTIBAddr' request. *Note General 7130 Query Packets::. This variable contains the address of the thread 7131 information block. 7132 7133 7134 On HP-UX systems, if you refer to a function or variable name that 7135begins with a dollar sign, GDB searches for a user or system name 7136first, before it searches for a convenience variable. 7137 7138 GDB also supplies some "convenience functions". These have a syntax 7139similar to convenience variables. A convenience function can be used 7140in an expression just like an ordinary function; however, a convenience 7141function is implemented internally to GDB. 7142 7143`help function' 7144 Print a list of all convenience functions. 7145 7146 7147File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data 7148 714910.12 Registers 7150=============== 7151 7152You can refer to machine register contents, in expressions, as variables 7153with names starting with `$'. The names of registers are different for 7154each machine; use `info registers' to see the names used on your 7155machine. 7156 7157`info registers' 7158 Print the names and values of all registers except floating-point 7159 and vector registers (in the selected stack frame). 7160 7161`info all-registers' 7162 Print the names and values of all registers, including 7163 floating-point and vector registers (in the selected stack frame). 7164 7165`info registers REGNAME ...' 7166 Print the "relativized" value of each specified register REGNAME. 7167 As discussed in detail below, register values are normally 7168 relative to the selected stack frame. REGNAME may be any register 7169 name valid on the machine you are using, with or without the 7170 initial `$'. 7171 7172 GDB has four "standard" register names that are available (in 7173expressions) on most machines--whenever they do not conflict with an 7174architecture's canonical mnemonics for registers. The register names 7175`$pc' and `$sp' are used for the program counter register and the stack 7176pointer. `$fp' is used for a register that contains a pointer to the 7177current stack frame, and `$ps' is used for a register that contains the 7178processor status. For example, you could print the program counter in 7179hex with 7180 7181 p/x $pc 7182 7183or print the instruction to be executed next with 7184 7185 x/i $pc 7186 7187or add four to the stack pointer(1) with 7188 7189 set $sp += 4 7190 7191 Whenever possible, these four standard register names are available 7192on your machine even though the machine has different canonical 7193mnemonics, so long as there is no conflict. The `info registers' 7194command shows the canonical names. For example, on the SPARC, `info 7195registers' displays the processor status register as `$psr' but you can 7196also refer to it as `$ps'; and on x86-based machines `$ps' is an alias 7197for the EFLAGS register. 7198 7199 GDB always considers the contents of an ordinary register as an 7200integer when the register is examined in this way. Some machines have 7201special registers which can hold nothing but floating point; these 7202registers are considered to have floating point values. There is no way 7203to refer to the contents of an ordinary register as floating point value 7204(although you can _print_ it as a floating point value with `print/f 7205$REGNAME'). 7206 7207 Some registers have distinct "raw" and "virtual" data formats. This 7208means that the data format in which the register contents are saved by 7209the operating system is not the same one that your program normally 7210sees. For example, the registers of the 68881 floating point 7211coprocessor are always saved in "extended" (raw) format, but all C 7212programs expect to work with "double" (virtual) format. In such cases, 7213GDB normally works with the virtual format only (the format that makes 7214sense for your program), but the `info registers' command prints the 7215data in both formats. 7216 7217 Some machines have special registers whose contents can be 7218interpreted in several different ways. For example, modern x86-based 7219machines have SSE and MMX registers that can hold several values packed 7220together in several different formats. GDB refers to such registers in 7221`struct' notation: 7222 7223 (gdb) print $xmm1 7224 $1 = { 7225 v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044}, 7226 v2_double = {9.92129282474342e-303, 2.7585945287983262e-313}, 7227 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", 7228 v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0}, 7229 v4_int32 = {0, 20657912, 11, 13}, 7230 v2_int64 = {88725056443645952, 55834574859}, 7231 uint128 = 0x0000000d0000000b013b36f800000000 7232 } 7233 7234To set values of such registers, you need to tell GDB which view of the 7235register you wish to change, as if you were assigning value to a 7236`struct' member: 7237 7238 (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF 7239 7240 Normally, register values are relative to the selected stack frame 7241(*note Selecting a Frame: Selection.). This means that you get the 7242value that the register would contain if all stack frames farther in 7243were exited and their saved registers restored. In order to see the 7244true contents of hardware registers, you must select the innermost 7245frame (with `frame 0'). 7246 7247 However, GDB must deduce where registers are saved, from the machine 7248code generated by your compiler. If some registers are not saved, or if 7249GDB is unable to locate the saved registers, the selected stack frame 7250makes no difference. 7251 7252 ---------- Footnotes ---------- 7253 7254 (1) This is a way of removing one word from the stack, on machines 7255where stacks grow downward in memory (most machines, nowadays). This 7256assumes that the innermost stack frame is selected; setting `$sp' is 7257not allowed when other stack frames are selected. To pop entire frames 7258off the stack, regardless of machine architecture, use `return'; see 7259*note Returning from a Function: Returning. 7260 7261 7262File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data 7263 726410.13 Floating Point Hardware 7265============================= 7266 7267Depending on the configuration, GDB may be able to give you more 7268information about the status of the floating point hardware. 7269 7270`info float' 7271 Display hardware-dependent information about the floating point 7272 unit. The exact contents and layout vary depending on the 7273 floating point chip. Currently, `info float' is supported on the 7274 ARM and x86 machines. 7275 7276 7277File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data 7278 727910.14 Vector Unit 7280================= 7281 7282Depending on the configuration, GDB may be able to give you more 7283information about the status of the vector unit. 7284 7285`info vector' 7286 Display information about the vector unit. The exact contents and 7287 layout vary depending on the hardware. 7288 7289 7290File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data 7291 729210.15 Operating System Auxiliary Information 7293============================================ 7294 7295GDB provides interfaces to useful OS facilities that can help you debug 7296your program. 7297 7298 When GDB runs on a "Posix system" (such as GNU or Unix machines), it 7299interfaces with the inferior via the `ptrace' system call. The 7300operating system creates a special sata structure, called `struct 7301user', for this interface. You can use the command `info udot' to 7302display the contents of this data structure. 7303 7304`info udot' 7305 Display the contents of the `struct user' maintained by the OS 7306 kernel for the program being debugged. GDB displays the contents 7307 of `struct user' as a list of hex numbers, similar to the 7308 `examine' command. 7309 7310 Some operating systems supply an "auxiliary vector" to programs at 7311startup. This is akin to the arguments and environment that you 7312specify for a program, but contains a system-dependent variety of 7313binary values that tell system libraries important details about the 7314hardware, operating system, and process. Each value's purpose is 7315identified by an integer tag; the meanings are well-known but 7316system-specific. Depending on the configuration and operating system 7317facilities, GDB may be able to show you this information. For remote 7318targets, this functionality may further depend on the remote stub's 7319support of the `qXfer:auxv:read' packet, see *note qXfer auxiliary 7320vector read::. 7321 7322`info auxv' 7323 Display the auxiliary vector of the inferior, which can be either a 7324 live process or a core dump file. GDB prints each tag value 7325 numerically, and also shows names and text descriptions for 7326 recognized tags. Some values in the vector are numbers, some bit 7327 masks, and some pointers to strings or other data. GDB displays 7328 each value in the most appropriate form for a recognized tag, and 7329 in hexadecimal for an unrecognized tag. 7330 7331 On some targets, GDB can access operating-system-specific information 7332and display it to user, without interpretation. For remote targets, 7333this functionality depends on the remote stub's support of the 7334`qXfer:osdata:read' packet, see *note qXfer osdata read::. 7335 7336`info os' 7337 List the types of OS information available for the target. If the 7338 target does not return a list of possible types, this command will 7339 report an error. 7340 7341`info os processes' 7342 Display the list of processes on the target. For each process, 7343 GDB prints the process identifier, the name of the user, and the 7344 command corresponding to the process. 7345 7346 7347File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data 7348 734910.16 Memory Region Attributes 7350============================== 7351 7352"Memory region attributes" allow you to describe special handling 7353required by regions of your target's memory. GDB uses attributes to 7354determine whether to allow certain types of memory accesses; whether to 7355use specific width accesses; and whether to cache target memory. By 7356default the description of memory regions is fetched from the target 7357(if the current target supports this), but the user can override the 7358fetched regions. 7359 7360 Defined memory regions can be individually enabled and disabled. 7361When a memory region is disabled, GDB uses the default attributes when 7362accessing memory in that region. Similarly, if no memory regions have 7363been defined, GDB uses the default attributes when accessing all memory. 7364 7365 When a memory region is defined, it is given a number to identify it; 7366to enable, disable, or remove a memory region, you specify that number. 7367 7368`mem LOWER UPPER ATTRIBUTES...' 7369 Define a memory region bounded by LOWER and UPPER with attributes 7370 ATTRIBUTES..., and add it to the list of regions monitored by GDB. 7371 Note that UPPER == 0 is a special case: it is treated as the 7372 target's maximum memory address. (0xffff on 16 bit targets, 7373 0xffffffff on 32 bit targets, etc.) 7374 7375`mem auto' 7376 Discard any user changes to the memory regions and use 7377 target-supplied regions, if available, or no regions if the target 7378 does not support. 7379 7380`delete mem NUMS...' 7381 Remove memory regions NUMS... from the list of regions monitored 7382 by GDB. 7383 7384`disable mem NUMS...' 7385 Disable monitoring of memory regions NUMS.... A disabled memory 7386 region is not forgotten. It may be enabled again later. 7387 7388`enable mem NUMS...' 7389 Enable monitoring of memory regions NUMS.... 7390 7391`info mem' 7392 Print a table of all defined memory regions, with the following 7393 columns for each region: 7394 7395 _Memory Region Number_ 7396 7397 _Enabled or Disabled._ 7398 Enabled memory regions are marked with `y'. Disabled memory 7399 regions are marked with `n'. 7400 7401 _Lo Address_ 7402 The address defining the inclusive lower bound of the memory 7403 region. 7404 7405 _Hi Address_ 7406 The address defining the exclusive upper bound of the memory 7407 region. 7408 7409 _Attributes_ 7410 The list of attributes set for this memory region. 7411 741210.16.1 Attributes 7413------------------ 7414 741510.16.1.1 Memory Access Mode 7416............................ 7417 7418The access mode attributes set whether GDB may make read or write 7419accesses to a memory region. 7420 7421 While these attributes prevent GDB from performing invalid memory 7422accesses, they do nothing to prevent the target system, I/O DMA, etc. 7423from accessing memory. 7424 7425`ro' 7426 Memory is read only. 7427 7428`wo' 7429 Memory is write only. 7430 7431`rw' 7432 Memory is read/write. This is the default. 7433 743410.16.1.2 Memory Access Size 7435............................ 7436 7437The access size attribute tells GDB to use specific sized accesses in 7438the memory region. Often memory mapped device registers require 7439specific sized accesses. If no access size attribute is specified, GDB 7440may use accesses of any size. 7441 7442`8' 7443 Use 8 bit memory accesses. 7444 7445`16' 7446 Use 16 bit memory accesses. 7447 7448`32' 7449 Use 32 bit memory accesses. 7450 7451`64' 7452 Use 64 bit memory accesses. 7453 745410.16.1.3 Data Cache 7455.................... 7456 7457The data cache attributes set whether GDB will cache target memory. 7458While this generally improves performance by reducing debug protocol 7459overhead, it can lead to incorrect results because GDB does not know 7460about volatile variables or memory mapped device registers. 7461 7462`cache' 7463 Enable GDB to cache target memory. 7464 7465`nocache' 7466 Disable GDB from caching target memory. This is the default. 7467 746810.16.2 Memory Access Checking 7469------------------------------ 7470 7471GDB can be instructed to refuse accesses to memory that is not 7472explicitly described. This can be useful if accessing such regions has 7473undesired effects for a specific target, or to provide better error 7474checking. The following commands control this behaviour. 7475 7476`set mem inaccessible-by-default [on|off]' 7477 If `on' is specified, make GDB treat memory not explicitly 7478 described by the memory ranges as non-existent and refuse accesses 7479 to such memory. The checks are only performed if there's at least 7480 one memory range defined. If `off' is specified, make GDB treat 7481 the memory not explicitly described by the memory ranges as RAM. 7482 The default value is `on'. 7483 7484`show mem inaccessible-by-default' 7485 Show the current handling of accesses to unknown memory. 7486 7487 7488File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data 7489 749010.17 Copy Between Memory and a File 7491==================================== 7492 7493You can use the commands `dump', `append', and `restore' to copy data 7494between target memory and a file. The `dump' and `append' commands 7495write data to a file, and the `restore' command reads data from a file 7496back into the inferior's memory. Files may be in binary, Motorola 7497S-record, Intel hex, or Tektronix Hex format; however, GDB can only 7498append to binary files. 7499 7500`dump [FORMAT] memory FILENAME START_ADDR END_ADDR' 7501`dump [FORMAT] value FILENAME EXPR' 7502 Dump the contents of memory from START_ADDR to END_ADDR, or the 7503 value of EXPR, to FILENAME in the given format. 7504 7505 The FORMAT parameter may be any one of: 7506 `binary' 7507 Raw binary form. 7508 7509 `ihex' 7510 Intel hex format. 7511 7512 `srec' 7513 Motorola S-record format. 7514 7515 `tekhex' 7516 Tektronix Hex format. 7517 7518 GDB uses the same definitions of these formats as the GNU binary 7519 utilities, like `objdump' and `objcopy'. If FORMAT is omitted, 7520 GDB dumps the data in raw binary form. 7521 7522`append [binary] memory FILENAME START_ADDR END_ADDR' 7523`append [binary] value FILENAME EXPR' 7524 Append the contents of memory from START_ADDR to END_ADDR, or the 7525 value of EXPR, to the file FILENAME, in raw binary form. (GDB can 7526 only append data to files in raw binary form.) 7527 7528`restore FILENAME [binary] BIAS START END' 7529 Restore the contents of file FILENAME into memory. The `restore' 7530 command can automatically recognize any known BFD file format, 7531 except for raw binary. To restore a raw binary file you must 7532 specify the optional keyword `binary' after the filename. 7533 7534 If BIAS is non-zero, its value will be added to the addresses 7535 contained in the file. Binary files always start at address zero, 7536 so they will be restored at address BIAS. Other bfd files have a 7537 built-in location; they will be restored at offset BIAS from that 7538 location. 7539 7540 If START and/or END are non-zero, then only data between file 7541 offset START and file offset END will be restored. These offsets 7542 are relative to the addresses in the file, before the BIAS 7543 argument is applied. 7544 7545 7546 7547File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data 7548 754910.18 How to Produce a Core File from Your Program 7550================================================== 7551 7552A "core file" or "core dump" is a file that records the memory image of 7553a running process and its process status (register values etc.). Its 7554primary use is post-mortem debugging of a program that crashed while it 7555ran outside a debugger. A program that crashes automatically produces 7556a core file, unless this feature is disabled by the user. *Note 7557Files::, for information on invoking GDB in the post-mortem debugging 7558mode. 7559 7560 Occasionally, you may wish to produce a core file of the program you 7561are debugging in order to preserve a snapshot of its state. GDB has a 7562special command for that. 7563 7564`generate-core-file [FILE]' 7565`gcore [FILE]' 7566 Produce a core dump of the inferior process. The optional argument 7567 FILE specifies the file name where to put the core dump. If not 7568 specified, the file name defaults to `core.PID', where PID is the 7569 inferior process ID. 7570 7571 Note that this command is implemented only for some systems (as of 7572 this writing, GNU/Linux, FreeBSD, Solaris, Unixware, and S390). 7573 7574 7575File: gdb.info, Node: Character Sets, Next: Caching Remote Data, Prev: Core File Generation, Up: Data 7576 757710.19 Character Sets 7578==================== 7579 7580If the program you are debugging uses a different character set to 7581represent characters and strings than the one GDB uses itself, GDB can 7582automatically translate between the character sets for you. The 7583character set GDB uses we call the "host character set"; the one the 7584inferior program uses we call the "target character set". 7585 7586 For example, if you are running GDB on a GNU/Linux system, which 7587uses the ISO Latin 1 character set, but you are using GDB's remote 7588protocol (*note Remote Debugging::) to debug a program running on an 7589IBM mainframe, which uses the EBCDIC character set, then the host 7590character set is Latin-1, and the target character set is EBCDIC. If 7591you give GDB the command `set target-charset EBCDIC-US', then GDB 7592translates between EBCDIC and Latin 1 as you print character or string 7593values, or use character and string literals in expressions. 7594 7595 GDB has no way to automatically recognize which character set the 7596inferior program uses; you must tell it, using the `set target-charset' 7597command, described below. 7598 7599 Here are the commands for controlling GDB's character set support: 7600 7601`set target-charset CHARSET' 7602 Set the current target character set to CHARSET. To display the 7603 list of supported target character sets, type 7604 `set target-charset <TAB><TAB>'. 7605 7606`set host-charset CHARSET' 7607 Set the current host character set to CHARSET. 7608 7609 By default, GDB uses a host character set appropriate to the 7610 system it is running on; you can override that default using the 7611 `set host-charset' command. On some systems, GDB cannot 7612 automatically determine the appropriate host character set. In 7613 this case, GDB uses `UTF-8'. 7614 7615 GDB can only use certain character sets as its host character set. 7616 If you type `set target-charset <TAB><TAB>', GDB will list the 7617 host character sets it supports. 7618 7619`set charset CHARSET' 7620 Set the current host and target character sets to CHARSET. As 7621 above, if you type `set charset <TAB><TAB>', GDB will list the 7622 names of the character sets that can be used for both host and 7623 target. 7624 7625`show charset' 7626 Show the names of the current host and target character sets. 7627 7628`show host-charset' 7629 Show the name of the current host character set. 7630 7631`show target-charset' 7632 Show the name of the current target character set. 7633 7634`set target-wide-charset CHARSET' 7635 Set the current target's wide character set to CHARSET. This is 7636 the character set used by the target's `wchar_t' type. To display 7637 the list of supported wide character sets, type 7638 `set target-wide-charset <TAB><TAB>'. 7639 7640`show target-wide-charset' 7641 Show the name of the current target's wide character set. 7642 7643 Here is an example of GDB's character set support in action. Assume 7644that the following source code has been placed in the file 7645`charset-test.c': 7646 7647 #include <stdio.h> 7648 7649 char ascii_hello[] 7650 = {72, 101, 108, 108, 111, 44, 32, 119, 7651 111, 114, 108, 100, 33, 10, 0}; 7652 char ibm1047_hello[] 7653 = {200, 133, 147, 147, 150, 107, 64, 166, 7654 150, 153, 147, 132, 90, 37, 0}; 7655 7656 main () 7657 { 7658 printf ("Hello, world!\n"); 7659 } 7660 7661 In this program, `ascii_hello' and `ibm1047_hello' are arrays 7662containing the string `Hello, world!' followed by a newline, encoded in 7663the ASCII and IBM1047 character sets. 7664 7665 We compile the program, and invoke the debugger on it: 7666 7667 $ gcc -g charset-test.c -o charset-test 7668 $ gdb -nw charset-test 7669 GNU gdb 2001-12-19-cvs 7670 Copyright 2001 Free Software Foundation, Inc. 7671 ... 7672 (gdb) 7673 7674 We can use the `show charset' command to see what character sets GDB 7675is currently using to interpret and display characters and strings: 7676 7677 (gdb) show charset 7678 The current host and target character set is `ISO-8859-1'. 7679 (gdb) 7680 7681 For the sake of printing this manual, let's use ASCII as our initial 7682character set: 7683 (gdb) set charset ASCII 7684 (gdb) show charset 7685 The current host and target character set is `ASCII'. 7686 (gdb) 7687 7688 Let's assume that ASCII is indeed the correct character set for our 7689host system -- in other words, let's assume that if GDB prints 7690characters using the ASCII character set, our terminal will display 7691them properly. Since our current target character set is also ASCII, 7692the contents of `ascii_hello' print legibly: 7693 7694 (gdb) print ascii_hello 7695 $1 = 0x401698 "Hello, world!\n" 7696 (gdb) print ascii_hello[0] 7697 $2 = 72 'H' 7698 (gdb) 7699 7700 GDB uses the target character set for character and string literals 7701you use in expressions: 7702 7703 (gdb) print '+' 7704 $3 = 43 '+' 7705 (gdb) 7706 7707 The ASCII character set uses the number 43 to encode the `+' 7708character. 7709 7710 GDB relies on the user to tell it which character set the target 7711program uses. If we print `ibm1047_hello' while our target character 7712set is still ASCII, we get jibberish: 7713 7714 (gdb) print ibm1047_hello 7715 $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" 7716 (gdb) print ibm1047_hello[0] 7717 $5 = 200 '\310' 7718 (gdb) 7719 7720 If we invoke the `set target-charset' followed by <TAB><TAB>, GDB 7721tells us the character sets it supports: 7722 7723 (gdb) set target-charset 7724 ASCII EBCDIC-US IBM1047 ISO-8859-1 7725 (gdb) set target-charset 7726 7727 We can select IBM1047 as our target character set, and examine the 7728program's strings again. Now the ASCII string is wrong, but GDB 7729translates the contents of `ibm1047_hello' from the target character 7730set, IBM1047, to the host character set, ASCII, and they display 7731correctly: 7732 7733 (gdb) set target-charset IBM1047 7734 (gdb) show charset 7735 The current host character set is `ASCII'. 7736 The current target character set is `IBM1047'. 7737 (gdb) print ascii_hello 7738 $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" 7739 (gdb) print ascii_hello[0] 7740 $7 = 72 '\110' 7741 (gdb) print ibm1047_hello 7742 $8 = 0x4016a8 "Hello, world!\n" 7743 (gdb) print ibm1047_hello[0] 7744 $9 = 200 'H' 7745 (gdb) 7746 7747 As above, GDB uses the target character set for character and string 7748literals you use in expressions: 7749 7750 (gdb) print '+' 7751 $10 = 78 '+' 7752 (gdb) 7753 7754 The IBM1047 character set uses the number 78 to encode the `+' 7755character. 7756 7757 7758File: gdb.info, Node: Caching Remote Data, Next: Searching Memory, Prev: Character Sets, Up: Data 7759 776010.20 Caching Data of Remote Targets 7761==================================== 7762 7763GDB caches data exchanged between the debugger and a remote target 7764(*note Remote Debugging::). Such caching generally improves 7765performance, because it reduces the overhead of the remote protocol by 7766bundling memory reads and writes into large chunks. Unfortunately, 7767simply caching everything would lead to incorrect results, since GDB 7768does not necessarily know anything about volatile values, memory-mapped 7769I/O addresses, etc. Furthermore, in non-stop mode (*note Non-Stop 7770Mode::) memory can be changed _while_ a gdb command is executing. 7771Therefore, by default, GDB only caches data known to be on the stack(1). 7772Other regions of memory can be explicitly marked as cacheable; see 7773*note Memory Region Attributes::. 7774 7775`set remotecache on' 7776`set remotecache off' 7777 This option no longer does anything; it exists for compatibility 7778 with old scripts. 7779 7780`show remotecache' 7781 Show the current state of the obsolete remotecache flag. 7782 7783`set stack-cache on' 7784`set stack-cache off' 7785 Enable or disable caching of stack accesses. When `ON', use 7786 caching. By default, this option is `ON'. 7787 7788`show stack-cache' 7789 Show the current state of data caching for memory accesses. 7790 7791`info dcache [line]' 7792 Print the information about the data cache performance. The 7793 information displayed includes the dcache width and depth, and for 7794 each cache line, its number, address, and how many times it was 7795 referenced. This command is useful for debugging the data cache 7796 operation. 7797 7798 If a line number is specified, the contents of that line will be 7799 printed in hex. 7800 7801 ---------- Footnotes ---------- 7802 7803 (1) In non-stop mode, it is moderately rare for a running thread to 7804modify the stack of a stopped thread in a way that would interfere with 7805a backtrace, and caching of stack reads provides a significant speed up 7806of remote backtraces. 7807 7808 7809File: gdb.info, Node: Searching Memory, Prev: Caching Remote Data, Up: Data 7810 781110.21 Search Memory 7812=================== 7813 7814Memory can be searched for a particular sequence of bytes with the 7815`find' command. 7816 7817`find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]' 7818`find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]' 7819 Search memory for the sequence of bytes specified by VAL1, VAL2, 7820 etc. The search begins at address START_ADDR and continues for 7821 either LEN bytes or through to END_ADDR inclusive. 7822 7823 S and N are optional parameters. They may be specified in either 7824order, apart or together. 7825 7826S, search query size 7827 The size of each search query value. 7828 7829 `b' 7830 bytes 7831 7832 `h' 7833 halfwords (two bytes) 7834 7835 `w' 7836 words (four bytes) 7837 7838 `g' 7839 giant words (eight bytes) 7840 7841 All values are interpreted in the current language. This means, 7842 for example, that if the current source language is C/C++ then 7843 searching for the string "hello" includes the trailing '\0'. 7844 7845 If the value size is not specified, it is taken from the value's 7846 type in the current language. This is useful when one wants to 7847 specify the search pattern as a mixture of types. Note that this 7848 means, for example, that in the case of C-like languages a search 7849 for an untyped 0x42 will search for `(int) 0x42' which is 7850 typically four bytes. 7851 7852N, maximum number of finds 7853 The maximum number of matches to print. The default is to print 7854 all finds. 7855 7856 You can use strings as search values. Quote them with double-quotes 7857(`"'). The string value is copied into the search pattern byte by byte, 7858regardless of the endianness of the target and the size specification. 7859 7860 The address of each match found is printed as well as a count of the 7861number of matches found. 7862 7863 The address of the last value found is stored in convenience variable 7864`$_'. A count of the number of matches is stored in `$numfound'. 7865 7866 For example, if stopped at the `printf' in this function: 7867 7868 void 7869 hello () 7870 { 7871 static char hello[] = "hello-hello"; 7872 static struct { char c; short s; int i; } 7873 __attribute__ ((packed)) mixed 7874 = { 'c', 0x1234, 0x87654321 }; 7875 printf ("%s\n", hello); 7876 } 7877 7878you get during debugging: 7879 7880 (gdb) find &hello[0], +sizeof(hello), "hello" 7881 0x804956d <hello.1620+6> 7882 1 pattern found 7883 (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' 7884 0x8049567 <hello.1620> 7885 0x804956d <hello.1620+6> 7886 2 patterns found 7887 (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' 7888 0x8049567 <hello.1620> 7889 1 pattern found 7890 (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 7891 0x8049560 <mixed.1625> 7892 1 pattern found 7893 (gdb) print $numfound 7894 $1 = 1 7895 (gdb) print $_ 7896 $2 = (void *) 0x8049560 7897 7898 7899File: gdb.info, Node: Optimized Code, Next: Macros, Prev: Data, Up: Top 7900 790111 Debugging Optimized Code 7902*************************** 7903 7904Almost all compilers support optimization. With optimization disabled, 7905the compiler generates assembly code that corresponds directly to your 7906source code, in a simplistic way. As the compiler applies more 7907powerful optimizations, the generated assembly code diverges from your 7908original source code. With help from debugging information generated 7909by the compiler, GDB can map from the running program back to 7910constructs from your original source. 7911 7912 GDB is more accurate with optimization disabled. If you can 7913recompile without optimization, it is easier to follow the progress of 7914your program during debugging. But, there are many cases where you may 7915need to debug an optimized version. 7916 7917 When you debug a program compiled with `-g -O', remember that the 7918optimizer has rearranged your code; the debugger shows you what is 7919really there. Do not be too surprised when the execution path does not 7920exactly match your source file! An extreme example: if you define a 7921variable, but never use it, GDB never sees that variable--because the 7922compiler optimizes it out of existence. 7923 7924 Some things do not work as well with `-g -O' as with just `-g', 7925particularly on machines with instruction scheduling. If in doubt, 7926recompile with `-g' alone, and if this fixes the problem, please report 7927it to us as a bug (including a test case!). *Note Variables::, for 7928more information about debugging optimized code. 7929 7930* Menu: 7931 7932* Inline Functions:: How GDB presents inlining 7933 7934 7935File: gdb.info, Node: Inline Functions, Up: Optimized Code 7936 793711.1 Inline Functions 7938===================== 7939 7940"Inlining" is an optimization that inserts a copy of the function body 7941directly at each call site, instead of jumping to a shared routine. 7942GDB displays inlined functions just like non-inlined functions. They 7943appear in backtraces. You can view their arguments and local 7944variables, step into them with `step', skip them with `next', and 7945escape from them with `finish'. You can check whether a function was 7946inlined by using the `info frame' command. 7947 7948 For GDB to support inlined functions, the compiler must record 7949information about inlining in the debug information -- GCC using the 7950DWARF 2 format does this, and several other compilers do also. GDB 7951only supports inlined functions when using DWARF 2. Versions of GCC 7952before 4.1 do not emit two required attributes (`DW_AT_call_file' and 7953`DW_AT_call_line'); GDB does not display inlined function calls with 7954earlier versions of GCC. It instead displays the arguments and local 7955variables of inlined functions as local variables in the caller. 7956 7957 The body of an inlined function is directly included at its call 7958site; unlike a non-inlined function, there are no instructions devoted 7959to the call. GDB still pretends that the call site and the start of 7960the inlined function are different instructions. Stepping to the call 7961site shows the call site, and then stepping again shows the first line 7962of the inlined function, even though no additional instructions are 7963executed. 7964 7965 This makes source-level debugging much clearer; you can see both the 7966context of the call and then the effect of the call. Only stepping by 7967a single instruction using `stepi' or `nexti' does not do this; single 7968instruction steps always show the inlined body. 7969 7970 There are some ways that GDB does not pretend that inlined function 7971calls are the same as normal calls: 7972 7973 * You cannot set breakpoints on inlined functions. GDB either 7974 reports that there is no symbol with that name, or else sets the 7975 breakpoint only on non-inlined copies of the function. This 7976 limitation will be removed in a future version of GDB; until then, 7977 set a breakpoint by line number on the first line of the inlined 7978 function instead. 7979 7980 * Setting breakpoints at the call site of an inlined function may not 7981 work, because the call site does not contain any code. GDB may 7982 incorrectly move the breakpoint to the next line of the enclosing 7983 function, after the call. This limitation will be removed in a 7984 future version of GDB; until then, set a breakpoint on an earlier 7985 line or inside the inlined function instead. 7986 7987 * GDB cannot locate the return value of inlined calls after using 7988 the `finish' command. This is a limitation of compiler-generated 7989 debugging information; after `finish', you can step to the next 7990 line and print a variable where your program stored the return 7991 value. 7992 7993 7994 7995File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Optimized Code, Up: Top 7996 799712 C Preprocessor Macros 7998************************ 7999 8000Some languages, such as C and C++, provide a way to define and invoke 8001"preprocessor macros" which expand into strings of tokens. GDB can 8002evaluate expressions containing macro invocations, show the result of 8003macro expansion, and show a macro's definition, including where it was 8004defined. 8005 8006 You may need to compile your program specially to provide GDB with 8007information about preprocessor macros. Most compilers do not include 8008macros in their debugging information, even when you compile with the 8009`-g' flag. *Note Compilation::. 8010 8011 A program may define a macro at one point, remove that definition 8012later, and then provide a different definition after that. Thus, at 8013different points in the program, a macro may have different 8014definitions, or have no definition at all. If there is a current stack 8015frame, GDB uses the macros in scope at that frame's source code line. 8016Otherwise, GDB uses the macros in scope at the current listing location; 8017see *note List::. 8018 8019 Whenever GDB evaluates an expression, it always expands any macro 8020invocations present in the expression. GDB also provides the following 8021commands for working with macros explicitly. 8022 8023`macro expand EXPRESSION' 8024`macro exp EXPRESSION' 8025 Show the results of expanding all preprocessor macro invocations in 8026 EXPRESSION. Since GDB simply expands macros, but does not parse 8027 the result, EXPRESSION need not be a valid expression; it can be 8028 any string of tokens. 8029 8030`macro expand-once EXPRESSION' 8031`macro exp1 EXPRESSION' 8032 (This command is not yet implemented.) Show the results of 8033 expanding those preprocessor macro invocations that appear 8034 explicitly in EXPRESSION. Macro invocations appearing in that 8035 expansion are left unchanged. This command allows you to see the 8036 effect of a particular macro more clearly, without being confused 8037 by further expansions. Since GDB simply expands macros, but does 8038 not parse the result, EXPRESSION need not be a valid expression; it 8039 can be any string of tokens. 8040 8041`info macro MACRO' 8042 Show the definition of the macro named MACRO, and describe the 8043 source location or compiler command-line where that definition was 8044 established. 8045 8046`macro define MACRO REPLACEMENT-LIST' 8047`macro define MACRO(ARGLIST) REPLACEMENT-LIST' 8048 Introduce a definition for a preprocessor macro named MACRO, 8049 invocations of which are replaced by the tokens given in 8050 REPLACEMENT-LIST. The first form of this command defines an 8051 "object-like" macro, which takes no arguments; the second form 8052 defines a "function-like" macro, which takes the arguments given in 8053 ARGLIST. 8054 8055 A definition introduced by this command is in scope in every 8056 expression evaluated in GDB, until it is removed with the `macro 8057 undef' command, described below. The definition overrides all 8058 definitions for MACRO present in the program being debugged, as 8059 well as any previous user-supplied definition. 8060 8061`macro undef MACRO' 8062 Remove any user-supplied definition for the macro named MACRO. 8063 This command only affects definitions provided with the `macro 8064 define' command, described above; it cannot remove definitions 8065 present in the program being debugged. 8066 8067`macro list' 8068 List all the macros defined using the `macro define' command. 8069 8070 Here is a transcript showing the above commands in action. First, we 8071show our source files: 8072 8073 $ cat sample.c 8074 #include <stdio.h> 8075 #include "sample.h" 8076 8077 #define M 42 8078 #define ADD(x) (M + x) 8079 8080 main () 8081 { 8082 #define N 28 8083 printf ("Hello, world!\n"); 8084 #undef N 8085 printf ("We're so creative.\n"); 8086 #define N 1729 8087 printf ("Goodbye, world!\n"); 8088 } 8089 $ cat sample.h 8090 #define Q < 8091 $ 8092 8093 Now, we compile the program using the GNU C compiler, GCC. We pass 8094the `-gdwarf-2' and `-g3' flags to ensure the compiler includes 8095information about preprocessor macros in the debugging information. 8096 8097 $ gcc -gdwarf-2 -g3 sample.c -o sample 8098 $ 8099 8100 Now, we start GDB on our sample program: 8101 8102 $ gdb -nw sample 8103 GNU gdb 2002-05-06-cvs 8104 Copyright 2002 Free Software Foundation, Inc. 8105 GDB is free software, ... 8106 (gdb) 8107 8108 We can expand macros and examine their definitions, even when the 8109program is not running. GDB uses the current listing position to 8110decide which macro definitions are in scope: 8111 8112 (gdb) list main 8113 3 8114 4 #define M 42 8115 5 #define ADD(x) (M + x) 8116 6 8117 7 main () 8118 8 { 8119 9 #define N 28 8120 10 printf ("Hello, world!\n"); 8121 11 #undef N 8122 12 printf ("We're so creative.\n"); 8123 (gdb) info macro ADD 8124 Defined at /home/jimb/gdb/macros/play/sample.c:5 8125 #define ADD(x) (M + x) 8126 (gdb) info macro Q 8127 Defined at /home/jimb/gdb/macros/play/sample.h:1 8128 included at /home/jimb/gdb/macros/play/sample.c:2 8129 #define Q < 8130 (gdb) macro expand ADD(1) 8131 expands to: (42 + 1) 8132 (gdb) macro expand-once ADD(1) 8133 expands to: once (M + 1) 8134 (gdb) 8135 8136 In the example above, note that `macro expand-once' expands only the 8137macro invocation explicit in the original text -- the invocation of 8138`ADD' -- but does not expand the invocation of the macro `M', which was 8139introduced by `ADD'. 8140 8141 Once the program is running, GDB uses the macro definitions in force 8142at the source line of the current stack frame: 8143 8144 (gdb) break main 8145 Breakpoint 1 at 0x8048370: file sample.c, line 10. 8146 (gdb) run 8147 Starting program: /home/jimb/gdb/macros/play/sample 8148 8149 Breakpoint 1, main () at sample.c:10 8150 10 printf ("Hello, world!\n"); 8151 (gdb) 8152 8153 At line 10, the definition of the macro `N' at line 9 is in force: 8154 8155 (gdb) info macro N 8156 Defined at /home/jimb/gdb/macros/play/sample.c:9 8157 #define N 28 8158 (gdb) macro expand N Q M 8159 expands to: 28 < 42 8160 (gdb) print N Q M 8161 $1 = 1 8162 (gdb) 8163 8164 As we step over directives that remove `N''s definition, and then 8165give it a new definition, GDB finds the definition (or lack thereof) in 8166force at each point: 8167 8168 (gdb) next 8169 Hello, world! 8170 12 printf ("We're so creative.\n"); 8171 (gdb) info macro N 8172 The symbol `N' has no definition as a C/C++ preprocessor macro 8173 at /home/jimb/gdb/macros/play/sample.c:12 8174 (gdb) next 8175 We're so creative. 8176 14 printf ("Goodbye, world!\n"); 8177 (gdb) info macro N 8178 Defined at /home/jimb/gdb/macros/play/sample.c:13 8179 #define N 1729 8180 (gdb) macro expand N Q M 8181 expands to: 1729 < 42 8182 (gdb) print N Q M 8183 $2 = 0 8184 (gdb) 8185 8186 In addition to source files, macros can be defined on the 8187compilation command line using the `-DNAME=VALUE' syntax. For macros 8188defined in such a way, GDB displays the location of their definition as 8189line zero of the source file submitted to the compiler. 8190 8191 (gdb) info macro __STDC__ 8192 Defined at /home/jimb/gdb/macros/play/sample.c:0 8193 -D__STDC__=1 8194 (gdb) 8195 8196 8197File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top 8198 819913 Tracepoints 8200************** 8201 8202In some applications, it is not feasible for the debugger to interrupt 8203the program's execution long enough for the developer to learn anything 8204helpful about its behavior. If the program's correctness depends on 8205its real-time behavior, delays introduced by a debugger might cause the 8206program to change its behavior drastically, or perhaps fail, even when 8207the code itself is correct. It is useful to be able to observe the 8208program's behavior without interrupting it. 8209 8210 Using GDB's `trace' and `collect' commands, you can specify 8211locations in the program, called "tracepoints", and arbitrary 8212expressions to evaluate when those tracepoints are reached. Later, 8213using the `tfind' command, you can examine the values those expressions 8214had when the program hit the tracepoints. The expressions may also 8215denote objects in memory--structures or arrays, for example--whose 8216values GDB should record; while visiting a particular tracepoint, you 8217may inspect those objects as if they were in memory at that moment. 8218However, because GDB records these values without interacting with you, 8219it can do so quickly and unobtrusively, hopefully not disturbing the 8220program's behavior. 8221 8222 The tracepoint facility is currently available only for remote 8223targets. *Note Targets::. In addition, your remote target must know 8224how to collect trace data. This functionality is implemented in the 8225remote stub; however, none of the stubs distributed with GDB support 8226tracepoints as of this writing. The format of the remote packets used 8227to implement tracepoints are described in *note Tracepoint Packets::. 8228 8229 It is also possible to get trace data from a file, in a manner 8230reminiscent of corefiles; you specify the filename, and use `tfind' to 8231search through the file. *Note Trace Files::, for more details. 8232 8233 This chapter describes the tracepoint commands and features. 8234 8235* Menu: 8236 8237* Set Tracepoints:: 8238* Analyze Collected Data:: 8239* Tracepoint Variables:: 8240* Trace Files:: 8241 8242 8243File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints 8244 824513.1 Commands to Set Tracepoints 8246================================ 8247 8248Before running such a "trace experiment", an arbitrary number of 8249tracepoints can be set. A tracepoint is actually a special type of 8250breakpoint (*note Set Breaks::), so you can manipulate it using 8251standard breakpoint commands. For instance, as with breakpoints, 8252tracepoint numbers are successive integers starting from one, and many 8253of the commands associated with tracepoints take the tracepoint number 8254as their argument, to identify which tracepoint to work on. 8255 8256 For each tracepoint, you can specify, in advance, some arbitrary set 8257of data that you want the target to collect in the trace buffer when it 8258hits that tracepoint. The collected data can include registers, local 8259variables, or global data. Later, you can use GDB commands to examine 8260the values these data had at the time the tracepoint was hit. 8261 8262 Tracepoints do not support every breakpoint feature. Ignore counts 8263on tracepoints have no effect, and tracepoints cannot run GDB commands 8264when they are hit. Tracepoints may not be thread-specific either. 8265 8266 Some targets may support "fast tracepoints", which are inserted in a 8267different way (such as with a jump instead of a trap), that is faster 8268but possibly restricted in where they may be installed. 8269 8270 Regular and fast tracepoints are dynamic tracing facilities, meaning 8271that they can be used to insert tracepoints at (almost) any location in 8272the target. Some targets may also support controlling "static 8273tracepoints" from GDB. With static tracing, a set of instrumentation 8274points, also known as "markers", are embedded in the target program, 8275and can be activated or deactivated by name or address. These are 8276usually placed at locations which facilitate investigating what the 8277target is actually doing. GDB's support for static tracing includes 8278being able to list instrumentation points, and attach them with GDB 8279defined high level tracepoints that expose the whole range of 8280convenience of GDB's tracepoints support. Namelly, support for 8281collecting registers values and values of global or local (to the 8282instrumentation point) variables; tracepoint conditions and trace state 8283variables. The act of installing a GDB static tracepoint on an 8284instrumentation point, or marker, is referred to as "probing" a static 8285tracepoint marker. 8286 8287 `gdbserver' supports tracepoints on some target systems. *Note 8288Tracepoints support in `gdbserver': Server. 8289 8290 This section describes commands to set tracepoints and associated 8291conditions and actions. 8292 8293* Menu: 8294 8295* Create and Delete Tracepoints:: 8296* Enable and Disable Tracepoints:: 8297* Tracepoint Passcounts:: 8298* Tracepoint Conditions:: 8299* Trace State Variables:: 8300* Tracepoint Actions:: 8301* Listing Tracepoints:: 8302* Listing Static Tracepoint Markers:: 8303* Starting and Stopping Trace Experiments:: 8304* Tracepoint Restrictions:: 8305 8306 8307File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints 8308 830913.1.1 Create and Delete Tracepoints 8310------------------------------------ 8311 8312`trace LOCATION' 8313 The `trace' command is very similar to the `break' command. Its 8314 argument LOCATION can be a source line, a function name, or an 8315 address in the target program. *Note Specify Location::. The 8316 `trace' command defines a tracepoint, which is a point in the 8317 target program where the debugger will briefly stop, collect some 8318 data, and then allow the program to continue. Setting a 8319 tracepoint or changing its actions doesn't take effect until the 8320 next `tstart' command, and once a trace experiment is running, 8321 further changes will not have any effect until the next trace 8322 experiment starts. 8323 8324 Here are some examples of using the `trace' command: 8325 8326 (gdb) trace foo.c:121 // a source file and line number 8327 8328 (gdb) trace +2 // 2 lines forward 8329 8330 (gdb) trace my_function // first source line of function 8331 8332 (gdb) trace *my_function // EXACT start address of function 8333 8334 (gdb) trace *0x2117c4 // an address 8335 8336 You can abbreviate `trace' as `tr'. 8337 8338`trace LOCATION if COND' 8339 Set a tracepoint with condition COND; evaluate the expression COND 8340 each time the tracepoint is reached, and collect data only if the 8341 value is nonzero--that is, if COND evaluates as true. *Note 8342 Tracepoint Conditions: Tracepoint Conditions, for more information 8343 on tracepoint conditions. 8344 8345`ftrace LOCATION [ if COND ]' 8346 The `ftrace' command sets a fast tracepoint. For targets that 8347 support them, fast tracepoints will use a more efficient but 8348 possibly less general technique to trigger data collection, such 8349 as a jump instruction instead of a trap, or some sort of hardware 8350 support. It may not be possible to create a fast tracepoint at 8351 the desired location, in which case the command will exit with an 8352 explanatory message. 8353 8354 GDB handles arguments to `ftrace' exactly as for `trace'. 8355 8356`strace LOCATION [ if COND ]' 8357 The `strace' command sets a static tracepoint. For targets that 8358 support it, setting a static tracepoint probes a static 8359 instrumentation point, or marker, found at LOCATION. It may not 8360 be possible to set a static tracepoint at the desired location, in 8361 which case the command will exit with an explanatory message. 8362 8363 GDB handles arguments to `strace' exactly as for `trace', with the 8364 addition that the user can also specify `-m MARKER' as LOCATION. 8365 This probes the marker identified by the MARKER string identifier. 8366 This identifier depends on the static tracepoint backend library 8367 your program is using. You can find all the marker identifiers in 8368 the `ID' field of the `info static-tracepoint-markers' command 8369 output. *Note Listing Static Tracepoint Markers: Listing Static 8370 Tracepoint Markers. For example, in the following small program 8371 using the UST tracing engine: 8372 8373 main () 8374 { 8375 trace_mark(ust, bar33, "str %s", "FOOBAZ"); 8376 } 8377 8378 the marker id is composed of joining the first two arguments to the 8379 `trace_mark' call with a slash, which translates to: 8380 8381 (gdb) info static-tracepoint-markers 8382 Cnt Enb ID Address What 8383 1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 8384 Data: "str %s" 8385 [etc...] 8386 8387 so you may probe the marker above with: 8388 8389 (gdb) strace -m ust/bar33 8390 8391 Static tracepoints accept an extra collect action -- `collect 8392 $_sdata'. This collects arbitrary user data passed in the probe 8393 point call to the tracing library. In the UST example above, 8394 you'll see that the third argument to `trace_mark' is a 8395 printf-like format string. The user data is then the result of 8396 running that formating string against the following arguments. 8397 Note that `info static-tracepoint-markers' command output lists 8398 that format string in the `Data:' field. 8399 8400 You can inspect this data when analyzing the trace buffer, by 8401 printing the $_sdata variable like any other variable available to 8402 GDB. *Note Tracepoint Action Lists: Tracepoint Actions. 8403 8404 The convenience variable `$tpnum' records the tracepoint number of 8405 the most recently set tracepoint. 8406 8407`delete tracepoint [NUM]' 8408 Permanently delete one or more tracepoints. With no argument, the 8409 default is to delete all tracepoints. Note that the regular 8410 `delete' command can remove tracepoints also. 8411 8412 Examples: 8413 8414 (gdb) delete trace 1 2 3 // remove three tracepoints 8415 8416 (gdb) delete trace // remove all tracepoints 8417 8418 You can abbreviate this command as `del tr'. 8419 8420 8421File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints 8422 842313.1.2 Enable and Disable Tracepoints 8424------------------------------------- 8425 8426These commands are deprecated; they are equivalent to plain `disable' 8427and `enable'. 8428 8429`disable tracepoint [NUM]' 8430 Disable tracepoint NUM, or all tracepoints if no argument NUM is 8431 given. A disabled tracepoint will have no effect during the next 8432 trace experiment, but it is not forgotten. You can re-enable a 8433 disabled tracepoint using the `enable tracepoint' command. 8434 8435`enable tracepoint [NUM]' 8436 Enable tracepoint NUM, or all tracepoints. The enabled 8437 tracepoints will become effective the next time a trace experiment 8438 is run. 8439 8440 8441File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Conditions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints 8442 844313.1.3 Tracepoint Passcounts 8444---------------------------- 8445 8446`passcount [N [NUM]]' 8447 Set the "passcount" of a tracepoint. The passcount is a way to 8448 automatically stop a trace experiment. If a tracepoint's 8449 passcount is N, then the trace experiment will be automatically 8450 stopped on the N'th time that tracepoint is hit. If the 8451 tracepoint number NUM is not specified, the `passcount' command 8452 sets the passcount of the most recently defined tracepoint. If no 8453 passcount is given, the trace experiment will run until stopped 8454 explicitly by the user. 8455 8456 Examples: 8457 8458 (gdb) passcount 5 2 // Stop on the 5th execution of 8459 `// tracepoint 2' 8460 8461 (gdb) passcount 12 // Stop on the 12th execution of the 8462 `// most recently defined tracepoint.' 8463 (gdb) trace foo 8464 (gdb) pass 3 8465 (gdb) trace bar 8466 (gdb) pass 2 8467 (gdb) trace baz 8468 (gdb) pass 1 // Stop tracing when foo has been 8469 `// executed 3 times OR when bar has' 8470 `// been executed 2 times' 8471 `// OR when baz has been executed 1 time.' 8472 8473 8474 8475File: gdb.info, Node: Tracepoint Conditions, Next: Trace State Variables, Prev: Tracepoint Passcounts, Up: Set Tracepoints 8476 847713.1.4 Tracepoint Conditions 8478---------------------------- 8479 8480The simplest sort of tracepoint collects data every time your program 8481reaches a specified place. You can also specify a "condition" for a 8482tracepoint. A condition is just a Boolean expression in your 8483programming language (*note Expressions: Expressions.). A tracepoint 8484with a condition evaluates the expression each time your program 8485reaches it, and data collection happens only if the condition is true. 8486 8487 Tracepoint conditions can be specified when a tracepoint is set, by 8488using `if' in the arguments to the `trace' command. *Note Setting 8489Tracepoints: Create and Delete Tracepoints. They can also be set or 8490changed at any time with the `condition' command, just as with 8491breakpoints. 8492 8493 Unlike breakpoint conditions, GDB does not actually evaluate the 8494conditional expression itself. Instead, GDB encodes the expression 8495into an agent expression (*note Agent Expressions:: suitable for 8496execution on the target, independently of GDB. Global variables become 8497raw memory locations, locals become stack accesses, and so forth. 8498 8499 For instance, suppose you have a function that is usually called 8500frequently, but should not be called after an error has occurred. You 8501could use the following tracepoint command to collect data about calls 8502of that function that happen while the error code is propagating 8503through the program; an unconditional tracepoint could end up 8504collecting thousands of useless trace frames that you would have to 8505search through. 8506 8507 (gdb) trace normal_operation if errcode > 0 8508 8509 8510File: gdb.info, Node: Trace State Variables, Next: Tracepoint Actions, Prev: Tracepoint Conditions, Up: Set Tracepoints 8511 851213.1.5 Trace State Variables 8513---------------------------- 8514 8515A "trace state variable" is a special type of variable that is created 8516and managed by target-side code. The syntax is the same as that for 8517GDB's convenience variables (a string prefixed with "$"), but they are 8518stored on the target. They must be created explicitly, using a 8519`tvariable' command. They are always 64-bit signed integers. 8520 8521 Trace state variables are remembered by GDB, and downloaded to the 8522target along with tracepoint information when the trace experiment 8523starts. There are no intrinsic limits on the number of trace state 8524variables, beyond memory limitations of the target. 8525 8526 Although trace state variables are managed by the target, you can use 8527them in print commands and expressions as if they were convenience 8528variables; GDB will get the current value from the target while the 8529trace experiment is running. Trace state variables share the same 8530namespace as other "$" variables, which means that you cannot have 8531trace state variables with names like `$23' or `$pc', nor can you have 8532a trace state variable and a convenience variable with the same name. 8533 8534`tvariable $NAME [ = EXPRESSION ]' 8535 The `tvariable' command creates a new trace state variable named 8536 `$NAME', and optionally gives it an initial value of EXPRESSION. 8537 EXPRESSION is evaluated when this command is entered; the result 8538 will be converted to an integer if possible, otherwise GDB will 8539 report an error. A subsequent `tvariable' command specifying the 8540 same name does not create a variable, but instead assigns the 8541 supplied initial value to the existing variable of that name, 8542 overwriting any previous initial value. The default initial value 8543 is 0. 8544 8545`info tvariables' 8546 List all the trace state variables along with their initial values. 8547 Their current values may also be displayed, if the trace 8548 experiment is currently running. 8549 8550`delete tvariable [ $NAME ... ]' 8551 Delete the given trace state variables, or all of them if no 8552 arguments are specified. 8553 8554 8555 8556File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Trace State Variables, Up: Set Tracepoints 8557 855813.1.6 Tracepoint Action Lists 8559------------------------------ 8560 8561`actions [NUM]' 8562 This command will prompt for a list of actions to be taken when the 8563 tracepoint is hit. If the tracepoint number NUM is not specified, 8564 this command sets the actions for the one that was most recently 8565 defined (so that you can define a tracepoint and then say 8566 `actions' without bothering about its number). You specify the 8567 actions themselves on the following lines, one action at a time, 8568 and terminate the actions list with a line containing just `end'. 8569 So far, the only defined actions are `collect', `teval', and 8570 `while-stepping'. 8571 8572 `actions' is actually equivalent to `commands' (*note Breakpoint 8573 Command Lists: Break Commands.), except that only the defined 8574 actions are allowed; any other GDB command is rejected. 8575 8576 To remove all actions from a tracepoint, type `actions NUM' and 8577 follow it immediately with `end'. 8578 8579 (gdb) collect DATA // collect some data 8580 8581 (gdb) while-stepping 5 // single-step 5 times, collect data 8582 8583 (gdb) end // signals the end of actions. 8584 8585 In the following example, the action list begins with `collect' 8586 commands indicating the things to be collected when the tracepoint 8587 is hit. Then, in order to single-step and collect additional data 8588 following the tracepoint, a `while-stepping' command is used, 8589 followed by the list of things to be collected after each step in a 8590 sequence of single steps. The `while-stepping' command is 8591 terminated by its own separate `end' command. Lastly, the action 8592 list is terminated by an `end' command. 8593 8594 (gdb) trace foo 8595 (gdb) actions 8596 Enter actions for tracepoint 1, one per line: 8597 > collect bar,baz 8598 > collect $regs 8599 > while-stepping 12 8600 > collect $pc, arr[i] 8601 > end 8602 end 8603 8604`collect EXPR1, EXPR2, ...' 8605 Collect values of the given expressions when the tracepoint is hit. 8606 This command accepts a comma-separated list of any valid 8607 expressions. In addition to global, static, or local variables, 8608 the following special arguments are supported: 8609 8610 `$regs' 8611 Collect all registers. 8612 8613 `$args' 8614 Collect all function arguments. 8615 8616 `$locals' 8617 Collect all local variables. 8618 8619 `$_sdata' 8620 Collect static tracepoint marker specific data. Only 8621 available for static tracepoints. *Note Tracepoint Action 8622 Lists: Tracepoint Actions. On the UST static tracepoints 8623 library backend, an instrumentation point resembles a 8624 `printf' function call. The tracing library is able to 8625 collect user specified data formatted to a character string 8626 using the format provided by the programmer that instrumented 8627 the program. Other backends have similar mechanisms. Here's 8628 an example of a UST marker call: 8629 8630 const char master_name[] = "$your_name"; 8631 trace_mark(channel1, marker1, "hello %s", master_name) 8632 8633 In this case, collecting `$_sdata' collects the string `hello 8634 $yourname'. When analyzing the trace buffer, you can inspect 8635 `$_sdata' like any other variable available to GDB. 8636 8637 You can give several consecutive `collect' commands, each one with 8638 a single argument, or one `collect' command with several arguments 8639 separated by commas; the effect is the same. 8640 8641 The command `info scope' (*note info scope: Symbols.) is 8642 particularly useful for figuring out what data to collect. 8643 8644`teval EXPR1, EXPR2, ...' 8645 Evaluate the given expressions when the tracepoint is hit. This 8646 command accepts a comma-separated list of expressions. The results 8647 are discarded, so this is mainly useful for assigning values to 8648 trace state variables (*note Trace State Variables::) without 8649 adding those values to the trace buffer, as would be the case if 8650 the `collect' action were used. 8651 8652`while-stepping N' 8653 Perform N single-step instruction traces after the tracepoint, 8654 collecting new data after each step. The `while-stepping' command 8655 is followed by the list of what to collect while stepping 8656 (followed by its own `end' command): 8657 8658 > while-stepping 12 8659 > collect $regs, myglobal 8660 > end 8661 > 8662 8663 Note that `$pc' is not automatically collected by 8664 `while-stepping'; you need to explicitly collect that register if 8665 you need it. You may abbreviate `while-stepping' as `ws' or 8666 `stepping'. 8667 8668`set default-collect EXPR1, EXPR2, ...' 8669 This variable is a list of expressions to collect at each 8670 tracepoint hit. It is effectively an additional `collect' action 8671 prepended to every tracepoint action list. The expressions are 8672 parsed individually for each tracepoint, so for instance a 8673 variable named `xyz' may be interpreted as a global for one 8674 tracepoint, and a local for another, as appropriate to the 8675 tracepoint's location. 8676 8677`show default-collect' 8678 Show the list of expressions that are collected by default at each 8679 tracepoint hit. 8680 8681 8682 8683File: gdb.info, Node: Listing Tracepoints, Next: Listing Static Tracepoint Markers, Prev: Tracepoint Actions, Up: Set Tracepoints 8684 868513.1.7 Listing Tracepoints 8686-------------------------- 8687 8688`info tracepoints [NUM]' 8689 Display information about the tracepoint NUM. If you don't 8690 specify a tracepoint number, displays information about all the 8691 tracepoints defined so far. The format is similar to that used for 8692 `info breakpoints'; in fact, `info tracepoints' is the same 8693 command, simply restricting itself to tracepoints. 8694 8695 A tracepoint's listing may include additional information specific 8696 to tracing: 8697 8698 * its passcount as given by the `passcount N' command 8699 8700 (gdb) info trace 8701 Num Type Disp Enb Address What 8702 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 8703 while-stepping 20 8704 collect globfoo, $regs 8705 end 8706 collect globfoo2 8707 end 8708 pass count 1200 8709 (gdb) 8710 8711 This command can be abbreviated `info tp'. 8712 8713 8714File: gdb.info, Node: Listing Static Tracepoint Markers, Next: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints 8715 871613.1.8 Listing Static Tracepoint Markers 8717---------------------------------------- 8718 8719`info static-tracepoint-markers' 8720 Display information about all static tracepoint markers defined in 8721 the program. 8722 8723 For each marker, the following columns are printed: 8724 8725 _Count_ 8726 An incrementing counter, output to help readability. This is 8727 not a stable identifier. 8728 8729 _ID_ 8730 The marker ID, as reported by the target. 8731 8732 _Enabled or Disabled_ 8733 Probed markers are tagged with `y'. `n' identifies marks 8734 that are not enabled. 8735 8736 _Address_ 8737 Where the marker is in your program, as a memory address. 8738 8739 _What_ 8740 Where the marker is in the source for your program, as a file 8741 and line number. If the debug information included in the 8742 program does not allow GDB to locate the source of the 8743 marker, this column will be left blank. 8744 8745 In addition, the following information may be printed for each 8746 marker: 8747 8748 _Data_ 8749 User data passed to the tracing library by the marker call. 8750 In the UST backend, this is the format string passed as 8751 argument to the marker call. 8752 8753 _Static tracepoints probing the marker_ 8754 The list of static tracepoints attached to the marker. 8755 8756 (gdb) info static-tracepoint-markers 8757 Cnt ID Enb Address What 8758 1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 8759 Data: number1 %d number2 %d 8760 Probed by static tracepoints: #2 8761 2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 8762 Data: str %s 8763 (gdb) 8764 8765 8766File: gdb.info, Node: Starting and Stopping Trace Experiments, Next: Tracepoint Restrictions, Prev: Listing Static Tracepoint Markers, Up: Set Tracepoints 8767 876813.1.9 Starting and Stopping Trace Experiments 8769---------------------------------------------- 8770 8771`tstart' 8772 This command takes no arguments. It starts the trace experiment, 8773 and begins collecting data. This has the side effect of 8774 discarding all the data collected in the trace buffer during the 8775 previous trace experiment. 8776 8777`tstop' 8778 This command takes no arguments. It ends the trace experiment, and 8779 stops collecting data. 8780 8781 *Note*: a trace experiment and data collection may stop 8782 automatically if any tracepoint's passcount is reached (*note 8783 Tracepoint Passcounts::), or if the trace buffer becomes full. 8784 8785`tstatus' 8786 This command displays the status of the current trace data 8787 collection. 8788 8789 Here is an example of the commands we described so far: 8790 8791 (gdb) trace gdb_c_test 8792 (gdb) actions 8793 Enter actions for tracepoint #1, one per line. 8794 > collect $regs,$locals,$args 8795 > while-stepping 11 8796 > collect $regs 8797 > end 8798 > end 8799 (gdb) tstart 8800 [time passes ...] 8801 (gdb) tstop 8802 8803 You can choose to continue running the trace experiment even if GDB 8804disconnects from the target, voluntarily or involuntarily. For 8805commands such as `detach', the debugger will ask what you want to do 8806with the trace. But for unexpected terminations (GDB crash, network 8807outage), it would be unfortunate to lose hard-won trace data, so the 8808variable `disconnected-tracing' lets you decide whether the trace should 8809continue running without GDB. 8810 8811`set disconnected-tracing on' 8812`set disconnected-tracing off' 8813 Choose whether a tracing run should continue to run if GDB has 8814 disconnected from the target. Note that `detach' or `quit' will 8815 ask you directly what to do about a running trace no matter what 8816 this variable's setting, so the variable is mainly useful for 8817 handling unexpected situations, such as loss of the network. 8818 8819`show disconnected-tracing' 8820 Show the current choice for disconnected tracing. 8821 8822 8823 When you reconnect to the target, the trace experiment may or may not 8824still be running; it might have filled the trace buffer in the 8825meantime, or stopped for one of the other reasons. If it is running, 8826it will continue after reconnection. 8827 8828 Upon reconnection, the target will upload information about the 8829tracepoints in effect. GDB will then compare that information to the 8830set of tracepoints currently defined, and attempt to match them up, 8831allowing for the possibility that the numbers may have changed due to 8832creation and deletion in the meantime. If one of the target's 8833tracepoints does not match any in GDB, the debugger will create a new 8834tracepoint, so that you have a number with which to specify that 8835tracepoint. This matching-up process is necessarily heuristic, and it 8836may result in useless tracepoints being created; you may simply delete 8837them if they are of no use. 8838 8839 If your target agent supports a "circular trace buffer", then you 8840can run a trace experiment indefinitely without filling the trace 8841buffer; when space runs out, the agent deletes already-collected trace 8842frames, oldest first, until there is enough room to continue 8843collecting. This is especially useful if your tracepoints are being 8844hit too often, and your trace gets terminated prematurely because the 8845buffer is full. To ask for a circular trace buffer, simply set 8846`circular_trace_buffer' to on. You can set this at any time, including 8847during tracing; if the agent can do it, it will change buffer handling 8848on the fly, otherwise it will not take effect until the next run. 8849 8850`set circular-trace-buffer on' 8851`set circular-trace-buffer off' 8852 Choose whether a tracing run should use a linear or circular buffer 8853 for trace data. A linear buffer will not lose any trace data, but 8854 may fill up prematurely, while a circular buffer will discard old 8855 trace data, but it will have always room for the latest tracepoint 8856 hits. 8857 8858`show circular-trace-buffer' 8859 Show the current choice for the trace buffer. Note that this may 8860 not match the agent's current buffer handling, nor is it 8861 guaranteed to match the setting that might have been in effect 8862 during a past run, for instance if you are looking at frames from 8863 a trace file. 8864 8865 8866 8867File: gdb.info, Node: Tracepoint Restrictions, Prev: Starting and Stopping Trace Experiments, Up: Set Tracepoints 8868 886913.1.10 Tracepoint Restrictions 8870------------------------------- 8871 8872There are a number of restrictions on the use of tracepoints. As 8873described above, tracepoint data gathering occurs on the target without 8874interaction from GDB. Thus the full capabilities of the debugger are 8875not available during data gathering, and then at data examination time, 8876you will be limited by only having what was collected. The following 8877items describe some common problems, but it is not exhaustive, and you 8878may run into additional difficulties not mentioned here. 8879 8880 * Tracepoint expressions are intended to gather objects (lvalues). 8881 Thus the full flexibility of GDB's expression evaluator is not 8882 available. You cannot call functions, cast objects to aggregate 8883 types, access convenience variables or modify values (except by 8884 assignment to trace state variables). Some language features may 8885 implicitly call functions (for instance Objective-C fields with 8886 accessors), and therefore cannot be collected either. 8887 8888 * Collection of local variables, either individually or in bulk with 8889 `$locals' or `$args', during `while-stepping' may behave 8890 erratically. The stepping action may enter a new scope (for 8891 instance by stepping into a function), or the location of the 8892 variable may change (for instance it is loaded into a register). 8893 The tracepoint data recorded uses the location information for the 8894 variables that is correct for the tracepoint location. When the 8895 tracepoint is created, it is not possible, in general, to determine 8896 where the steps of a `while-stepping' sequence will advance the 8897 program--particularly if a conditional branch is stepped. 8898 8899 * Collection of an incompletely-initialized or partially-destroyed 8900 object may result in something that GDB cannot display, or displays 8901 in a misleading way. 8902 8903 * When GDB displays a pointer to character it automatically 8904 dereferences the pointer to also display characters of the string 8905 being pointed to. However, collecting the pointer during tracing 8906 does not automatically collect the string. You need to explicitly 8907 dereference the pointer and provide size information if you want to 8908 collect not only the pointer, but the memory pointed to. For 8909 example, `*ptr@50' can be used to collect the 50 element array 8910 pointed to by `ptr'. 8911 8912 * It is not possible to collect a complete stack backtrace at a 8913 tracepoint. Instead, you may collect the registers and a few 8914 hundred bytes from the stack pointer with something like 8915 `*$esp@300' (adjust to use the name of the actual stack pointer 8916 register on your target architecture, and the amount of stack you 8917 wish to capture). Then the `backtrace' command will show a 8918 partial backtrace when using a trace frame. The number of stack 8919 frames that can be examined depends on the sizes of the frames in 8920 the collected stack. Note that if you ask for a block so large 8921 that it goes past the bottom of the stack, the target agent may 8922 report an error trying to read from an invalid address. 8923 8924 * If you do not collect registers at a tracepoint, GDB can infer 8925 that the value of `$pc' must be the same as the address of the 8926 tracepoint and use that when you are looking at a trace frame for 8927 that tracepoint. However, this cannot work if the tracepoint has 8928 multiple locations (for instance if it was set in a function that 8929 was inlined), or if it has a `while-stepping' loop. In those cases 8930 GDB will warn you that it can't infer `$pc', and default it to 8931 zero. 8932 8933 8934 8935File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints 8936 893713.2 Using the Collected Data 8938============================= 8939 8940After the tracepoint experiment ends, you use GDB commands for 8941examining the trace data. The basic idea is that each tracepoint 8942collects a trace "snapshot" every time it is hit and another snapshot 8943every time it single-steps. All these snapshots are consecutively 8944numbered from zero and go into a buffer, and you can examine them 8945later. The way you examine them is to "focus" on a specific trace 8946snapshot. When the remote stub is focused on a trace snapshot, it will 8947respond to all GDB requests for memory and registers by reading from 8948the buffer which belongs to that snapshot, rather than from _real_ 8949memory or registers of the program being debugged. This means that 8950*all* GDB commands (`print', `info registers', `backtrace', etc.) will 8951behave as if we were currently debugging the program state as it was 8952when the tracepoint occurred. Any requests for data that are not in 8953the buffer will fail. 8954 8955* Menu: 8956 8957* tfind:: How to select a trace snapshot 8958* tdump:: How to display all data for a snapshot 8959* save tracepoints:: How to save tracepoints for a future run 8960 8961 8962File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data 8963 896413.2.1 `tfind N' 8965---------------- 8966 8967The basic command for selecting a trace snapshot from the buffer is 8968`tfind N', which finds trace snapshot number N, counting from zero. If 8969no argument N is given, the next snapshot is selected. 8970 8971 Here are the various forms of using the `tfind' command. 8972 8973`tfind start' 8974 Find the first snapshot in the buffer. This is a synonym for 8975 `tfind 0' (since 0 is the number of the first snapshot). 8976 8977`tfind none' 8978 Stop debugging trace snapshots, resume _live_ debugging. 8979 8980`tfind end' 8981 Same as `tfind none'. 8982 8983`tfind' 8984 No argument means find the next trace snapshot. 8985 8986`tfind -' 8987 Find the previous trace snapshot before the current one. This 8988 permits retracing earlier steps. 8989 8990`tfind tracepoint NUM' 8991 Find the next snapshot associated with tracepoint NUM. Search 8992 proceeds forward from the last examined trace snapshot. If no 8993 argument NUM is given, it means find the next snapshot collected 8994 for the same tracepoint as the current snapshot. 8995 8996`tfind pc ADDR' 8997 Find the next snapshot associated with the value ADDR of the 8998 program counter. Search proceeds forward from the last examined 8999 trace snapshot. If no argument ADDR is given, it means find the 9000 next snapshot with the same value of PC as the current snapshot. 9001 9002`tfind outside ADDR1, ADDR2' 9003 Find the next snapshot whose PC is outside the given range of 9004 addresses (exclusive). 9005 9006`tfind range ADDR1, ADDR2' 9007 Find the next snapshot whose PC is between ADDR1 and ADDR2 9008 (inclusive). 9009 9010`tfind line [FILE:]N' 9011 Find the next snapshot associated with the source line N. If the 9012 optional argument FILE is given, refer to line N in that source 9013 file. Search proceeds forward from the last examined trace 9014 snapshot. If no argument N is given, it means find the next line 9015 other than the one currently being examined; thus saying `tfind 9016 line' repeatedly can appear to have the same effect as stepping 9017 from line to line in a _live_ debugging session. 9018 9019 The default arguments for the `tfind' commands are specifically 9020designed to make it easy to scan through the trace buffer. For 9021instance, `tfind' with no argument selects the next trace snapshot, and 9022`tfind -' with no argument selects the previous trace snapshot. So, by 9023giving one `tfind' command, and then simply hitting <RET> repeatedly 9024you can examine all the trace snapshots in order. Or, by saying `tfind 9025-' and then hitting <RET> repeatedly you can examine the snapshots in 9026reverse order. The `tfind line' command with no argument selects the 9027snapshot for the next source line executed. The `tfind pc' command with 9028no argument selects the next snapshot with the same program counter 9029(PC) as the current frame. The `tfind tracepoint' command with no 9030argument selects the next trace snapshot collected by the same 9031tracepoint as the current one. 9032 9033 In addition to letting you scan through the trace buffer manually, 9034these commands make it easy to construct GDB scripts that scan through 9035the trace buffer and print out whatever collected data you are 9036interested in. Thus, if we want to examine the PC, FP, and SP 9037registers from each trace frame in the buffer, we can say this: 9038 9039 (gdb) tfind start 9040 (gdb) while ($trace_frame != -1) 9041 > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ 9042 $trace_frame, $pc, $sp, $fp 9043 > tfind 9044 > end 9045 9046 Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 9047 Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 9048 Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 9049 Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 9050 Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 9051 Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 9052 Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 9053 Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 9054 Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 9055 Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 9056 Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 9057 9058 Or, if we want to examine the variable `X' at each source line in 9059the buffer: 9060 9061 (gdb) tfind start 9062 (gdb) while ($trace_frame != -1) 9063 > printf "Frame %d, X == %d\n", $trace_frame, X 9064 > tfind line 9065 > end 9066 9067 Frame 0, X = 1 9068 Frame 7, X = 2 9069 Frame 13, X = 255 9070 9071 9072File: gdb.info, Node: tdump, Next: save tracepoints, Prev: tfind, Up: Analyze Collected Data 9073 907413.2.2 `tdump' 9075-------------- 9076 9077This command takes no arguments. It prints all the data collected at 9078the current trace snapshot. 9079 9080 (gdb) trace 444 9081 (gdb) actions 9082 Enter actions for tracepoint #2, one per line: 9083 > collect $regs, $locals, $args, gdb_long_test 9084 > end 9085 9086 (gdb) tstart 9087 9088 (gdb) tfind line 444 9089 #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) 9090 at gdb_test.c:444 9091 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) 9092 9093 (gdb) tdump 9094 Data collected at tracepoint 2, trace frame 1: 9095 d0 0xc4aa0085 -995491707 9096 d1 0x18 24 9097 d2 0x80 128 9098 d3 0x33 51 9099 d4 0x71aea3d 119204413 9100 d5 0x22 34 9101 d6 0xe0 224 9102 d7 0x380035 3670069 9103 a0 0x19e24a 1696330 9104 a1 0x3000668 50333288 9105 a2 0x100 256 9106 a3 0x322000 3284992 9107 a4 0x3000698 50333336 9108 a5 0x1ad3cc 1758156 9109 fp 0x30bf3c 0x30bf3c 9110 sp 0x30bf34 0x30bf34 9111 ps 0x0 0 9112 pc 0x20b2c8 0x20b2c8 9113 fpcontrol 0x0 0 9114 fpstatus 0x0 0 9115 fpiaddr 0x0 0 9116 p = 0x20e5b4 "gdb-test" 9117 p1 = (void *) 0x11 9118 p2 = (void *) 0x22 9119 p3 = (void *) 0x33 9120 p4 = (void *) 0x44 9121 p5 = (void *) 0x55 9122 p6 = (void *) 0x66 9123 gdb_long_test = 17 '\021' 9124 9125 (gdb) 9126 9127 `tdump' works by scanning the tracepoint's current collection 9128actions and printing the value of each expression listed. So `tdump' 9129can fail, if after a run, you change the tracepoint's actions to 9130mention variables that were not collected during the run. 9131 9132 Also, for tracepoints with `while-stepping' loops, `tdump' uses the 9133collected value of `$pc' to distinguish between trace frames that were 9134collected at the tracepoint hit, and frames that were collected while 9135stepping. This allows it to correctly choose whether to display the 9136basic list of collections, or the collections from the body of the 9137while-stepping loop. However, if `$pc' was not collected, then `tdump' 9138will always attempt to dump using the basic collection list, and may 9139fail if a while-stepping frame does not include all the same data that 9140is collected at the tracepoint hit. 9141 9142 9143File: gdb.info, Node: save tracepoints, Prev: tdump, Up: Analyze Collected Data 9144 914513.2.3 `save tracepoints FILENAME' 9146---------------------------------- 9147 9148This command saves all current tracepoint definitions together with 9149their actions and passcounts, into a file `FILENAME' suitable for use 9150in a later debugging session. To read the saved tracepoint 9151definitions, use the `source' command (*note Command Files::). The 9152`save-tracepoints' command is a deprecated alias for `save tracepoints' 9153 9154 9155File: gdb.info, Node: Tracepoint Variables, Next: Trace Files, Prev: Analyze Collected Data, Up: Tracepoints 9156 915713.3 Convenience Variables for Tracepoints 9158========================================== 9159 9160`(int) $trace_frame' 9161 The current trace snapshot (a.k.a. "frame") number, or -1 if no 9162 snapshot is selected. 9163 9164`(int) $tracepoint' 9165 The tracepoint for the current trace snapshot. 9166 9167`(int) $trace_line' 9168 The line number for the current trace snapshot. 9169 9170`(char []) $trace_file' 9171 The source file for the current trace snapshot. 9172 9173`(char []) $trace_func' 9174 The name of the function containing `$tracepoint'. 9175 9176 Note: `$trace_file' is not suitable for use in `printf', use 9177`output' instead. 9178 9179 Here's a simple example of using these convenience variables for 9180stepping through all the trace snapshots and printing some of their 9181data. Note that these are not the same as trace state variables, which 9182are managed by the target. 9183 9184 (gdb) tfind start 9185 9186 (gdb) while $trace_frame != -1 9187 > output $trace_file 9188 > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint 9189 > tfind 9190 > end 9191 9192 9193File: gdb.info, Node: Trace Files, Prev: Tracepoint Variables, Up: Tracepoints 9194 919513.4 Using Trace Files 9196====================== 9197 9198In some situations, the target running a trace experiment may no longer 9199be available; perhaps it crashed, or the hardware was needed for a 9200different activity. To handle these cases, you can arrange to dump the 9201trace data into a file, and later use that file as a source of trace 9202data, via the `target tfile' command. 9203 9204`tsave [ -r ] FILENAME' 9205 Save the trace data to FILENAME. By default, this command assumes 9206 that FILENAME refers to the host filesystem, so if necessary GDB 9207 will copy raw trace data up from the target and then save it. If 9208 the target supports it, you can also supply the optional argument 9209 `-r' ("remote") to direct the target to save the data directly 9210 into FILENAME in its own filesystem, which may be more efficient 9211 if the trace buffer is very large. (Note, however, that `target 9212 tfile' can only read from files accessible to the host.) 9213 9214`target tfile FILENAME' 9215 Use the file named FILENAME as a source of trace data. Commands 9216 that examine data work as they do with a live target, but it is not 9217 possible to run any new trace experiments. `tstatus' will report 9218 the state of the trace run at the moment the data was saved, as 9219 well as the current trace frame you are examining. FILENAME must 9220 be on a filesystem accessible to the host. 9221 9222 9223 9224File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top 9225 922614 Debugging Programs That Use Overlays 9227*************************************** 9228 9229If your program is too large to fit completely in your target system's 9230memory, you can sometimes use "overlays" to work around this problem. 9231GDB provides some support for debugging programs that use overlays. 9232 9233* Menu: 9234 9235* How Overlays Work:: A general explanation of overlays. 9236* Overlay Commands:: Managing overlays in GDB. 9237* Automatic Overlay Debugging:: GDB can find out which overlays are 9238 mapped by asking the inferior. 9239* Overlay Sample Program:: A sample program using overlays. 9240 9241 9242File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays 9243 924414.1 How Overlays Work 9245====================== 9246 9247Suppose you have a computer whose instruction address space is only 64 9248kilobytes long, but which has much more memory which can be accessed by 9249other means: special instructions, segment registers, or memory 9250management hardware, for example. Suppose further that you want to 9251adapt a program which is larger than 64 kilobytes to run on this system. 9252 9253 One solution is to identify modules of your program which are 9254relatively independent, and need not call each other directly; call 9255these modules "overlays". Separate the overlays from the main program, 9256and place their machine code in the larger memory. Place your main 9257program in instruction memory, but leave at least enough space there to 9258hold the largest overlay as well. 9259 9260 Now, to call a function located in an overlay, you must first copy 9261that overlay's machine code from the large memory into the space set 9262aside for it in the instruction memory, and then jump to its entry point 9263there. 9264 9265 Data Instruction Larger 9266 Address Space Address Space Address Space 9267 +-----------+ +-----------+ +-----------+ 9268 | | | | | | 9269 +-----------+ +-----------+ +-----------+<-- overlay 1 9270 | program | | main | .----| overlay 1 | load address 9271 | variables | | program | | +-----------+ 9272 | and heap | | | | | | 9273 +-----------+ | | | +-----------+<-- overlay 2 9274 | | +-----------+ | | | load address 9275 +-----------+ | | | .-| overlay 2 | 9276 | | | | | | 9277 mapped --->+-----------+ | | +-----------+ 9278 address | | | | | | 9279 | overlay | <-' | | | 9280 | area | <---' +-----------+<-- overlay 3 9281 | | <---. | | load address 9282 +-----------+ `--| overlay 3 | 9283 | | | | 9284 +-----------+ | | 9285 +-----------+ 9286 | | 9287 +-----------+ 9288 9289 A code overlay 9290 9291 The diagram (*note A code overlay::) shows a system with separate 9292data and instruction address spaces. To map an overlay, the program 9293copies its code from the larger address space to the instruction 9294address space. Since the overlays shown here all use the same mapped 9295address, only one may be mapped at a time. For a system with a single 9296address space for data and instructions, the diagram would be similar, 9297except that the program variables and heap would share an address space 9298with the main program and the overlay area. 9299 9300 An overlay loaded into instruction memory and ready for use is 9301called a "mapped" overlay; its "mapped address" is its address in the 9302instruction memory. An overlay not present (or only partially present) 9303in instruction memory is called "unmapped"; its "load address" is its 9304address in the larger memory. The mapped address is also called the 9305"virtual memory address", or "VMA"; the load address is also called the 9306"load memory address", or "LMA". 9307 9308 Unfortunately, overlays are not a completely transparent way to 9309adapt a program to limited instruction memory. They introduce a new 9310set of global constraints you must keep in mind as you design your 9311program: 9312 9313 * Before calling or returning to a function in an overlay, your 9314 program must make sure that overlay is actually mapped. 9315 Otherwise, the call or return will transfer control to the right 9316 address, but in the wrong overlay, and your program will probably 9317 crash. 9318 9319 * If the process of mapping an overlay is expensive on your system, 9320 you will need to choose your overlays carefully to minimize their 9321 effect on your program's performance. 9322 9323 * The executable file you load onto your system must contain each 9324 overlay's instructions, appearing at the overlay's load address, 9325 not its mapped address. However, each overlay's instructions must 9326 be relocated and its symbols defined as if the overlay were at its 9327 mapped address. You can use GNU linker scripts to specify 9328 different load and relocation addresses for pieces of your 9329 program; see *note Overlay Description: (ld.info)Overlay 9330 Description. 9331 9332 * The procedure for loading executable files onto your system must 9333 be able to load their contents into the larger address space as 9334 well as the instruction and data spaces. 9335 9336 9337 The overlay system described above is rather simple, and could be 9338improved in many ways: 9339 9340 * If your system has suitable bank switch registers or memory 9341 management hardware, you could use those facilities to make an 9342 overlay's load area contents simply appear at their mapped address 9343 in instruction space. This would probably be faster than copying 9344 the overlay to its mapped area in the usual way. 9345 9346 * If your overlays are small enough, you could set aside more than 9347 one overlay area, and have more than one overlay mapped at a time. 9348 9349 * You can use overlays to manage data, as well as instructions. In 9350 general, data overlays are even less transparent to your design 9351 than code overlays: whereas code overlays only require care when 9352 you call or return to functions, data overlays require care every 9353 time you access the data. Also, if you change the contents of a 9354 data overlay, you must copy its contents back out to its load 9355 address before you can copy a different data overlay into the same 9356 mapped area. 9357 9358 9359 9360File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays 9361 936214.2 Overlay Commands 9363===================== 9364 9365To use GDB's overlay support, each overlay in your program must 9366correspond to a separate section of the executable file. The section's 9367virtual memory address and load memory address must be the overlay's 9368mapped and load addresses. Identifying overlays with sections allows 9369GDB to determine the appropriate address of a function or variable, 9370depending on whether the overlay is mapped or not. 9371 9372 GDB's overlay commands all start with the word `overlay'; you can 9373abbreviate this as `ov' or `ovly'. The commands are: 9374 9375`overlay off' 9376 Disable GDB's overlay support. When overlay support is disabled, 9377 GDB assumes that all functions and variables are always present at 9378 their mapped addresses. By default, GDB's overlay support is 9379 disabled. 9380 9381`overlay manual' 9382 Enable "manual" overlay debugging. In this mode, GDB relies on 9383 you to tell it which overlays are mapped, and which are not, using 9384 the `overlay map-overlay' and `overlay unmap-overlay' commands 9385 described below. 9386 9387`overlay map-overlay OVERLAY' 9388`overlay map OVERLAY' 9389 Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of 9390 the object file section containing the overlay. When an overlay 9391 is mapped, GDB assumes it can find the overlay's functions and 9392 variables at their mapped addresses. GDB assumes that any other 9393 overlays whose mapped ranges overlap that of OVERLAY are now 9394 unmapped. 9395 9396`overlay unmap-overlay OVERLAY' 9397`overlay unmap OVERLAY' 9398 Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the 9399 name of the object file section containing the overlay. When an 9400 overlay is unmapped, GDB assumes it can find the overlay's 9401 functions and variables at their load addresses. 9402 9403`overlay auto' 9404 Enable "automatic" overlay debugging. In this mode, GDB consults 9405 a data structure the overlay manager maintains in the inferior to 9406 see which overlays are mapped. For details, see *note Automatic 9407 Overlay Debugging::. 9408 9409`overlay load-target' 9410`overlay load' 9411 Re-read the overlay table from the inferior. Normally, GDB 9412 re-reads the table GDB automatically each time the inferior stops, 9413 so this command should only be necessary if you have changed the 9414 overlay mapping yourself using GDB. This command is only useful 9415 when using automatic overlay debugging. 9416 9417`overlay list-overlays' 9418`overlay list' 9419 Display a list of the overlays currently mapped, along with their 9420 mapped addresses, load addresses, and sizes. 9421 9422 9423 Normally, when GDB prints a code address, it includes the name of 9424the function the address falls in: 9425 9426 (gdb) print main 9427 $3 = {int ()} 0x11a0 <main> 9428 When overlay debugging is enabled, GDB recognizes code in unmapped 9429overlays, and prints the names of unmapped functions with asterisks 9430around them. For example, if `foo' is a function in an unmapped 9431overlay, GDB prints it this way: 9432 9433 (gdb) overlay list 9434 No sections are mapped. 9435 (gdb) print foo 9436 $5 = {int (int)} 0x100000 <*foo*> 9437 When `foo''s overlay is mapped, GDB prints the function's name 9438normally: 9439 9440 (gdb) overlay list 9441 Section .ov.foo.text, loaded at 0x100000 - 0x100034, 9442 mapped at 0x1016 - 0x104a 9443 (gdb) print foo 9444 $6 = {int (int)} 0x1016 <foo> 9445 9446 When overlay debugging is enabled, GDB can find the correct address 9447for functions and variables in an overlay, whether or not the overlay 9448is mapped. This allows most GDB commands, like `break' and 9449`disassemble', to work normally, even on unmapped code. However, GDB's 9450breakpoint support has some limitations: 9451 9452 * You can set breakpoints in functions in unmapped overlays, as long 9453 as GDB can write to the overlay at its load address. 9454 9455 * GDB can not set hardware or simulator-based breakpoints in 9456 unmapped overlays. However, if you set a breakpoint at the end of 9457 your overlay manager (and tell GDB which overlays are now mapped, 9458 if you are using manual overlay management), GDB will re-set its 9459 breakpoints properly. 9460 9461 9462File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays 9463 946414.3 Automatic Overlay Debugging 9465================================ 9466 9467GDB can automatically track which overlays are mapped and which are 9468not, given some simple co-operation from the overlay manager in the 9469inferior. If you enable automatic overlay debugging with the `overlay 9470auto' command (*note Overlay Commands::), GDB looks in the inferior's 9471memory for certain variables describing the current state of the 9472overlays. 9473 9474 Here are the variables your overlay manager must define to support 9475GDB's automatic overlay debugging: 9476 9477`_ovly_table': 9478 This variable must be an array of the following structures: 9479 9480 struct 9481 { 9482 /* The overlay's mapped address. */ 9483 unsigned long vma; 9484 9485 /* The size of the overlay, in bytes. */ 9486 unsigned long size; 9487 9488 /* The overlay's load address. */ 9489 unsigned long lma; 9490 9491 /* Non-zero if the overlay is currently mapped; 9492 zero otherwise. */ 9493 unsigned long mapped; 9494 } 9495 9496`_novlys': 9497 This variable must be a four-byte signed integer, holding the total 9498 number of elements in `_ovly_table'. 9499 9500 9501 To decide whether a particular overlay is mapped or not, GDB looks 9502for an entry in `_ovly_table' whose `vma' and `lma' members equal the 9503VMA and LMA of the overlay's section in the executable file. When GDB 9504finds a matching entry, it consults the entry's `mapped' member to 9505determine whether the overlay is currently mapped. 9506 9507 In addition, your overlay manager may define a function called 9508`_ovly_debug_event'. If this function is defined, GDB will silently 9509set a breakpoint there. If the overlay manager then calls this 9510function whenever it has changed the overlay table, this will enable 9511GDB to accurately keep track of which overlays are in program memory, 9512and update any breakpoints that may be set in overlays. This will 9513allow breakpoints to work even if the overlays are kept in ROM or other 9514non-writable memory while they are not being executed. 9515 9516 9517File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays 9518 951914.4 Overlay Sample Program 9520=========================== 9521 9522When linking a program which uses overlays, you must place the overlays 9523at their load addresses, while relocating them to run at their mapped 9524addresses. To do this, you must write a linker script (*note Overlay 9525Description: (ld.info)Overlay Description.). Unfortunately, since 9526linker scripts are specific to a particular host system, target 9527architecture, and target memory layout, this manual cannot provide 9528portable sample code demonstrating GDB's overlay support. 9529 9530 However, the GDB source distribution does contain an overlaid 9531program, with linker scripts for a few systems, as part of its test 9532suite. The program consists of the following files from 9533`gdb/testsuite/gdb.base': 9534 9535`overlays.c' 9536 The main program file. 9537 9538`ovlymgr.c' 9539 A simple overlay manager, used by `overlays.c'. 9540 9541`foo.c' 9542`bar.c' 9543`baz.c' 9544`grbx.c' 9545 Overlay modules, loaded and used by `overlays.c'. 9546 9547`d10v.ld' 9548`m32r.ld' 9549 Linker scripts for linking the test program on the `d10v-elf' and 9550 `m32r-elf' targets. 9551 9552 You can build the test program using the `d10v-elf' GCC 9553cross-compiler like this: 9554 9555 $ d10v-elf-gcc -g -c overlays.c 9556 $ d10v-elf-gcc -g -c ovlymgr.c 9557 $ d10v-elf-gcc -g -c foo.c 9558 $ d10v-elf-gcc -g -c bar.c 9559 $ d10v-elf-gcc -g -c baz.c 9560 $ d10v-elf-gcc -g -c grbx.c 9561 $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ 9562 baz.o grbx.o -Wl,-Td10v.ld -o overlays 9563 9564 The build process is identical for any other architecture, except 9565that you must substitute the appropriate compiler and linker script for 9566the target system for `d10v-elf-gcc' and `d10v.ld'. 9567 9568 9569File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, Up: Top 9570 957115 Using GDB with Different Languages 9572************************************* 9573 9574Although programming languages generally have common aspects, they are 9575rarely expressed in the same manner. For instance, in ANSI C, 9576dereferencing a pointer `p' is accomplished by `*p', but in Modula-2, 9577it is accomplished by `p^'. Values can also be represented (and 9578displayed) differently. Hex numbers in C appear as `0x1ae', while in 9579Modula-2 they appear as `1AEH'. 9580 9581 Language-specific information is built into GDB for some languages, 9582allowing you to express operations like the above in your program's 9583native language, and allowing GDB to output values in a manner 9584consistent with the syntax of your program's native language. The 9585language you use to build expressions is called the "working language". 9586 9587* Menu: 9588 9589* Setting:: Switching between source languages 9590* Show:: Displaying the language 9591* Checks:: Type and range checks 9592* Supported Languages:: Supported languages 9593* Unsupported Languages:: Unsupported languages 9594 9595 9596File: gdb.info, Node: Setting, Next: Show, Up: Languages 9597 959815.1 Switching Between Source Languages 9599======================================= 9600 9601There are two ways to control the working language--either have GDB set 9602it automatically, or select it manually yourself. You can use the `set 9603language' command for either purpose. On startup, GDB defaults to 9604setting the language automatically. The working language is used to 9605determine how expressions you type are interpreted, how values are 9606printed, etc. 9607 9608 In addition to the working language, every source file that GDB 9609knows about has its own working language. For some object file 9610formats, the compiler might indicate which language a particular source 9611file is in. However, most of the time GDB infers the language from the 9612name of the file. The language of a source file controls whether C++ 9613names are demangled--this way `backtrace' can show each frame 9614appropriately for its own language. There is no way to set the 9615language of a source file from within GDB, but you can set the language 9616associated with a filename extension. *Note Displaying the Language: 9617Show. 9618 9619 This is most commonly a problem when you use a program, such as 9620`cfront' or `f2c', that generates C but is written in another language. 9621In that case, make the program use `#line' directives in its C output; 9622that way GDB will know the correct language of the source code of the 9623original program, and will display that source code, not the generated 9624C code. 9625 9626* Menu: 9627 9628* Filenames:: Filename extensions and languages. 9629* Manually:: Setting the working language manually 9630* Automatically:: Having GDB infer the source language 9631 9632 9633File: gdb.info, Node: Filenames, Next: Manually, Up: Setting 9634 963515.1.1 List of Filename Extensions and Languages 9636------------------------------------------------ 9637 9638If a source file name ends in one of the following extensions, then GDB 9639infers that its language is the one indicated. 9640 9641`.ada' 9642`.ads' 9643`.adb' 9644`.a' 9645 Ada source file. 9646 9647`.c' 9648 C source file 9649 9650`.C' 9651`.cc' 9652`.cp' 9653`.cpp' 9654`.cxx' 9655`.c++' 9656 C++ source file 9657 9658`.d' 9659 D source file 9660 9661`.m' 9662 Objective-C source file 9663 9664`.f' 9665`.F' 9666 Fortran source file 9667 9668`.mod' 9669 Modula-2 source file 9670 9671`.s' 9672`.S' 9673 Assembler source file. This actually behaves almost like C, but 9674 GDB does not skip over function prologues when stepping. 9675 9676 In addition, you may set the language associated with a filename 9677extension. *Note Displaying the Language: Show. 9678 9679 9680File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting 9681 968215.1.2 Setting the Working Language 9683----------------------------------- 9684 9685If you allow GDB to set the language automatically, expressions are 9686interpreted the same way in your debugging session and your program. 9687 9688 If you wish, you may set the language manually. To do this, issue 9689the command `set language LANG', where LANG is the name of a language, 9690such as `c' or `modula-2'. For a list of the supported languages, type 9691`set language'. 9692 9693 Setting the language manually prevents GDB from updating the working 9694language automatically. This can lead to confusion if you try to debug 9695a program when the working language is not the same as the source 9696language, when an expression is acceptable to both languages--but means 9697different things. For instance, if the current source file were 9698written in C, and GDB was parsing Modula-2, a command such as: 9699 9700 print a = b + c 9701 9702might not have the effect you intended. In C, this means to add `b' 9703and `c' and place the result in `a'. The result printed would be the 9704value of `a'. In Modula-2, this means to compare `a' to the result of 9705`b+c', yielding a `BOOLEAN' value. 9706 9707 9708File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting 9709 971015.1.3 Having GDB Infer the Source Language 9711------------------------------------------- 9712 9713To have GDB set the working language automatically, use `set language 9714local' or `set language auto'. GDB then infers the working language. 9715That is, when your program stops in a frame (usually by encountering a 9716breakpoint), GDB sets the working language to the language recorded for 9717the function in that frame. If the language for a frame is unknown 9718(that is, if the function or block corresponding to the frame was 9719defined in a source file that does not have a recognized extension), 9720the current working language is not changed, and GDB issues a warning. 9721 9722 This may not seem necessary for most programs, which are written 9723entirely in one source language. However, program modules and libraries 9724written in one source language can be used by a main program written in 9725a different source language. Using `set language auto' in this case 9726frees you from having to set the working language manually. 9727 9728 9729File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages 9730 973115.2 Displaying the Language 9732============================ 9733 9734The following commands help you find out which language is the working 9735language, and also what language source files were written in. 9736 9737`show language' 9738 Display the current working language. This is the language you 9739 can use with commands such as `print' to build and compute 9740 expressions that may involve variables in your program. 9741 9742`info frame' 9743 Display the source language for this frame. This language becomes 9744 the working language if you use an identifier from this frame. 9745 *Note Information about a Frame: Frame Info, to identify the other 9746 information listed here. 9747 9748`info source' 9749 Display the source language of this source file. *Note Examining 9750 the Symbol Table: Symbols, to identify the other information 9751 listed here. 9752 9753 In unusual circumstances, you may have source files with extensions 9754not in the standard list. You can then set the extension associated 9755with a language explicitly: 9756 9757`set extension-language EXT LANGUAGE' 9758 Tell GDB that source files with extension EXT are to be assumed as 9759 written in the source language LANGUAGE. 9760 9761`info extensions' 9762 List all the filename extensions and the associated languages. 9763 9764 9765File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages 9766 976715.3 Type and Range Checking 9768============================ 9769 9770 _Warning:_ In this release, the GDB commands for type and range 9771 checking are included, but they do not yet have any effect. This 9772 section documents the intended facilities. 9773 9774 Some languages are designed to guard you against making seemingly 9775common errors through a series of compile- and run-time checks. These 9776include checking the type of arguments to functions and operators, and 9777making sure mathematical overflows are caught at run time. Checks such 9778as these help to ensure a program's correctness once it has been 9779compiled by eliminating type mismatches, and providing active checks 9780for range errors when your program is running. 9781 9782 GDB can check for conditions like the above if you wish. Although 9783GDB does not check the statements in your program, it can check 9784expressions entered directly into GDB for evaluation via the `print' 9785command, for example. As with the working language, GDB can also 9786decide whether or not to check automatically based on your program's 9787source language. *Note Supported Languages: Supported Languages, for 9788the default settings of supported languages. 9789 9790* Menu: 9791 9792* Type Checking:: An overview of type checking 9793* Range Checking:: An overview of range checking 9794 9795 9796File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks 9797 979815.3.1 An Overview of Type Checking 9799----------------------------------- 9800 9801Some languages, such as Modula-2, are strongly typed, meaning that the 9802arguments to operators and functions have to be of the correct type, 9803otherwise an error occurs. These checks prevent type mismatch errors 9804from ever causing any run-time problems. For example, 9805 9806 1 + 2 => 3 9807but 9808 error--> 1 + 2.3 9809 9810 The second example fails because the `CARDINAL' 1 is not 9811type-compatible with the `REAL' 2.3. 9812 9813 For the expressions you use in GDB commands, you can tell the GDB 9814type checker to skip checking; to treat any mismatches as errors and 9815abandon the expression; or to only issue warnings when type mismatches 9816occur, but evaluate the expression anyway. When you choose the last of 9817these, GDB evaluates expressions like the second example above, but 9818also issues a warning. 9819 9820 Even if you turn type checking off, there may be other reasons 9821related to type that prevent GDB from evaluating an expression. For 9822instance, GDB does not know how to add an `int' and a `struct foo'. 9823These particular type errors have nothing to do with the language in 9824use, and usually arise from expressions, such as the one described 9825above, which make little sense to evaluate anyway. 9826 9827 Each language defines to what degree it is strict about type. For 9828instance, both Modula-2 and C require the arguments to arithmetical 9829operators to be numbers. In C, enumerated types and pointers can be 9830represented as numbers, so that they are valid arguments to mathematical 9831operators. *Note Supported Languages: Supported Languages, for further 9832details on specific languages. 9833 9834 GDB provides some additional commands for controlling the type 9835checker: 9836 9837`set check type auto' 9838 Set type checking on or off based on the current working language. 9839 *Note Supported Languages: Supported Languages, for the default 9840 settings for each language. 9841 9842`set check type on' 9843`set check type off' 9844 Set type checking on or off, overriding the default setting for the 9845 current working language. Issue a warning if the setting does not 9846 match the language default. If any type mismatches occur in 9847 evaluating an expression while type checking is on, GDB prints a 9848 message and aborts evaluation of the expression. 9849 9850`set check type warn' 9851 Cause the type checker to issue warnings, but to always attempt to 9852 evaluate the expression. Evaluating the expression may still be 9853 impossible for other reasons. For example, GDB cannot add numbers 9854 and structures. 9855 9856`show type' 9857 Show the current setting of the type checker, and whether or not 9858 GDB is setting it automatically. 9859 9860 9861File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks 9862 986315.3.2 An Overview of Range Checking 9864------------------------------------ 9865 9866In some languages (such as Modula-2), it is an error to exceed the 9867bounds of a type; this is enforced with run-time checks. Such range 9868checking is meant to ensure program correctness by making sure 9869computations do not overflow, or indices on an array element access do 9870not exceed the bounds of the array. 9871 9872 For expressions you use in GDB commands, you can tell GDB to treat 9873range errors in one of three ways: ignore them, always treat them as 9874errors and abandon the expression, or issue warnings but evaluate the 9875expression anyway. 9876 9877 A range error can result from numerical overflow, from exceeding an 9878array index bound, or when you type a constant that is not a member of 9879any type. Some languages, however, do not treat overflows as an error. 9880In many implementations of C, mathematical overflow causes the result 9881to "wrap around" to lower values--for example, if M is the largest 9882integer value, and S is the smallest, then 9883 9884 M + 1 => S 9885 9886 This, too, is specific to individual languages, and in some cases 9887specific to individual compilers or machines. *Note Supported 9888Languages: Supported Languages, for further details on specific 9889languages. 9890 9891 GDB provides some additional commands for controlling the range 9892checker: 9893 9894`set check range auto' 9895 Set range checking on or off based on the current working language. 9896 *Note Supported Languages: Supported Languages, for the default 9897 settings for each language. 9898 9899`set check range on' 9900`set check range off' 9901 Set range checking on or off, overriding the default setting for 9902 the current working language. A warning is issued if the setting 9903 does not match the language default. If a range error occurs and 9904 range checking is on, then a message is printed and evaluation of 9905 the expression is aborted. 9906 9907`set check range warn' 9908 Output messages when the GDB range checker detects a range error, 9909 but attempt to evaluate the expression anyway. Evaluating the 9910 expression may still be impossible for other reasons, such as 9911 accessing memory that the process does not own (a typical example 9912 from many Unix systems). 9913 9914`show range' 9915 Show the current setting of the range checker, and whether or not 9916 it is being set automatically by GDB. 9917 9918 9919File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages 9920 992115.4 Supported Languages 9922======================== 9923 9924GDB supports C, C++, D, Objective-C, Fortran, Java, Pascal, assembly, 9925Modula-2, and Ada. Some GDB features may be used in expressions 9926regardless of the language you use: the GDB `@' and `::' operators, and 9927the `{type}addr' construct (*note Expressions: Expressions.) can be 9928used with the constructs of any supported language. 9929 9930 The following sections detail to what degree each source language is 9931supported by GDB. These sections are not meant to be language 9932tutorials or references, but serve only as a reference guide to what the 9933GDB expression parser accepts, and what input and output formats should 9934look like for different languages. There are many good books written 9935on each of these languages; please look to these for a language 9936reference or tutorial. 9937 9938* Menu: 9939 9940* C:: C and C++ 9941* D:: D 9942* Objective-C:: Objective-C 9943* Fortran:: Fortran 9944* Pascal:: Pascal 9945* Modula-2:: Modula-2 9946* Ada:: Ada 9947 9948 9949File: gdb.info, Node: C, Next: D, Up: Supported Languages 9950 995115.4.1 C and C++ 9952---------------- 9953 9954Since C and C++ are so closely related, many features of GDB apply to 9955both languages. Whenever this is the case, we discuss those languages 9956together. 9957 9958 The C++ debugging facilities are jointly implemented by the C++ 9959compiler and GDB. Therefore, to debug your C++ code effectively, you 9960must compile your C++ programs with a supported C++ compiler, such as 9961GNU `g++', or the HP ANSI C++ compiler (`aCC'). 9962 9963 For best results when using GNU C++, use the DWARF 2 debugging 9964format; if it doesn't work on your system, try the stabs+ debugging 9965format. You can select those formats explicitly with the `g++' 9966command-line options `-gdwarf-2' and `-gstabs+'. *Note Options for 9967Debugging Your Program or GCC: (gcc.info)Debugging Options. 9968 9969* Menu: 9970 9971* C Operators:: C and C++ operators 9972* C Constants:: C and C++ constants 9973* C Plus Plus Expressions:: C++ expressions 9974* C Defaults:: Default settings for C and C++ 9975* C Checks:: C and C++ type and range checks 9976* Debugging C:: GDB and C 9977* Debugging C Plus Plus:: GDB features for C++ 9978* Decimal Floating Point:: Numbers in Decimal Floating Point format 9979 9980 9981File: gdb.info, Node: C Operators, Next: C Constants, Up: C 9982 998315.4.1.1 C and C++ Operators 9984............................ 9985 9986Operators must be defined on values of specific types. For instance, 9987`+' is defined on numbers, but not on structures. Operators are often 9988defined on groups of types. 9989 9990 For the purposes of C and C++, the following definitions hold: 9991 9992 * _Integral types_ include `int' with any of its storage-class 9993 specifiers; `char'; `enum'; and, for C++, `bool'. 9994 9995 * _Floating-point types_ include `float', `double', and `long 9996 double' (if supported by the target platform). 9997 9998 * _Pointer types_ include all types defined as `(TYPE *)'. 9999 10000 * _Scalar types_ include all of the above. 10001 10002 10003The following operators are supported. They are listed here in order 10004of increasing precedence: 10005 10006`,' 10007 The comma or sequencing operator. Expressions in a 10008 comma-separated list are evaluated from left to right, with the 10009 result of the entire expression being the last expression 10010 evaluated. 10011 10012`=' 10013 Assignment. The value of an assignment expression is the value 10014 assigned. Defined on scalar types. 10015 10016`OP=' 10017 Used in an expression of the form `A OP= B', and translated to 10018 `A = A OP B'. `OP=' and `=' have the same precedence. OP is any 10019 one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*', 10020 `/', `%'. 10021 10022`?:' 10023 The ternary operator. `A ? B : C' can be thought of as: if A 10024 then B else C. A should be of an integral type. 10025 10026`||' 10027 Logical OR. Defined on integral types. 10028 10029`&&' 10030 Logical AND. Defined on integral types. 10031 10032`|' 10033 Bitwise OR. Defined on integral types. 10034 10035`^' 10036 Bitwise exclusive-OR. Defined on integral types. 10037 10038`&' 10039 Bitwise AND. Defined on integral types. 10040 10041`==, !=' 10042 Equality and inequality. Defined on scalar types. The value of 10043 these expressions is 0 for false and non-zero for true. 10044 10045`<, >, <=, >=' 10046 Less than, greater than, less than or equal, greater than or equal. 10047 Defined on scalar types. The value of these expressions is 0 for 10048 false and non-zero for true. 10049 10050`<<, >>' 10051 left shift, and right shift. Defined on integral types. 10052 10053`@' 10054 The GDB "artificial array" operator (*note Expressions: 10055 Expressions.). 10056 10057`+, -' 10058 Addition and subtraction. Defined on integral types, 10059 floating-point types and pointer types. 10060 10061`*, /, %' 10062 Multiplication, division, and modulus. Multiplication and 10063 division are defined on integral and floating-point types. 10064 Modulus is defined on integral types. 10065 10066`++, --' 10067 Increment and decrement. When appearing before a variable, the 10068 operation is performed before the variable is used in an 10069 expression; when appearing after it, the variable's value is used 10070 before the operation takes place. 10071 10072`*' 10073 Pointer dereferencing. Defined on pointer types. Same precedence 10074 as `++'. 10075 10076`&' 10077 Address operator. Defined on variables. Same precedence as `++'. 10078 10079 For debugging C++, GDB implements a use of `&' beyond what is 10080 allowed in the C++ language itself: you can use `&(&REF)' to 10081 examine the address where a C++ reference variable (declared with 10082 `&REF') is stored. 10083 10084`-' 10085 Negative. Defined on integral and floating-point types. Same 10086 precedence as `++'. 10087 10088`!' 10089 Logical negation. Defined on integral types. Same precedence as 10090 `++'. 10091 10092`~' 10093 Bitwise complement operator. Defined on integral types. Same 10094 precedence as `++'. 10095 10096`., ->' 10097 Structure member, and pointer-to-structure member. For 10098 convenience, GDB regards the two as equivalent, choosing whether 10099 to dereference a pointer based on the stored type information. 10100 Defined on `struct' and `union' data. 10101 10102`.*, ->*' 10103 Dereferences of pointers to members. 10104 10105`[]' 10106 Array indexing. `A[I]' is defined as `*(A+I)'. Same precedence 10107 as `->'. 10108 10109`()' 10110 Function parameter list. Same precedence as `->'. 10111 10112`::' 10113 C++ scope resolution operator. Defined on `struct', `union', and 10114 `class' types. 10115 10116`::' 10117 Doubled colons also represent the GDB scope operator (*note 10118 Expressions: Expressions.). Same precedence as `::', above. 10119 10120 If an operator is redefined in the user code, GDB usually attempts 10121to invoke the redefined version instead of using the operator's 10122predefined meaning. 10123 10124 10125File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C 10126 1012715.4.1.2 C and C++ Constants 10128............................ 10129 10130GDB allows you to express the constants of C and C++ in the following 10131ways: 10132 10133 * Integer constants are a sequence of digits. Octal constants are 10134 specified by a leading `0' (i.e. zero), and hexadecimal constants 10135 by a leading `0x' or `0X'. Constants may also end with a letter 10136 `l', specifying that the constant should be treated as a `long' 10137 value. 10138 10139 * Floating point constants are a sequence of digits, followed by a 10140 decimal point, followed by a sequence of digits, and optionally 10141 followed by an exponent. An exponent is of the form: 10142 `e[[+]|-]NNN', where NNN is another sequence of digits. The `+' 10143 is optional for positive exponents. A floating-point constant may 10144 also end with a letter `f' or `F', specifying that the constant 10145 should be treated as being of the `float' (as opposed to the 10146 default `double') type; or with a letter `l' or `L', which 10147 specifies a `long double' constant. 10148 10149 * Enumerated constants consist of enumerated identifiers, or their 10150 integral equivalents. 10151 10152 * Character constants are a single character surrounded by single 10153 quotes (`''), or a number--the ordinal value of the corresponding 10154 character (usually its ASCII value). Within quotes, the single 10155 character may be represented by a letter or by "escape sequences", 10156 which are of the form `\NNN', where NNN is the octal representation 10157 of the character's ordinal value; or of the form `\X', where `X' 10158 is a predefined special character--for example, `\n' for newline. 10159 10160 * String constants are a sequence of character constants surrounded 10161 by double quotes (`"'). Any valid character constant (as described 10162 above) may appear. Double quotes within the string must be 10163 preceded by a backslash, so for instance `"a\"b'c"' is a string of 10164 five characters. 10165 10166 * Pointer constants are an integral value. You can also write 10167 pointers to constants using the C operator `&'. 10168 10169 * Array constants are comma-separated lists surrounded by braces `{' 10170 and `}'; for example, `{1,2,3}' is a three-element array of 10171 integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and 10172 `{&"hi", &"there", &"fred"}' is a three-element array of pointers. 10173 10174 10175File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C 10176 1017715.4.1.3 C++ Expressions 10178........................ 10179 10180GDB expression handling can interpret most C++ expressions. 10181 10182 _Warning:_ GDB can only debug C++ code if you use the proper 10183 compiler and the proper debug format. Currently, GDB works best 10184 when debugging C++ code that is compiled with GCC 2.95.3 or with 10185 GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'. 10186 DWARF 2 is preferred over stabs+. Most configurations of GCC emit 10187 either DWARF 2 or stabs+ as their default debug format, so you 10188 usually don't need to specify a debug format explicitly. Other 10189 compilers and/or debug formats are likely to work badly or not at 10190 all when using GDB to debug C++ code. 10191 10192 1. Member function calls are allowed; you can use expressions like 10193 10194 count = aml->GetOriginal(x, y) 10195 10196 2. While a member function is active (in the selected stack frame), 10197 your expressions have the same namespace available as the member 10198 function; that is, GDB allows implicit references to the class 10199 instance pointer `this' following the same rules as C++. 10200 10201 3. You can call overloaded functions; GDB resolves the function call 10202 to the right definition, with some restrictions. GDB does not 10203 perform overload resolution involving user-defined type 10204 conversions, calls to constructors, or instantiations of templates 10205 that do not exist in the program. It also cannot handle ellipsis 10206 argument lists or default arguments. 10207 10208 It does perform integral conversions and promotions, floating-point 10209 promotions, arithmetic conversions, pointer conversions, 10210 conversions of class objects to base classes, and standard 10211 conversions such as those of functions or arrays to pointers; it 10212 requires an exact match on the number of function arguments. 10213 10214 Overload resolution is always performed, unless you have specified 10215 `set overload-resolution off'. *Note GDB Features for C++: 10216 Debugging C Plus Plus. 10217 10218 You must specify `set overload-resolution off' in order to use an 10219 explicit function signature to call an overloaded function, as in 10220 p 'foo(char,int)'('x', 13) 10221 10222 The GDB command-completion facility can simplify this; see *note 10223 Command Completion: Completion. 10224 10225 4. GDB understands variables declared as C++ references; you can use 10226 them in expressions just as you do in C++ source--they are 10227 automatically dereferenced. 10228 10229 In the parameter list shown when GDB displays a frame, the values 10230 of reference variables are not displayed (unlike other variables); 10231 this avoids clutter, since references are often used for large 10232 structures. The _address_ of a reference variable is always 10233 shown, unless you have specified `set print address off'. 10234 10235 5. GDB supports the C++ name resolution operator `::'--your 10236 expressions can use it just as expressions in your program do. 10237 Since one scope may be defined in another, you can use `::' 10238 repeatedly if necessary, for example in an expression like 10239 `SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by 10240 reference to source files, in both C and C++ debugging (*note 10241 Program Variables: Variables.). 10242 10243 In addition, when used with HP's C++ compiler, GDB supports calling 10244virtual functions correctly, printing out virtual bases of objects, 10245calling functions in a base subobject, casting objects, and invoking 10246user-defined operators. 10247 10248 10249File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C 10250 1025115.4.1.4 C and C++ Defaults 10252........................... 10253 10254If you allow GDB to set type and range checking automatically, they 10255both default to `off' whenever the working language changes to C or 10256C++. This happens regardless of whether you or GDB selects the working 10257language. 10258 10259 If you allow GDB to set the language automatically, it recognizes 10260source files whose names end with `.c', `.C', or `.cc', etc, and when 10261GDB enters code compiled from one of these files, it sets the working 10262language to C or C++. *Note Having GDB Infer the Source Language: 10263Automatically, for further details. 10264 10265 10266File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C 10267 1026815.4.1.5 C and C++ Type and Range Checks 10269........................................ 10270 10271By default, when GDB parses C or C++ expressions, type checking is not 10272used. However, if you turn type checking on, GDB considers two 10273variables type equivalent if: 10274 10275 * The two variables are structured and have the same structure, 10276 union, or enumerated tag. 10277 10278 * The two variables have the same type name, or types that have been 10279 declared equivalent through `typedef'. 10280 10281 10282 Range checking, if turned on, is done on mathematical operations. 10283Array indices are not checked, since they are often used to index a 10284pointer that is not itself an array. 10285 10286 10287File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C 10288 1028915.4.1.6 GDB and C 10290.................. 10291 10292The `set print union' and `show print union' commands apply to the 10293`union' type. When set to `on', any `union' that is inside a `struct' 10294or `class' is also printed. Otherwise, it appears as `{...}'. 10295 10296 The `@' operator aids in the debugging of dynamic arrays, formed 10297with pointers and a memory allocation function. *Note Expressions: 10298Expressions. 10299 10300 10301File: gdb.info, Node: Debugging C Plus Plus, Next: Decimal Floating Point, Prev: Debugging C, Up: C 10302 1030315.4.1.7 GDB Features for C++ 10304............................. 10305 10306Some GDB commands are particularly useful with C++, and some are 10307designed specifically for use with C++. Here is a summary: 10308 10309`breakpoint menus' 10310 When you want a breakpoint in a function whose name is overloaded, 10311 GDB has the capability to display a menu of possible breakpoint 10312 locations to help you specify which function definition you want. 10313 *Note Ambiguous Expressions: Ambiguous Expressions. 10314 10315`rbreak REGEX' 10316 Setting breakpoints using regular expressions is helpful for 10317 setting breakpoints on overloaded functions that are not members 10318 of any special classes. *Note Setting Breakpoints: Set Breaks. 10319 10320`catch throw' 10321`catch catch' 10322 Debug C++ exception handling using these commands. *Note Setting 10323 Catchpoints: Set Catchpoints. 10324 10325`ptype TYPENAME' 10326 Print inheritance relationships as well as other information for 10327 type TYPENAME. *Note Examining the Symbol Table: Symbols. 10328 10329`set print demangle' 10330`show print demangle' 10331`set print asm-demangle' 10332`show print asm-demangle' 10333 Control whether C++ symbols display in their source form, both when 10334 displaying code as C++ source and when displaying disassemblies. 10335 *Note Print Settings: Print Settings. 10336 10337`set print object' 10338`show print object' 10339 Choose whether to print derived (actual) or declared types of 10340 objects. *Note Print Settings: Print Settings. 10341 10342`set print vtbl' 10343`show print vtbl' 10344 Control the format for printing virtual function tables. *Note 10345 Print Settings: Print Settings. (The `vtbl' commands do not work 10346 on programs compiled with the HP ANSI C++ compiler (`aCC').) 10347 10348`set overload-resolution on' 10349 Enable overload resolution for C++ expression evaluation. The 10350 default is on. For overloaded functions, GDB evaluates the 10351 arguments and searches for a function whose signature matches the 10352 argument types, using the standard C++ conversion rules (see *note 10353 C++ Expressions: C Plus Plus Expressions, for details). If it 10354 cannot find a match, it emits a message. 10355 10356`set overload-resolution off' 10357 Disable overload resolution for C++ expression evaluation. For 10358 overloaded functions that are not class member functions, GDB 10359 chooses the first function of the specified name that it finds in 10360 the symbol table, whether or not its arguments are of the correct 10361 type. For overloaded functions that are class member functions, 10362 GDB searches for a function whose signature _exactly_ matches the 10363 argument types. 10364 10365`show overload-resolution' 10366 Show the current setting of overload resolution. 10367 10368`Overloaded symbol names' 10369 You can specify a particular definition of an overloaded symbol, 10370 using the same notation that is used to declare such symbols in 10371 C++: type `SYMBOL(TYPES)' rather than just SYMBOL. You can also 10372 use the GDB command-line word completion facilities to list the 10373 available choices, or to finish the type list for you. *Note 10374 Command Completion: Completion, for details on how to do this. 10375 10376 10377File: gdb.info, Node: Decimal Floating Point, Prev: Debugging C Plus Plus, Up: C 10378 1037915.4.1.8 Decimal Floating Point format 10380...................................... 10381 10382GDB can examine, set and perform computations with numbers in decimal 10383floating point format, which in the C language correspond to the 10384`_Decimal32', `_Decimal64' and `_Decimal128' types as specified by the 10385extension to support decimal floating-point arithmetic. 10386 10387 There are two encodings in use, depending on the architecture: BID 10388(Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed 10389Decimal) for PowerPC. GDB will use the appropriate encoding for the 10390configured target. 10391 10392 Because of a limitation in `libdecnumber', the library used by GDB 10393to manipulate decimal floating point numbers, it is not possible to 10394convert (using a cast, for example) integers wider than 32-bit to 10395decimal float. 10396 10397 In addition, in order to imitate GDB's behaviour with binary floating 10398point computations, error checking in decimal float operations ignores 10399underflow, overflow and divide by zero exceptions. 10400 10401 In the PowerPC architecture, GDB provides a set of pseudo-registers 10402to inspect `_Decimal128' values stored in floating point registers. 10403See *note PowerPC: PowerPC. for more details. 10404 10405 10406File: gdb.info, Node: D, Next: Objective-C, Prev: C, Up: Supported Languages 10407 1040815.4.2 D 10409-------- 10410 10411GDB can be used to debug programs written in D and compiled with GDC, 10412LDC or DMD compilers. Currently GDB supports only one D specific 10413feature -- dynamic arrays. 10414 10415 10416File: gdb.info, Node: Objective-C, Next: Fortran, Prev: D, Up: Supported Languages 10417 1041815.4.3 Objective-C 10419------------------ 10420 10421This section provides information about some commands and command 10422options that are useful for debugging Objective-C code. See also *note 10423info classes: Symbols, and *note info selectors: Symbols, for a few 10424more commands specific to Objective-C support. 10425 10426* Menu: 10427 10428* Method Names in Commands:: 10429* The Print Command with Objective-C:: 10430 10431 10432File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C 10433 1043415.4.3.1 Method Names in Commands 10435................................. 10436 10437The following commands have been extended to accept Objective-C method 10438names as line specifications: 10439 10440 * `clear' 10441 10442 * `break' 10443 10444 * `info line' 10445 10446 * `jump' 10447 10448 * `list' 10449 10450 A fully qualified Objective-C method name is specified as 10451 10452 -[CLASS METHODNAME] 10453 10454 where the minus sign is used to indicate an instance method and a 10455plus sign (not shown) is used to indicate a class method. The class 10456name CLASS and method name METHODNAME are enclosed in brackets, similar 10457to the way messages are specified in Objective-C source code. For 10458example, to set a breakpoint at the `create' instance method of class 10459`Fruit' in the program currently being debugged, enter: 10460 10461 break -[Fruit create] 10462 10463 To list ten program lines around the `initialize' class method, 10464enter: 10465 10466 list +[NSText initialize] 10467 10468 In the current version of GDB, the plus or minus sign is required. 10469In future versions of GDB, the plus or minus sign will be optional, but 10470you can use it to narrow the search. It is also possible to specify 10471just a method name: 10472 10473 break create 10474 10475 You must specify the complete method name, including any colons. If 10476your program's source files contain more than one `create' method, 10477you'll be presented with a numbered list of classes that implement that 10478method. Indicate your choice by number, or type `0' to exit if none 10479apply. 10480 10481 As another example, to clear a breakpoint established at the 10482`makeKeyAndOrderFront:' method of the `NSWindow' class, enter: 10483 10484 clear -[NSWindow makeKeyAndOrderFront:] 10485 10486 10487File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C 10488 1048915.4.3.2 The Print Command With Objective-C 10490........................................... 10491 10492The print command has also been extended to accept methods. For 10493example: 10494 10495 print -[OBJECT hash] 10496 10497will tell GDB to send the `hash' message to OBJECT and print the 10498result. Also, an additional command has been added, `print-object' or 10499`po' for short, which is meant to print the description of an object. 10500However, this command may only work with certain Objective-C libraries 10501that have a particular hook function, `_NSPrintForDebugger', defined. 10502 10503 10504File: gdb.info, Node: Fortran, Next: Pascal, Prev: Objective-C, Up: Supported Languages 10505 1050615.4.4 Fortran 10507-------------- 10508 10509GDB can be used to debug programs written in Fortran, but it currently 10510supports only the features of Fortran 77 language. 10511 10512 Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers 10513among them) append an underscore to the names of variables and 10514functions. When you debug programs compiled by those compilers, you 10515will need to refer to variables and functions with a trailing 10516underscore. 10517 10518* Menu: 10519 10520* Fortran Operators:: Fortran operators and expressions 10521* Fortran Defaults:: Default settings for Fortran 10522* Special Fortran Commands:: Special GDB commands for Fortran 10523 10524 10525File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran 10526 1052715.4.4.1 Fortran Operators and Expressions 10528.......................................... 10529 10530Operators must be defined on values of specific types. For instance, 10531`+' is defined on numbers, but not on characters or other non- 10532arithmetic types. Operators are often defined on groups of types. 10533 10534`**' 10535 The exponentiation operator. It raises the first operand to the 10536 power of the second one. 10537 10538`:' 10539 The range operator. Normally used in the form of array(low:high) 10540 to represent a section of array. 10541 10542`%' 10543 The access component operator. Normally used to access elements 10544 in derived types. Also suitable for unions. As unions aren't 10545 part of regular Fortran, this can only happen when accessing a 10546 register that uses a gdbarch-defined union type. 10547 10548 10549File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran 10550 1055115.4.4.2 Fortran Defaults 10552......................... 10553 10554Fortran symbols are usually case-insensitive, so GDB by default uses 10555case-insensitive matches for Fortran symbols. You can change that with 10556the `set case-insensitive' command, see *note Symbols::, for the 10557details. 10558 10559 10560File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Defaults, Up: Fortran 10561 1056215.4.4.3 Special Fortran Commands 10563................................. 10564 10565GDB has some commands to support Fortran-specific features, such as 10566displaying common blocks. 10567 10568`info common [COMMON-NAME]' 10569 This command prints the values contained in the Fortran `COMMON' 10570 block whose name is COMMON-NAME. With no argument, the names of 10571 all `COMMON' blocks visible at the current program location are 10572 printed. 10573 10574 10575File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported Languages 10576 1057715.4.5 Pascal 10578------------- 10579 10580Debugging Pascal programs which use sets, subranges, file variables, or 10581nested functions does not currently work. GDB does not support 10582entering expressions, printing values, or similar features using Pascal 10583syntax. 10584 10585 The Pascal-specific command `set print pascal_static-members' 10586controls whether static members of Pascal objects are displayed. *Note 10587pascal_static-members: Print Settings. 10588 10589 10590File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported Languages 10591 1059215.4.6 Modula-2 10593--------------- 10594 10595The extensions made to GDB to support Modula-2 only support output from 10596the GNU Modula-2 compiler (which is currently being developed). Other 10597Modula-2 compilers are not currently supported, and attempting to debug 10598executables produced by them is most likely to give an error as GDB 10599reads in the executable's symbol table. 10600 10601* Menu: 10602 10603* M2 Operators:: Built-in operators 10604* Built-In Func/Proc:: Built-in functions and procedures 10605* M2 Constants:: Modula-2 constants 10606* M2 Types:: Modula-2 types 10607* M2 Defaults:: Default settings for Modula-2 10608* Deviations:: Deviations from standard Modula-2 10609* M2 Checks:: Modula-2 type and range checks 10610* M2 Scope:: The scope operators `::' and `.' 10611* GDB/M2:: GDB and Modula-2 10612 10613 10614File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 10615 1061615.4.6.1 Operators 10617.................. 10618 10619Operators must be defined on values of specific types. For instance, 10620`+' is defined on numbers, but not on structures. Operators are often 10621defined on groups of types. For the purposes of Modula-2, the 10622following definitions hold: 10623 10624 * _Integral types_ consist of `INTEGER', `CARDINAL', and their 10625 subranges. 10626 10627 * _Character types_ consist of `CHAR' and its subranges. 10628 10629 * _Floating-point types_ consist of `REAL'. 10630 10631 * _Pointer types_ consist of anything declared as `POINTER TO TYPE'. 10632 10633 * _Scalar types_ consist of all of the above. 10634 10635 * _Set types_ consist of `SET' and `BITSET' types. 10636 10637 * _Boolean types_ consist of `BOOLEAN'. 10638 10639The following operators are supported, and appear in order of 10640increasing precedence: 10641 10642`,' 10643 Function argument or array index separator. 10644 10645`:=' 10646 Assignment. The value of VAR `:=' VALUE is VALUE. 10647 10648`<, >' 10649 Less than, greater than on integral, floating-point, or enumerated 10650 types. 10651 10652`<=, >=' 10653 Less than or equal to, greater than or equal to on integral, 10654 floating-point and enumerated types, or set inclusion on set 10655 types. Same precedence as `<'. 10656 10657`=, <>, #' 10658 Equality and two ways of expressing inequality, valid on scalar 10659 types. Same precedence as `<'. In GDB scripts, only `<>' is 10660 available for inequality, since `#' conflicts with the script 10661 comment character. 10662 10663`IN' 10664 Set membership. Defined on set types and the types of their 10665 members. Same precedence as `<'. 10666 10667`OR' 10668 Boolean disjunction. Defined on boolean types. 10669 10670`AND, &' 10671 Boolean conjunction. Defined on boolean types. 10672 10673`@' 10674 The GDB "artificial array" operator (*note Expressions: 10675 Expressions.). 10676 10677`+, -' 10678 Addition and subtraction on integral and floating-point types, or 10679 union and difference on set types. 10680 10681`*' 10682 Multiplication on integral and floating-point types, or set 10683 intersection on set types. 10684 10685`/' 10686 Division on floating-point types, or symmetric set difference on 10687 set types. Same precedence as `*'. 10688 10689`DIV, MOD' 10690 Integer division and remainder. Defined on integral types. Same 10691 precedence as `*'. 10692 10693`-' 10694 Negative. Defined on `INTEGER' and `REAL' data. 10695 10696`^' 10697 Pointer dereferencing. Defined on pointer types. 10698 10699`NOT' 10700 Boolean negation. Defined on boolean types. Same precedence as 10701 `^'. 10702 10703`.' 10704 `RECORD' field selector. Defined on `RECORD' data. Same 10705 precedence as `^'. 10706 10707`[]' 10708 Array indexing. Defined on `ARRAY' data. Same precedence as `^'. 10709 10710`()' 10711 Procedure argument list. Defined on `PROCEDURE' objects. Same 10712 precedence as `^'. 10713 10714`::, .' 10715 GDB and Modula-2 scope operators. 10716 10717 _Warning:_ Set expressions and their operations are not yet 10718 supported, so GDB treats the use of the operator `IN', or the use 10719 of operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>=' 10720 on sets as an error. 10721 10722 10723File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 10724 1072515.4.6.2 Built-in Functions and Procedures 10726.......................................... 10727 10728Modula-2 also makes available several built-in procedures and functions. 10729In describing these, the following metavariables are used: 10730 10731A 10732 represents an `ARRAY' variable. 10733 10734C 10735 represents a `CHAR' constant or variable. 10736 10737I 10738 represents a variable or constant of integral type. 10739 10740M 10741 represents an identifier that belongs to a set. Generally used in 10742 the same function with the metavariable S. The type of S should 10743 be `SET OF MTYPE' (where MTYPE is the type of M). 10744 10745N 10746 represents a variable or constant of integral or floating-point 10747 type. 10748 10749R 10750 represents a variable or constant of floating-point type. 10751 10752T 10753 represents a type. 10754 10755V 10756 represents a variable. 10757 10758X 10759 represents a variable or constant of one of many types. See the 10760 explanation of the function for details. 10761 10762 All Modula-2 built-in procedures also return a result, described 10763below. 10764 10765`ABS(N)' 10766 Returns the absolute value of N. 10767 10768`CAP(C)' 10769 If C is a lower case letter, it returns its upper case equivalent, 10770 otherwise it returns its argument. 10771 10772`CHR(I)' 10773 Returns the character whose ordinal value is I. 10774 10775`DEC(V)' 10776 Decrements the value in the variable V by one. Returns the new 10777 value. 10778 10779`DEC(V,I)' 10780 Decrements the value in the variable V by I. Returns the new 10781 value. 10782 10783`EXCL(M,S)' 10784 Removes the element M from the set S. Returns the new set. 10785 10786`FLOAT(I)' 10787 Returns the floating point equivalent of the integer I. 10788 10789`HIGH(A)' 10790 Returns the index of the last member of A. 10791 10792`INC(V)' 10793 Increments the value in the variable V by one. Returns the new 10794 value. 10795 10796`INC(V,I)' 10797 Increments the value in the variable V by I. Returns the new 10798 value. 10799 10800`INCL(M,S)' 10801 Adds the element M to the set S if it is not already there. 10802 Returns the new set. 10803 10804`MAX(T)' 10805 Returns the maximum value of the type T. 10806 10807`MIN(T)' 10808 Returns the minimum value of the type T. 10809 10810`ODD(I)' 10811 Returns boolean TRUE if I is an odd number. 10812 10813`ORD(X)' 10814 Returns the ordinal value of its argument. For example, the 10815 ordinal value of a character is its ASCII value (on machines 10816 supporting the ASCII character set). X must be of an ordered 10817 type, which include integral, character and enumerated types. 10818 10819`SIZE(X)' 10820 Returns the size of its argument. X can be a variable or a type. 10821 10822`TRUNC(R)' 10823 Returns the integral part of R. 10824 10825`TSIZE(X)' 10826 Returns the size of its argument. X can be a variable or a type. 10827 10828`VAL(T,I)' 10829 Returns the member of the type T whose ordinal value is I. 10830 10831 _Warning:_ Sets and their operations are not yet supported, so 10832 GDB treats the use of procedures `INCL' and `EXCL' as an error. 10833 10834 10835File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2 10836 1083715.4.6.3 Constants 10838.................. 10839 10840GDB allows you to express the constants of Modula-2 in the following 10841ways: 10842 10843 * Integer constants are simply a sequence of digits. When used in an 10844 expression, a constant is interpreted to be type-compatible with 10845 the rest of the expression. Hexadecimal integers are specified by 10846 a trailing `H', and octal integers by a trailing `B'. 10847 10848 * Floating point constants appear as a sequence of digits, followed 10849 by a decimal point and another sequence of digits. An optional 10850 exponent can then be specified, in the form `E[+|-]NNN', where 10851 `[+|-]NNN' is the desired exponent. All of the digits of the 10852 floating point constant must be valid decimal (base 10) digits. 10853 10854 * Character constants consist of a single character enclosed by a 10855 pair of like quotes, either single (`'') or double (`"'). They may 10856 also be expressed by their ordinal value (their ASCII value, 10857 usually) followed by a `C'. 10858 10859 * String constants consist of a sequence of characters enclosed by a 10860 pair of like quotes, either single (`'') or double (`"'). Escape 10861 sequences in the style of C are also allowed. *Note C and C++ 10862 Constants: C Constants, for a brief explanation of escape 10863 sequences. 10864 10865 * Enumerated constants consist of an enumerated identifier. 10866 10867 * Boolean constants consist of the identifiers `TRUE' and `FALSE'. 10868 10869 * Pointer constants consist of integral values only. 10870 10871 * Set constants are not yet supported. 10872 10873 10874File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 10875 1087615.4.6.4 Modula-2 Types 10877....................... 10878 10879Currently GDB can print the following data types in Modula-2 syntax: 10880array types, record types, set types, pointer types, procedure types, 10881enumerated types, subrange types and base types. You can also print 10882the contents of variables declared using these type. This section 10883gives a number of simple source code examples together with sample GDB 10884sessions. 10885 10886 The first example contains the following section of code: 10887 10888 VAR 10889 s: SET OF CHAR ; 10890 r: [20..40] ; 10891 10892and you can request GDB to interrogate the type and value of `r' and 10893`s'. 10894 10895 (gdb) print s 10896 {'A'..'C', 'Z'} 10897 (gdb) ptype s 10898 SET OF CHAR 10899 (gdb) print r 10900 21 10901 (gdb) ptype r 10902 [20..40] 10903 10904Likewise if your source code declares `s' as: 10905 10906 VAR 10907 s: SET ['A'..'Z'] ; 10908 10909then you may query the type of `s' by: 10910 10911 (gdb) ptype s 10912 type = SET ['A'..'Z'] 10913 10914Note that at present you cannot interactively manipulate set 10915expressions using the debugger. 10916 10917 The following example shows how you might declare an array in 10918Modula-2 and how you can interact with GDB to print its type and 10919contents: 10920 10921 VAR 10922 s: ARRAY [-10..10] OF CHAR ; 10923 10924 (gdb) ptype s 10925 ARRAY [-10..10] OF CHAR 10926 10927 Note that the array handling is not yet complete and although the 10928type is printed correctly, expression handling still assumes that all 10929arrays have a lower bound of zero and not `-10' as in the example above. 10930 10931 Here are some more type related Modula-2 examples: 10932 10933 TYPE 10934 colour = (blue, red, yellow, green) ; 10935 t = [blue..yellow] ; 10936 VAR 10937 s: t ; 10938 BEGIN 10939 s := blue ; 10940 10941The GDB interaction shows how you can query the data type and value of 10942a variable. 10943 10944 (gdb) print s 10945 $1 = blue 10946 (gdb) ptype t 10947 type = [blue..yellow] 10948 10949In this example a Modula-2 array is declared and its contents 10950displayed. Observe that the contents are written in the same way as 10951their `C' counterparts. 10952 10953 VAR 10954 s: ARRAY [1..5] OF CARDINAL ; 10955 BEGIN 10956 s[1] := 1 ; 10957 10958 (gdb) print s 10959 $1 = {1, 0, 0, 0, 0} 10960 (gdb) ptype s 10961 type = ARRAY [1..5] OF CARDINAL 10962 10963 The Modula-2 language interface to GDB also understands pointer 10964types as shown in this example: 10965 10966 VAR 10967 s: POINTER TO ARRAY [1..5] OF CARDINAL ; 10968 BEGIN 10969 NEW(s) ; 10970 s^[1] := 1 ; 10971 10972and you can request that GDB describes the type of `s'. 10973 10974 (gdb) ptype s 10975 type = POINTER TO ARRAY [1..5] OF CARDINAL 10976 10977 GDB handles compound types as we can see in this example. Here we 10978combine array types, record types, pointer types and subrange types: 10979 10980 TYPE 10981 foo = RECORD 10982 f1: CARDINAL ; 10983 f2: CHAR ; 10984 f3: myarray ; 10985 END ; 10986 10987 myarray = ARRAY myrange OF CARDINAL ; 10988 myrange = [-2..2] ; 10989 VAR 10990 s: POINTER TO ARRAY myrange OF foo ; 10991 10992and you can ask GDB to describe the type of `s' as shown below. 10993 10994 (gdb) ptype s 10995 type = POINTER TO ARRAY [-2..2] OF foo = RECORD 10996 f1 : CARDINAL; 10997 f2 : CHAR; 10998 f3 : ARRAY [-2..2] OF CARDINAL; 10999 END 11000 11001 11002File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 11003 1100415.4.6.5 Modula-2 Defaults 11005.......................... 11006 11007If type and range checking are set automatically by GDB, they both 11008default to `on' whenever the working language changes to Modula-2. 11009This happens regardless of whether you or GDB selected the working 11010language. 11011 11012 If you allow GDB to set the language automatically, then entering 11013code compiled from a file whose name ends with `.mod' sets the working 11014language to Modula-2. *Note Having GDB Infer the Source Language: 11015Automatically, for further details. 11016 11017 11018File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 11019 1102015.4.6.6 Deviations from Standard Modula-2 11021.......................................... 11022 11023A few changes have been made to make Modula-2 programs easier to debug. 11024This is done primarily via loosening its type strictness: 11025 11026 * Unlike in standard Modula-2, pointer constants can be formed by 11027 integers. This allows you to modify pointer variables during 11028 debugging. (In standard Modula-2, the actual address contained in 11029 a pointer variable is hidden from you; it can only be modified 11030 through direct assignment to another pointer variable or 11031 expression that returned a pointer.) 11032 11033 * C escape sequences can be used in strings and characters to 11034 represent non-printable characters. GDB prints out strings with 11035 these escape sequences embedded. Single non-printable characters 11036 are printed using the `CHR(NNN)' format. 11037 11038 * The assignment operator (`:=') returns the value of its right-hand 11039 argument. 11040 11041 * All built-in procedures both modify _and_ return their argument. 11042 11043 11044File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 11045 1104615.4.6.7 Modula-2 Type and Range Checks 11047....................................... 11048 11049 _Warning:_ in this release, GDB does not yet perform type or range 11050 checking. 11051 11052 GDB considers two Modula-2 variables type equivalent if: 11053 11054 * They are of types that have been declared equivalent via a `TYPE 11055 T1 = T2' statement 11056 11057 * They have been declared on the same line. (Note: This is true of 11058 the GNU Modula-2 compiler, but it may not be true of other 11059 compilers.) 11060 11061 As long as type checking is enabled, any attempt to combine variables 11062whose types are not equivalent is an error. 11063 11064 Range checking is done on all mathematical operations, assignment, 11065array index bounds, and all built-in functions and procedures. 11066 11067 11068File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 11069 1107015.4.6.8 The Scope Operators `::' and `.' 11071......................................... 11072 11073There are a few subtle differences between the Modula-2 scope operator 11074(`.') and the GDB scope operator (`::'). The two have similar syntax: 11075 11076 11077 MODULE . ID 11078 SCOPE :: ID 11079 11080where SCOPE is the name of a module or a procedure, MODULE the name of 11081a module, and ID is any declared identifier within your program, except 11082another module. 11083 11084 Using the `::' operator makes GDB search the scope specified by 11085SCOPE for the identifier ID. If it is not found in the specified 11086scope, then GDB searches all scopes enclosing the one specified by 11087SCOPE. 11088 11089 Using the `.' operator makes GDB search the current scope for the 11090identifier specified by ID that was imported from the definition module 11091specified by MODULE. With this operator, it is an error if the 11092identifier ID was not imported from definition module MODULE, or if ID 11093is not an identifier in MODULE. 11094 11095 11096File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 11097 1109815.4.6.9 GDB and Modula-2 11099......................... 11100 11101Some GDB commands have little use when debugging Modula-2 programs. 11102Five subcommands of `set print' and `show print' apply specifically to 11103C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'. 11104The first four apply to C++, and the last to the C `union' type, which 11105has no direct analogue in Modula-2. 11106 11107 The `@' operator (*note Expressions: Expressions.), while available 11108with any language, is not useful with Modula-2. Its intent is to aid 11109the debugging of "dynamic arrays", which cannot be created in Modula-2 11110as they can in C or C++. However, because an address can be specified 11111by an integral constant, the construct `{TYPE}ADREXP' is still useful. 11112 11113 In GDB scripts, the Modula-2 inequality operator `#' is interpreted 11114as the beginning of a comment. Use `<>' instead. 11115 11116 11117File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages 11118 1111915.4.7 Ada 11120---------- 11121 11122The extensions made to GDB for Ada only support output from the GNU Ada 11123(GNAT) compiler. Other Ada compilers are not currently supported, and 11124attempting to debug executables produced by them is most likely to be 11125difficult. 11126 11127* Menu: 11128 11129* Ada Mode Intro:: General remarks on the Ada syntax 11130 and semantics supported by Ada mode 11131 in GDB. 11132* Omissions from Ada:: Restrictions on the Ada expression syntax. 11133* Additions to Ada:: Extensions of the Ada expression syntax. 11134* Stopping Before Main Program:: Debugging the program during elaboration. 11135* Ada Tasks:: Listing and setting breakpoints in tasks. 11136* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files 11137* Ada Glitches:: Known peculiarities of Ada mode. 11138 11139 11140File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada 11141 1114215.4.7.1 Introduction 11143..................... 11144 11145The Ada mode of GDB supports a fairly large subset of Ada expression 11146syntax, with some extensions. The philosophy behind the design of this 11147subset is 11148 11149 * That GDB should provide basic literals and access to operations for 11150 arithmetic, dereferencing, field selection, indexing, and 11151 subprogram calls, leaving more sophisticated computations to 11152 subprograms written into the program (which therefore may be 11153 called from GDB). 11154 11155 * That type safety and strict adherence to Ada language restrictions 11156 are not particularly important to the GDB user. 11157 11158 * That brevity is important to the GDB user. 11159 11160 Thus, for brevity, the debugger acts as if all names declared in 11161user-written packages are directly visible, even if they are not visible 11162according to Ada rules, thus making it unnecessary to fully qualify most 11163names with their packages, regardless of context. Where this causes 11164ambiguity, GDB asks the user's intent. 11165 11166 The debugger will start in Ada mode if it detects an Ada main 11167program. As for other languages, it will enter Ada mode when stopped 11168in a program that was translated from an Ada source file. 11169 11170 While in Ada mode, you may use `-' for comments. This is useful 11171mostly for documenting command files. The standard GDB comment (`#') 11172still works at the beginning of a line in Ada mode, but not in the 11173middle (to allow based literals). 11174 11175 The debugger supports limited overloading. Given a subprogram call 11176in which the function symbol has multiple definitions, it will use the 11177number of actual parameters and some information about their types to 11178attempt to narrow the set of definitions. It also makes very limited 11179use of context, preferring procedures to functions in the context of 11180the `call' command, and functions to procedures elsewhere. 11181 11182 11183File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada 11184 1118515.4.7.2 Omissions from Ada 11186........................... 11187 11188Here are the notable omissions from the subset: 11189 11190 * Only a subset of the attributes are supported: 11191 11192 - 'First, 'Last, and 'Length on array objects (not on types 11193 and subtypes). 11194 11195 - 'Min and 'Max. 11196 11197 - 'Pos and 'Val. 11198 11199 - 'Tag. 11200 11201 - 'Range on array objects (not subtypes), but only as the right 11202 operand of the membership (`in') operator. 11203 11204 - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT 11205 extension). 11206 11207 - 'Address. 11208 11209 * The names in `Characters.Latin_1' are not available and 11210 concatenation is not implemented. Thus, escape characters in 11211 strings are not currently available. 11212 11213 * Equality tests (`=' and `/=') on arrays test for bitwise equality 11214 of representations. They will generally work correctly for 11215 strings and arrays whose elements have integer or enumeration 11216 types. They may not work correctly for arrays whose element types 11217 have user-defined equality, for arrays of real values (in 11218 particular, IEEE-conformant floating point, because of negative 11219 zeroes and NaNs), and for arrays whose elements contain unused 11220 bits with indeterminate values. 11221 11222 * The other component-by-component array operations (`and', `or', 11223 `xor', `not', and relational tests other than equality) are not 11224 implemented. 11225 11226 * There is limited support for array and record aggregates. They are 11227 permitted only on the right sides of assignments, as in these 11228 examples: 11229 11230 (gdb) set An_Array := (1, 2, 3, 4, 5, 6) 11231 (gdb) set An_Array := (1, others => 0) 11232 (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) 11233 (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) 11234 (gdb) set A_Record := (1, "Peter", True); 11235 (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True) 11236 11237 Changing a discriminant's value by assigning an aggregate has an 11238 undefined effect if that discriminant is used within the record. 11239 However, you can first modify discriminants by directly assigning 11240 to them (which normally would not be allowed in Ada), and then 11241 performing an aggregate assignment. For example, given a variable 11242 `A_Rec' declared to have a type such as: 11243 11244 type Rec (Len : Small_Integer := 0) is record 11245 Id : Integer; 11246 Vals : IntArray (1 .. Len); 11247 end record; 11248 11249 you can assign a value with a different size of `Vals' with two 11250 assignments: 11251 11252 (gdb) set A_Rec.Len := 4 11253 (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) 11254 11255 As this example also illustrates, GDB is very loose about the usual 11256 rules concerning aggregates. You may leave out some of the 11257 components of an array or record aggregate (such as the `Len' 11258 component in the assignment to `A_Rec' above); they will retain 11259 their original values upon assignment. You may freely use dynamic 11260 values as indices in component associations. You may even use 11261 overlapping or redundant component associations, although which 11262 component values are assigned in such cases is not defined. 11263 11264 * Calls to dispatching subprograms are not implemented. 11265 11266 * The overloading algorithm is much more limited (i.e., less 11267 selective) than that of real Ada. It makes only limited use of 11268 the context in which a subexpression appears to resolve its 11269 meaning, and it is much looser in its rules for allowing type 11270 matches. As a result, some function calls will be ambiguous, and 11271 the user will be asked to choose the proper resolution. 11272 11273 * The `new' operator is not implemented. 11274 11275 * Entry calls are not implemented. 11276 11277 * Aside from printing, arithmetic operations on the native VAX 11278 floating-point formats are not supported. 11279 11280 * It is not possible to slice a packed array. 11281 11282 * The names `True' and `False', when not part of a qualified name, 11283 are interpreted as if implicitly prefixed by `Standard', 11284 regardless of context. Should your program redefine these names 11285 in a package or procedure (at best a dubious practice), you will 11286 have to use fully qualified names to access their new definitions. 11287 11288 11289File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada 11290 1129115.4.7.3 Additions to Ada 11292......................... 11293 11294As it does for other languages, GDB makes certain generic extensions to 11295Ada (*note Expressions::): 11296 11297 * If the expression E is a variable residing in memory (typically a 11298 local variable or array element) and N is a positive integer, then 11299 `E@N' displays the values of E and the N-1 adjacent variables 11300 following it in memory as an array. In Ada, this operator is 11301 generally not necessary, since its prime use is in displaying 11302 parts of an array, and slicing will usually do this in Ada. 11303 However, there are occasional uses when debugging programs in 11304 which certain debugging information has been optimized away. 11305 11306 * `B::VAR' means "the variable named VAR that appears in function or 11307 file B." When B is a file name, you must typically surround it in 11308 single quotes. 11309 11310 * The expression `{TYPE} ADDR' means "the variable of type TYPE that 11311 appears at address ADDR." 11312 11313 * A name starting with `$' is a convenience variable (*note 11314 Convenience Vars::) or a machine register (*note Registers::). 11315 11316 In addition, GDB provides a few other shortcuts and outright 11317additions specific to Ada: 11318 11319 * The assignment statement is allowed as an expression, returning 11320 its right-hand operand as its value. Thus, you may enter 11321 11322 (gdb) set x := y + 3 11323 (gdb) print A(tmp := y + 1) 11324 11325 * The semicolon is allowed as an "operator," returning as its value 11326 the value of its right-hand operand. This allows, for example, 11327 complex conditional breaks: 11328 11329 (gdb) break f 11330 (gdb) condition 1 (report(i); k += 1; A(k) > 100) 11331 11332 * Rather than use catenation and symbolic character names to 11333 introduce special characters into strings, one may instead use a 11334 special bracket notation, which is also used to print strings. A 11335 sequence of characters of the form `["XX"]' within a string or 11336 character literal denotes the (single) character whose numeric 11337 encoding is XX in hexadecimal. The sequence of characters `["""]' 11338 also denotes a single quotation mark in strings. For example, 11339 "One line.["0a"]Next line.["0a"]" 11340 contains an ASCII newline character (`Ada.Characters.Latin_1.LF') 11341 after each period. 11342 11343 * The subtype used as a prefix for the attributes 'Pos, 'Min, and 11344 'Max is optional (and is ignored in any case). For example, it is 11345 valid to write 11346 11347 (gdb) print 'max(x, y) 11348 11349 * When printing arrays, GDB uses positional notation when the array 11350 has a lower bound of 1, and uses a modified named notation 11351 otherwise. For example, a one-dimensional array of three integers 11352 with a lower bound of 3 might print as 11353 11354 (3 => 10, 17, 1) 11355 11356 That is, in contrast to valid Ada, only the first component has a 11357 `=>' clause. 11358 11359 * You may abbreviate attributes in expressions with any unique, 11360 multi-character subsequence of their names (an exact match gets 11361 preference). For example, you may use a'len, a'gth, or a'lh in 11362 place of a'length. 11363 11364 * Since Ada is case-insensitive, the debugger normally maps 11365 identifiers you type to lower case. The GNAT compiler uses 11366 upper-case characters for some of its internal identifiers, which 11367 are normally of no interest to users. For the rare occasions when 11368 you actually have to look at them, enclose them in angle brackets 11369 to avoid the lower-case mapping. For example, 11370 (gdb) print <JMPBUF_SAVE>[0] 11371 11372 * Printing an object of class-wide type or dereferencing an 11373 access-to-class-wide value will display all the components of the 11374 object's specific type (as indicated by its run-time tag). 11375 Likewise, component selection on such a value will operate on the 11376 specific type of the object. 11377 11378 11379 11380File: gdb.info, Node: Stopping Before Main Program, Next: Ada Tasks, Prev: Additions to Ada, Up: Ada 11381 1138215.4.7.4 Stopping at the Very Beginning 11383....................................... 11384 11385It is sometimes necessary to debug the program during elaboration, and 11386before reaching the main procedure. As defined in the Ada Reference 11387Manual, the elaboration code is invoked from a procedure called 11388`adainit'. To run your program up to the beginning of elaboration, 11389simply use the following two commands: `tbreak adainit' and `run'. 11390 11391 11392File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Stopping Before Main Program, Up: Ada 11393 1139415.4.7.5 Extensions for Ada Tasks 11395................................. 11396 11397Support for Ada tasks is analogous to that for threads (*note 11398Threads::). GDB provides the following task-related commands: 11399 11400`info tasks' 11401 This command shows a list of current Ada tasks, as in the 11402 following example: 11403 11404 (gdb) info tasks 11405 ID TID P-ID Pri State Name 11406 1 8088000 0 15 Child Activation Wait main_task 11407 2 80a4000 1 15 Accept Statement b 11408 3 809a800 1 15 Child Activation Wait a 11409 * 4 80ae800 3 15 Runnable c 11410 11411 In this listing, the asterisk before the last task indicates it to 11412 be the task currently being inspected. 11413 11414 ID 11415 Represents GDB's internal task number. 11416 11417 TID 11418 The Ada task ID. 11419 11420 P-ID 11421 The parent's task ID (GDB's internal task number). 11422 11423 Pri 11424 The base priority of the task. 11425 11426 State 11427 Current state of the task. 11428 11429 `Unactivated' 11430 The task has been created but has not been activated. 11431 It cannot be executing. 11432 11433 `Runnable' 11434 The task is not blocked for any reason known to Ada. 11435 (It may be waiting for a mutex, though.) It is 11436 conceptually "executing" in normal mode. 11437 11438 `Terminated' 11439 The task is terminated, in the sense of ARM 9.3 (5). 11440 Any dependents that were waiting on terminate 11441 alternatives have been awakened and have terminated 11442 themselves. 11443 11444 `Child Activation Wait' 11445 The task is waiting for created tasks to complete 11446 activation. 11447 11448 `Accept Statement' 11449 The task is waiting on an accept or selective wait 11450 statement. 11451 11452 `Waiting on entry call' 11453 The task is waiting on an entry call. 11454 11455 `Async Select Wait' 11456 The task is waiting to start the abortable part of an 11457 asynchronous select statement. 11458 11459 `Delay Sleep' 11460 The task is waiting on a select statement with only a 11461 delay alternative open. 11462 11463 `Child Termination Wait' 11464 The task is sleeping having completed a master within 11465 itself, and is waiting for the tasks dependent on that 11466 master to become terminated or waiting on a terminate 11467 Phase. 11468 11469 `Wait Child in Term Alt' 11470 The task is sleeping waiting for tasks on terminate 11471 alternatives to finish terminating. 11472 11473 `Accepting RV with TASKNO' 11474 The task is accepting a rendez-vous with the task TASKNO. 11475 11476 Name 11477 Name of the task in the program. 11478 11479 11480`info task TASKNO' 11481 This command shows detailled informations on the specified task, 11482 as in the following example: 11483 (gdb) info tasks 11484 ID TID P-ID Pri State Name 11485 1 8077880 0 15 Child Activation Wait main_task 11486 * 2 807c468 1 15 Runnable task_1 11487 (gdb) info task 2 11488 Ada Task: 0x807c468 11489 Name: task_1 11490 Thread: 0x807f378 11491 Parent: 1 (main_task) 11492 Base Priority: 15 11493 State: Runnable 11494 11495`task' 11496 This command prints the ID of the current task. 11497 11498 (gdb) info tasks 11499 ID TID P-ID Pri State Name 11500 1 8077870 0 15 Child Activation Wait main_task 11501 * 2 807c458 1 15 Runnable t 11502 (gdb) task 11503 [Current task is 2] 11504 11505`task TASKNO' 11506 This command is like the `thread THREADNO' command (*note 11507 Threads::). It switches the context of debugging from the current 11508 task to the given task. 11509 11510 (gdb) info tasks 11511 ID TID P-ID Pri State Name 11512 1 8077870 0 15 Child Activation Wait main_task 11513 * 2 807c458 1 15 Runnable t 11514 (gdb) task 1 11515 [Switching to task 1] 11516 #0 0x8067726 in pthread_cond_wait () 11517 (gdb) bt 11518 #0 0x8067726 in pthread_cond_wait () 11519 #1 0x8056714 in system.os_interface.pthread_cond_wait () 11520 #2 0x805cb63 in system.task_primitives.operations.sleep () 11521 #3 0x806153e in system.tasking.stages.activate_tasks () 11522 #4 0x804aacc in un () at un.adb:5 11523 11524`break LINESPEC task TASKNO' 11525`break LINESPEC task TASKNO if ...' 11526 These commands are like the `break ... thread ...' command (*note 11527 Thread Stops::). LINESPEC specifies source lines, as described in 11528 *note Specify Location::. 11529 11530 Use the qualifier `task TASKNO' with a breakpoint command to 11531 specify that you only want GDB to stop the program when a 11532 particular Ada task reaches this breakpoint. TASKNO is one of the 11533 numeric task identifiers assigned by GDB, shown in the first 11534 column of the `info tasks' display. 11535 11536 If you do not specify `task TASKNO' when you set a breakpoint, the 11537 breakpoint applies to _all_ tasks of your program. 11538 11539 You can use the `task' qualifier on conditional breakpoints as 11540 well; in this case, place `task TASKNO' before the breakpoint 11541 condition (before the `if'). 11542 11543 For example, 11544 11545 (gdb) info tasks 11546 ID TID P-ID Pri State Name 11547 1 140022020 0 15 Child Activation Wait main_task 11548 2 140045060 1 15 Accept/Select Wait t2 11549 3 140044840 1 15 Runnable t1 11550 * 4 140056040 1 15 Runnable t3 11551 (gdb) b 15 task 2 11552 Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. 11553 (gdb) cont 11554 Continuing. 11555 task # 1 running 11556 task # 2 running 11557 11558 Breakpoint 5, test_task_debug () at test_task_debug.adb:15 11559 15 flush; 11560 (gdb) info tasks 11561 ID TID P-ID Pri State Name 11562 1 140022020 0 15 Child Activation Wait main_task 11563 * 2 140045060 1 15 Runnable t2 11564 3 140044840 1 15 Runnable t1 11565 4 140056040 1 15 Delay Sleep t3 11566 11567 11568File: gdb.info, Node: Ada Tasks and Core Files, Next: Ada Glitches, Prev: Ada Tasks, Up: Ada 11569 1157015.4.7.6 Tasking Support when Debugging Core Files 11571.................................................. 11572 11573When inspecting a core file, as opposed to debugging a live program, 11574tasking support may be limited or even unavailable, depending on the 11575platform being used. For instance, on x86-linux, the list of tasks is 11576available, but task switching is not supported. On Tru64, however, 11577task switching will work as usual. 11578 11579 On certain platforms, including Tru64, the debugger needs to perform 11580some memory writes in order to provide Ada tasking support. When 11581inspecting a core file, this means that the core file must be opened 11582with read-write privileges, using the command `"set write on"' (*note 11583Patching::). Under these circumstances, you should make a backup copy 11584of the core file before inspecting it with GDB. 11585 11586 11587File: gdb.info, Node: Ada Glitches, Prev: Ada Tasks and Core Files, Up: Ada 11588 1158915.4.7.7 Known Peculiarities of Ada Mode 11590........................................ 11591 11592Besides the omissions listed previously (*note Omissions from Ada::), 11593we know of several problems with and limitations of Ada mode in GDB, 11594some of which will be fixed with planned future releases of the debugger 11595and the GNU Ada compiler. 11596 11597 * Currently, the debugger has insufficient information to determine 11598 whether certain pointers represent pointers to objects or the 11599 objects themselves. Thus, the user may have to tack an extra 11600 `.all' after an expression to get it printed properly. 11601 11602 * Static constants that the compiler chooses not to materialize as 11603 objects in storage are invisible to the debugger. 11604 11605 * Named parameter associations in function argument lists are 11606 ignored (the argument lists are treated as positional). 11607 11608 * Many useful library packages are currently invisible to the 11609 debugger. 11610 11611 * Fixed-point arithmetic, conversions, input, and output is carried 11612 out using floating-point arithmetic, and may give results that 11613 only approximate those on the host machine. 11614 11615 * The GNAT compiler never generates the prefix `Standard' for any of 11616 the standard symbols defined by the Ada language. GDB knows about 11617 this: it will strip the prefix from names when you use it, and 11618 will never look for a name you have so qualified among local 11619 symbols, nor match against symbols in other packages or 11620 subprograms. If you have defined entities anywhere in your 11621 program other than parameters and local variables whose simple 11622 names match names in `Standard', GNAT's lack of qualification here 11623 can cause confusion. When this happens, you can usually resolve 11624 the confusion by qualifying the problematic names with package 11625 `Standard' explicitly. 11626 11627 Older versions of the compiler sometimes generate erroneous debugging 11628information, resulting in the debugger incorrectly printing the value 11629of affected entities. In some cases, the debugger is able to work 11630around an issue automatically. In other cases, the debugger is able to 11631work around the issue, but the work-around has to be specifically 11632enabled. 11633 11634`set ada trust-PAD-over-XVS on' 11635 Configure GDB to strictly follow the GNAT encoding when computing 11636 the value of Ada entities, particularly when `PAD' and `PAD___XVS' 11637 types are involved (see `ada/exp_dbug.ads' in the GCC sources for 11638 a complete description of the encoding used by the GNAT compiler). 11639 This is the default. 11640 11641`set ada trust-PAD-over-XVS off' 11642 This is related to the encoding using by the GNAT compiler. If 11643 GDB sometimes prints the wrong value for certain entities, 11644 changing `ada trust-PAD-over-XVS' to `off' activates a work-around 11645 which may fix the issue. It is always safe to set `ada 11646 trust-PAD-over-XVS' to `off', but this incurs a slight performance 11647 penalty, so it is recommended to leave this setting to `on' unless 11648 necessary. 11649 11650 11651 11652File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages 11653 1165415.5 Unsupported Languages 11655========================== 11656 11657In addition to the other fully-supported programming languages, GDB 11658also provides a pseudo-language, called `minimal'. It does not 11659represent a real programming language, but provides a set of 11660capabilities close to what the C or assembly languages provide. This 11661should allow most simple operations to be performed while debugging an 11662application that uses a language currently not supported by GDB. 11663 11664 If the language is set to `auto', GDB will automatically select this 11665language if the current frame corresponds to an unsupported language. 11666 11667 11668File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top 11669 1167016 Examining the Symbol Table 11671***************************** 11672 11673The commands described in this chapter allow you to inquire about the 11674symbols (names of variables, functions and types) defined in your 11675program. This information is inherent in the text of your program and 11676does not change as your program executes. GDB finds it in your 11677program's symbol table, in the file indicated when you started GDB 11678(*note Choosing Files: File Options.), or by one of the file-management 11679commands (*note Commands to Specify Files: Files.). 11680 11681 Occasionally, you may need to refer to symbols that contain unusual 11682characters, which GDB ordinarily treats as word delimiters. The most 11683frequent case is in referring to static variables in other source files 11684(*note Program Variables: Variables.). File names are recorded in 11685object files as debugging symbols, but GDB would ordinarily parse a 11686typical file name, like `foo.c', as the three words `foo' `.' `c'. To 11687allow GDB to recognize `foo.c' as a single symbol, enclose it in single 11688quotes; for example, 11689 11690 p 'foo.c'::x 11691 11692looks up the value of `x' in the scope of the file `foo.c'. 11693 11694`set case-sensitive on' 11695`set case-sensitive off' 11696`set case-sensitive auto' 11697 Normally, when GDB looks up symbols, it matches their names with 11698 case sensitivity determined by the current source language. 11699 Occasionally, you may wish to control that. The command `set 11700 case-sensitive' lets you do that by specifying `on' for 11701 case-sensitive matches or `off' for case-insensitive ones. If you 11702 specify `auto', case sensitivity is reset to the default suitable 11703 for the source language. The default is case-sensitive matches 11704 for all languages except for Fortran, for which the default is 11705 case-insensitive matches. 11706 11707`show case-sensitive' 11708 This command shows the current setting of case sensitivity for 11709 symbols lookups. 11710 11711`info address SYMBOL' 11712 Describe where the data for SYMBOL is stored. For a register 11713 variable, this says which register it is kept in. For a 11714 non-register local variable, this prints the stack-frame offset at 11715 which the variable is always stored. 11716 11717 Note the contrast with `print &SYMBOL', which does not work at all 11718 for a register variable, and for a stack local variable prints the 11719 exact address of the current instantiation of the variable. 11720 11721`info symbol ADDR' 11722 Print the name of a symbol which is stored at the address ADDR. 11723 If no symbol is stored exactly at ADDR, GDB prints the nearest 11724 symbol and an offset from it: 11725 11726 (gdb) info symbol 0x54320 11727 _initialize_vx + 396 in section .text 11728 11729 This is the opposite of the `info address' command. You can use 11730 it to find out the name of a variable or a function given its 11731 address. 11732 11733 For dynamically linked executables, the name of executable or 11734 shared library containing the symbol is also printed: 11735 11736 (gdb) info symbol 0x400225 11737 _start + 5 in section .text of /tmp/a.out 11738 (gdb) info symbol 0x2aaaac2811cf 11739 __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 11740 11741`whatis [ARG]' 11742 Print the data type of ARG, which can be either an expression or a 11743 data type. With no argument, print the data type of `$', the last 11744 value in the value history. If ARG is an expression, it is not 11745 actually evaluated, and any side-effecting operations (such as 11746 assignments or function calls) inside it do not take place. If 11747 ARG is a type name, it may be the name of a type or typedef, or 11748 for C code it may have the form `class CLASS-NAME', `struct 11749 STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'. *Note 11750 Expressions: Expressions. 11751 11752`ptype [ARG]' 11753 `ptype' accepts the same arguments as `whatis', but prints a 11754 detailed description of the type, instead of just the name of the 11755 type. *Note Expressions: Expressions. 11756 11757 For example, for this variable declaration: 11758 11759 struct complex {double real; double imag;} v; 11760 11761 the two commands give this output: 11762 11763 (gdb) whatis v 11764 type = struct complex 11765 (gdb) ptype v 11766 type = struct complex { 11767 double real; 11768 double imag; 11769 } 11770 11771 As with `whatis', using `ptype' without an argument refers to the 11772 type of `$', the last value in the value history. 11773 11774 Sometimes, programs use opaque data types or incomplete 11775 specifications of complex data structure. If the debug 11776 information included in the program does not allow GDB to display 11777 a full declaration of the data type, it will say `<incomplete 11778 type>'. For example, given these declarations: 11779 11780 struct foo; 11781 struct foo *fooptr; 11782 11783 but no definition for `struct foo' itself, GDB will say: 11784 11785 (gdb) ptype foo 11786 $1 = <incomplete type> 11787 11788 "Incomplete type" is C terminology for data types that are not 11789 completely specified. 11790 11791`info types REGEXP' 11792`info types' 11793 Print a brief description of all types whose names match the 11794 regular expression REGEXP (or all types in your program, if you 11795 supply no argument). Each complete typename is matched as though 11796 it were a complete line; thus, `i type value' gives information on 11797 all types in your program whose names include the string `value', 11798 but `i type ^value$' gives information only on types whose complete 11799 name is `value'. 11800 11801 This command differs from `ptype' in two ways: first, like 11802 `whatis', it does not print a detailed description; second, it 11803 lists all source files where a type is defined. 11804 11805`info scope LOCATION' 11806 List all the variables local to a particular scope. This command 11807 accepts a LOCATION argument--a function name, a source line, or an 11808 address preceded by a `*', and prints all the variables local to 11809 the scope defined by that location. (*Note Specify Location::, for 11810 details about supported forms of LOCATION.) For example: 11811 11812 (gdb) info scope command_line_handler 11813 Scope for command_line_handler: 11814 Symbol rl is an argument at stack/frame offset 8, length 4. 11815 Symbol linebuffer is in static storage at address 0x150a18, length 4. 11816 Symbol linelength is in static storage at address 0x150a1c, length 4. 11817 Symbol p is a local variable in register $esi, length 4. 11818 Symbol p1 is a local variable in register $ebx, length 4. 11819 Symbol nline is a local variable in register $edx, length 4. 11820 Symbol repeat is a local variable at frame offset -8, length 4. 11821 11822 This command is especially useful for determining what data to 11823 collect during a "trace experiment", see *note collect: Tracepoint 11824 Actions. 11825 11826`info source' 11827 Show information about the current source file--that is, the 11828 source file for the function containing the current point of 11829 execution: 11830 * the name of the source file, and the directory containing it, 11831 11832 * the directory it was compiled in, 11833 11834 * its length, in lines, 11835 11836 * which programming language it is written in, 11837 11838 * whether the executable includes debugging information for 11839 that file, and if so, what format the information is in 11840 (e.g., STABS, Dwarf 2, etc.), and 11841 11842 * whether the debugging information includes information about 11843 preprocessor macros. 11844 11845`info sources' 11846 Print the names of all source files in your program for which 11847 there is debugging information, organized into two lists: files 11848 whose symbols have already been read, and files whose symbols will 11849 be read when needed. 11850 11851`info functions' 11852 Print the names and data types of all defined functions. 11853 11854`info functions REGEXP' 11855 Print the names and data types of all defined functions whose 11856 names contain a match for regular expression REGEXP. Thus, `info 11857 fun step' finds all functions whose names include `step'; `info 11858 fun ^step' finds those whose names start with `step'. If a 11859 function name contains characters that conflict with the regular 11860 expression language (e.g. `operator*()'), they may be quoted with 11861 a backslash. 11862 11863`info variables' 11864 Print the names and data types of all variables that are defined 11865 outside of functions (i.e. excluding local variables). 11866 11867`info variables REGEXP' 11868 Print the names and data types of all variables (except for local 11869 variables) whose names contain a match for regular expression 11870 REGEXP. 11871 11872`info classes' 11873`info classes REGEXP' 11874 Display all Objective-C classes in your program, or (with the 11875 REGEXP argument) all those matching a particular regular 11876 expression. 11877 11878`info selectors' 11879`info selectors REGEXP' 11880 Display all Objective-C selectors in your program, or (with the 11881 REGEXP argument) all those matching a particular regular 11882 expression. 11883 11884 Some systems allow individual object files that make up your 11885 program to be replaced without stopping and restarting your 11886 program. For example, in VxWorks you can simply recompile a 11887 defective object file and keep on running. If you are running on 11888 one of these systems, you can allow GDB to reload the symbols for 11889 automatically relinked modules: 11890 11891 `set symbol-reloading on' 11892 Replace symbol definitions for the corresponding source file 11893 when an object file with a particular name is seen again. 11894 11895 `set symbol-reloading off' 11896 Do not replace symbol definitions when encountering object 11897 files of the same name more than once. This is the default 11898 state; if you are not running on a system that permits 11899 automatic relinking of modules, you should leave 11900 `symbol-reloading' off, since otherwise GDB may discard 11901 symbols when linking large programs, that may contain several 11902 modules (from different directories or libraries) with the 11903 same name. 11904 11905 `show symbol-reloading' 11906 Show the current `on' or `off' setting. 11907 11908`set opaque-type-resolution on' 11909 Tell GDB to resolve opaque types. An opaque type is a type 11910 declared as a pointer to a `struct', `class', or `union'--for 11911 example, `struct MyType *'--that is used in one source file 11912 although the full declaration of `struct MyType' is in another 11913 source file. The default is on. 11914 11915 A change in the setting of this subcommand will not take effect 11916 until the next time symbols for a file are loaded. 11917 11918`set opaque-type-resolution off' 11919 Tell GDB not to resolve opaque types. In this case, the type is 11920 printed as follows: 11921 {<no data fields>} 11922 11923`show opaque-type-resolution' 11924 Show whether opaque types are resolved or not. 11925 11926`maint print symbols FILENAME' 11927`maint print psymbols FILENAME' 11928`maint print msymbols FILENAME' 11929 Write a dump of debugging symbol data into the file FILENAME. 11930 These commands are used to debug the GDB symbol-reading code. Only 11931 symbols with debugging data are included. If you use `maint print 11932 symbols', GDB includes all the symbols for which it has already 11933 collected full details: that is, FILENAME reflects symbols for 11934 only those files whose symbols GDB has read. You can use the 11935 command `info sources' to find out which files these are. If you 11936 use `maint print psymbols' instead, the dump shows information 11937 about symbols that GDB only knows partially--that is, symbols 11938 defined in files that GDB has skimmed, but not yet read 11939 completely. Finally, `maint print msymbols' dumps just the 11940 minimal symbol information required for each object file from 11941 which GDB has read some symbols. *Note Commands to Specify Files: 11942 Files, for a discussion of how GDB reads symbols (in the 11943 description of `symbol-file'). 11944 11945`maint info symtabs [ REGEXP ]' 11946`maint info psymtabs [ REGEXP ]' 11947 List the `struct symtab' or `struct partial_symtab' structures 11948 whose names match REGEXP. If REGEXP is not given, list them all. 11949 The output includes expressions which you can copy into a GDB 11950 debugging this one to examine a particular structure in more 11951 detail. For example: 11952 11953 (gdb) maint info psymtabs dwarf2read 11954 { objfile /home/gnu/build/gdb/gdb 11955 ((struct objfile *) 0x82e69d0) 11956 { psymtab /home/gnu/src/gdb/dwarf2read.c 11957 ((struct partial_symtab *) 0x8474b10) 11958 readin no 11959 fullname (null) 11960 text addresses 0x814d3c8 -- 0x8158074 11961 globals (* (struct partial_symbol **) 0x8507a08 @ 9) 11962 statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) 11963 dependencies (none) 11964 } 11965 } 11966 (gdb) maint info symtabs 11967 (gdb) 11968 We see that there is one partial symbol table whose filename 11969 contains the string `dwarf2read', belonging to the `gdb' 11970 executable; and we see that GDB has not read in any symtabs yet at 11971 all. If we set a breakpoint on a function, that will cause GDB to 11972 read the symtab for the compilation unit containing that function: 11973 11974 (gdb) break dwarf2_psymtab_to_symtab 11975 Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, 11976 line 1574. 11977 (gdb) maint info symtabs 11978 { objfile /home/gnu/build/gdb/gdb 11979 ((struct objfile *) 0x82e69d0) 11980 { symtab /home/gnu/src/gdb/dwarf2read.c 11981 ((struct symtab *) 0x86c1f38) 11982 dirname (null) 11983 fullname (null) 11984 blockvector ((struct blockvector *) 0x86c1bd0) (primary) 11985 linetable ((struct linetable *) 0x8370fa0) 11986 debugformat DWARF 2 11987 } 11988 } 11989 (gdb) 11990 11991 11992File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top 11993 1199417 Altering Execution 11995********************* 11996 11997Once you think you have found an error in your program, you might want 11998to find out for certain whether correcting the apparent error would 11999lead to correct results in the rest of the run. You can find the 12000answer by experiment, using the GDB features for altering execution of 12001the program. 12002 12003 For example, you can store new values into variables or memory 12004locations, give your program a signal, restart it at a different 12005address, or even return prematurely from a function. 12006 12007* Menu: 12008 12009* Assignment:: Assignment to variables 12010* Jumping:: Continuing at a different address 12011* Signaling:: Giving your program a signal 12012* Returning:: Returning from a function 12013* Calling:: Calling your program's functions 12014* Patching:: Patching your program 12015 12016 12017File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering 12018 1201917.1 Assignment to Variables 12020============================ 12021 12022To alter the value of a variable, evaluate an assignment expression. 12023*Note Expressions: Expressions. For example, 12024 12025 print x=4 12026 12027stores the value 4 into the variable `x', and then prints the value of 12028the assignment expression (which is 4). *Note Using GDB with Different 12029Languages: Languages, for more information on operators in supported 12030languages. 12031 12032 If you are not interested in seeing the value of the assignment, use 12033the `set' command instead of the `print' command. `set' is really the 12034same as `print' except that the expression's value is not printed and 12035is not put in the value history (*note Value History: Value History.). 12036The expression is evaluated only for its effects. 12037 12038 If the beginning of the argument string of the `set' command appears 12039identical to a `set' subcommand, use the `set variable' command instead 12040of just `set'. This command is identical to `set' except for its lack 12041of subcommands. For example, if your program has a variable `width', 12042you get an error if you try to set a new value with just `set 12043width=13', because GDB has the command `set width': 12044 12045 (gdb) whatis width 12046 type = double 12047 (gdb) p width 12048 $4 = 13 12049 (gdb) set width=47 12050 Invalid syntax in expression. 12051 12052The invalid expression, of course, is `=47'. In order to actually set 12053the program's variable `width', use 12054 12055 (gdb) set var width=47 12056 12057 Because the `set' command has many subcommands that can conflict 12058with the names of program variables, it is a good idea to use the `set 12059variable' command instead of just `set'. For example, if your program 12060has a variable `g', you run into problems if you try to set a new value 12061with just `set g=4', because GDB has the command `set gnutarget', 12062abbreviated `set g': 12063 12064 (gdb) whatis g 12065 type = double 12066 (gdb) p g 12067 $1 = 1 12068 (gdb) set g=4 12069 (gdb) p g 12070 $2 = 1 12071 (gdb) r 12072 The program being debugged has been started already. 12073 Start it from the beginning? (y or n) y 12074 Starting program: /home/smith/cc_progs/a.out 12075 "/home/smith/cc_progs/a.out": can't open to read symbols: 12076 Invalid bfd target. 12077 (gdb) show g 12078 The current BFD target is "=4". 12079 12080The program variable `g' did not change, and you silently set the 12081`gnutarget' to an invalid value. In order to set the variable `g', use 12082 12083 (gdb) set var g=4 12084 12085 GDB allows more implicit conversions in assignments than C; you can 12086freely store an integer value into a pointer variable or vice versa, 12087and you can convert any structure to any other structure that is the 12088same length or shorter. 12089 12090 To store values into arbitrary places in memory, use the `{...}' 12091construct to generate a value of specified type at a specified address 12092(*note Expressions: Expressions.). For example, `{int}0x83040' refers 12093to memory location `0x83040' as an integer (which implies a certain size 12094and representation in memory), and 12095 12096 set {int}0x83040 = 4 12097 12098stores the value 4 into that memory location. 12099 12100 12101File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering 12102 1210317.2 Continuing at a Different Address 12104====================================== 12105 12106Ordinarily, when you continue your program, you do so at the place where 12107it stopped, with the `continue' command. You can instead continue at 12108an address of your own choosing, with the following commands: 12109 12110`jump LINESPEC' 12111`jump LOCATION' 12112 Resume execution at line LINESPEC or at address given by LOCATION. 12113 Execution stops again immediately if there is a breakpoint there. 12114 *Note Specify Location::, for a description of the different forms 12115 of LINESPEC and LOCATION. It is common practice to use the 12116 `tbreak' command in conjunction with `jump'. *Note Setting 12117 Breakpoints: Set Breaks. 12118 12119 The `jump' command does not change the current stack frame, or the 12120 stack pointer, or the contents of any memory location or any 12121 register other than the program counter. If line LINESPEC is in a 12122 different function from the one currently executing, the results 12123 may be bizarre if the two functions expect different patterns of 12124 arguments or of local variables. For this reason, the `jump' 12125 command requests confirmation if the specified line is not in the 12126 function currently executing. However, even bizarre results are 12127 predictable if you are well acquainted with the machine-language 12128 code of your program. 12129 12130 On many systems, you can get much the same effect as the `jump' 12131command by storing a new value into the register `$pc'. The difference 12132is that this does not start your program running; it only changes the 12133address of where it _will_ run when you continue. For example, 12134 12135 set $pc = 0x485 12136 12137makes the next `continue' command or stepping command execute at 12138address `0x485', rather than at the address where your program stopped. 12139*Note Continuing and Stepping: Continuing and Stepping. 12140 12141 The most common occasion to use the `jump' command is to back 12142up--perhaps with more breakpoints set--over a portion of a program that 12143has already executed, in order to examine its execution in more detail. 12144 12145 12146File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering 12147 1214817.3 Giving your Program a Signal 12149================================= 12150 12151`signal SIGNAL' 12152 Resume execution where your program stopped, but immediately give 12153 it the signal SIGNAL. SIGNAL can be the name or the number of a 12154 signal. For example, on many systems `signal 2' and `signal 12155 SIGINT' are both ways of sending an interrupt signal. 12156 12157 Alternatively, if SIGNAL is zero, continue execution without 12158 giving a signal. This is useful when your program stopped on 12159 account of a signal and would ordinary see the signal when resumed 12160 with the `continue' command; `signal 0' causes it to resume 12161 without a signal. 12162 12163 `signal' does not repeat when you press <RET> a second time after 12164 executing the command. 12165 12166 Invoking the `signal' command is not the same as invoking the `kill' 12167utility from the shell. Sending a signal with `kill' causes GDB to 12168decide what to do with the signal depending on the signal handling 12169tables (*note Signals::). The `signal' command passes the signal 12170directly to your program. 12171 12172 12173File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering 12174 1217517.4 Returning from a Function 12176============================== 12177 12178`return' 12179`return EXPRESSION' 12180 You can cancel execution of a function call with the `return' 12181 command. If you give an EXPRESSION argument, its value is used as 12182 the function's return value. 12183 12184 When you use `return', GDB discards the selected stack frame (and 12185all frames within it). You can think of this as making the discarded 12186frame return prematurely. If you wish to specify a value to be 12187returned, give that value as the argument to `return'. 12188 12189 This pops the selected stack frame (*note Selecting a Frame: 12190Selection.), and any other frames inside of it, leaving its caller as 12191the innermost remaining frame. That frame becomes selected. The 12192specified value is stored in the registers used for returning values of 12193functions. 12194 12195 The `return' command does not resume execution; it leaves the 12196program stopped in the state that would exist if the function had just 12197returned. In contrast, the `finish' command (*note Continuing and 12198Stepping: Continuing and Stepping.) resumes execution until the 12199selected stack frame returns naturally. 12200 12201 GDB needs to know how the EXPRESSION argument should be set for the 12202inferior. The concrete registers assignment depends on the OS ABI and 12203the type being returned by the selected stack frame. For example it is 12204common for OS ABI to return floating point values in FPU registers 12205while integer values in CPU registers. Still some ABIs return even 12206floating point values in CPU registers. Larger integer widths (such as 12207`long long int') also have specific placement rules. GDB already knows 12208the OS ABI from its current target so it needs to find out also the 12209type being returned to make the assignment into the right register(s). 12210 12211 Normally, the selected stack frame has debug info. GDB will always 12212use the debug info instead of the implicit type of EXPRESSION when the 12213debug info is available. For example, if you type `return -1', and the 12214function in the current stack frame is declared to return a `long long 12215int', GDB transparently converts the implicit `int' value of -1 into a 12216`long long int': 12217 12218 Breakpoint 1, func () at gdb.base/return-nodebug.c:29 12219 29 return 31; 12220 (gdb) return -1 12221 Make func return now? (y or n) y 12222 #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 12223 43 printf ("result=%lld\n", func ()); 12224 (gdb) 12225 12226 However, if the selected stack frame does not have a debug info, 12227e.g., if the function was compiled without debug info, GDB has to find 12228out the type to return from user. Specifying a different type by 12229mistake may set the value in different inferior registers than the 12230caller code expects. For example, typing `return -1' with its implicit 12231type `int' would set only a part of a `long long int' result for a 12232debug info less function (on 32-bit architectures). Therefore the user 12233is required to specify the return type by an appropriate cast 12234explicitly: 12235 12236 Breakpoint 2, 0x0040050b in func () 12237 (gdb) return -1 12238 Return value type not available for selected stack frame. 12239 Please use an explicit cast of the value to return. 12240 (gdb) return (long long int) -1 12241 Make selected stack frame return now? (y or n) y 12242 #0 0x00400526 in main () 12243 (gdb) 12244 12245 12246File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering 12247 1224817.5 Calling Program Functions 12249============================== 12250 12251`print EXPR' 12252 Evaluate the expression EXPR and display the resulting value. 12253 EXPR may include calls to functions in the program being debugged. 12254 12255`call EXPR' 12256 Evaluate the expression EXPR without displaying `void' returned 12257 values. 12258 12259 You can use this variant of the `print' command if you want to 12260 execute a function from your program that does not return anything 12261 (a.k.a. "a void function"), but without cluttering the output with 12262 `void' returned values that GDB will otherwise print. If the 12263 result is not void, it is printed and saved in the value history. 12264 12265 It is possible for the function you call via the `print' or `call' 12266command to generate a signal (e.g., if there's a bug in the function, 12267or if you passed it incorrect arguments). What happens in that case is 12268controlled by the `set unwindonsignal' command. 12269 12270 Similarly, with a C++ program it is possible for the function you 12271call via the `print' or `call' command to generate an exception that is 12272not handled due to the constraints of the dummy frame. In this case, 12273any exception that is raised in the frame, but has an out-of-frame 12274exception handler will not be found. GDB builds a dummy-frame for the 12275inferior function call, and the unwinder cannot seek for exception 12276handlers outside of this dummy-frame. What happens in that case is 12277controlled by the `set unwind-on-terminating-exception' command. 12278 12279`set unwindonsignal' 12280 Set unwinding of the stack if a signal is received while in a 12281 function that GDB called in the program being debugged. If set to 12282 on, GDB unwinds the stack it created for the call and restores the 12283 context to what it was before the call. If set to off (the 12284 default), GDB stops in the frame where the signal was received. 12285 12286`show unwindonsignal' 12287 Show the current setting of stack unwinding in the functions 12288 called by GDB. 12289 12290`set unwind-on-terminating-exception' 12291 Set unwinding of the stack if a C++ exception is raised, but left 12292 unhandled while in a function that GDB called in the program being 12293 debugged. If set to on (the default), GDB unwinds the stack it 12294 created for the call and restores the context to what it was before 12295 the call. If set to off, GDB the exception is delivered to the 12296 default C++ exception handler and the inferior terminated. 12297 12298`show unwind-on-terminating-exception' 12299 Show the current setting of stack unwinding in the functions 12300 called by GDB. 12301 12302 12303 Sometimes, a function you wish to call is actually a "weak alias" 12304for another function. In such case, GDB might not pick up the type 12305information, including the types of the function arguments, which 12306causes GDB to call the inferior function incorrectly. As a result, the 12307called function will function erroneously and may even crash. A 12308solution to that is to use the name of the aliased function instead. 12309 12310 12311File: gdb.info, Node: Patching, Prev: Calling, Up: Altering 12312 1231317.6 Patching Programs 12314====================== 12315 12316By default, GDB opens the file containing your program's executable 12317code (or the corefile) read-only. This prevents accidental alterations 12318to machine code; but it also prevents you from intentionally patching 12319your program's binary. 12320 12321 If you'd like to be able to patch the binary, you can specify that 12322explicitly with the `set write' command. For example, you might want 12323to turn on internal debugging flags, or even to make emergency repairs. 12324 12325`set write on' 12326`set write off' 12327 If you specify `set write on', GDB opens executable and core files 12328 for both reading and writing; if you specify `set write off' (the 12329 default), GDB opens them read-only. 12330 12331 If you have already loaded a file, you must load it again (using 12332 the `exec-file' or `core-file' command) after changing `set 12333 write', for your new setting to take effect. 12334 12335`show write' 12336 Display whether executable files and core files are opened for 12337 writing as well as reading. 12338 12339 12340File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top 12341 1234218 GDB Files 12343************ 12344 12345GDB needs to know the file name of the program to be debugged, both in 12346order to read its symbol table and in order to start your program. To 12347debug a core dump of a previous run, you must also tell GDB the name of 12348the core dump file. 12349 12350* Menu: 12351 12352* Files:: Commands to specify files 12353* Separate Debug Files:: Debugging information in separate files 12354* Index Files:: Index files speed up GDB 12355* Symbol Errors:: Errors reading symbol files 12356* Data Files:: GDB data files 12357 12358 12359File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files 12360 1236118.1 Commands to Specify Files 12362============================== 12363 12364You may want to specify executable and core dump file names. The usual 12365way to do this is at start-up time, using the arguments to GDB's 12366start-up commands (*note Getting In and Out of GDB: Invocation.). 12367 12368 Occasionally it is necessary to change to a different file during a 12369GDB session. Or you may run GDB and forget to specify a file you want 12370to use. Or you are debugging a remote target via `gdbserver' (*note 12371file: Server.). In these situations the GDB commands to specify new 12372files are useful. 12373 12374`file FILENAME' 12375 Use FILENAME as the program to be debugged. It is read for its 12376 symbols and for the contents of pure memory. It is also the 12377 program executed when you use the `run' command. If you do not 12378 specify a directory and the file is not found in the GDB working 12379 directory, GDB uses the environment variable `PATH' as a list of 12380 directories to search, just as the shell does when looking for a 12381 program to run. You can change the value of this variable, for 12382 both GDB and your program, using the `path' command. 12383 12384 You can load unlinked object `.o' files into GDB using the `file' 12385 command. You will not be able to "run" an object file, but you 12386 can disassemble functions and inspect variables. Also, if the 12387 underlying BFD functionality supports it, you could use `gdb 12388 -write' to patch object files using this technique. Note that GDB 12389 can neither interpret nor modify relocations in this case, so 12390 branches and some initialized variables will appear to go to the 12391 wrong place. But this feature is still handy from time to time. 12392 12393`file' 12394 `file' with no argument makes GDB discard any information it has 12395 on both executable file and the symbol table. 12396 12397`exec-file [ FILENAME ]' 12398 Specify that the program to be run (but not the symbol table) is 12399 found in FILENAME. GDB searches the environment variable `PATH' 12400 if necessary to locate your program. Omitting FILENAME means to 12401 discard information on the executable file. 12402 12403`symbol-file [ FILENAME ]' 12404 Read symbol table information from file FILENAME. `PATH' is 12405 searched when necessary. Use the `file' command to get both symbol 12406 table and program to run from the same file. 12407 12408 `symbol-file' with no argument clears out GDB information on your 12409 program's symbol table. 12410 12411 The `symbol-file' command causes GDB to forget the contents of 12412 some breakpoints and auto-display expressions. This is because 12413 they may contain pointers to the internal data recording symbols 12414 and data types, which are part of the old symbol table data being 12415 discarded inside GDB. 12416 12417 `symbol-file' does not repeat if you press <RET> again after 12418 executing it once. 12419 12420 When GDB is configured for a particular environment, it 12421 understands debugging information in whatever format is the 12422 standard generated for that environment; you may use either a GNU 12423 compiler, or other compilers that adhere to the local conventions. 12424 Best results are usually obtained from GNU compilers; for example, 12425 using `GCC' you can generate debugging information for optimized 12426 code. 12427 12428 For most kinds of object files, with the exception of old SVR3 12429 systems using COFF, the `symbol-file' command does not normally 12430 read the symbol table in full right away. Instead, it scans the 12431 symbol table quickly to find which source files and which symbols 12432 are present. The details are read later, one source file at a 12433 time, as they are needed. 12434 12435 The purpose of this two-stage reading strategy is to make GDB 12436 start up faster. For the most part, it is invisible except for 12437 occasional pauses while the symbol table details for a particular 12438 source file are being read. (The `set verbose' command can turn 12439 these pauses into messages if desired. *Note Optional Warnings 12440 and Messages: Messages/Warnings.) 12441 12442 We have not implemented the two-stage strategy for COFF yet. When 12443 the symbol table is stored in COFF format, `symbol-file' reads the 12444 symbol table data in full right away. Note that "stabs-in-COFF" 12445 still does the two-stage strategy, since the debug info is actually 12446 in stabs format. 12447 12448`symbol-file [ -readnow ] FILENAME' 12449`file [ -readnow ] FILENAME' 12450 You can override the GDB two-stage strategy for reading symbol 12451 tables by using the `-readnow' option with any of the commands that 12452 load symbol table information, if you want to be sure GDB has the 12453 entire symbol table available. 12454 12455`core-file [FILENAME]' 12456`core' 12457 Specify the whereabouts of a core dump file to be used as the 12458 "contents of memory". Traditionally, core files contain only some 12459 parts of the address space of the process that generated them; GDB 12460 can access the executable file itself for other parts. 12461 12462 `core-file' with no argument specifies that no core file is to be 12463 used. 12464 12465 Note that the core file is ignored when your program is actually 12466 running under GDB. So, if you have been running your program and 12467 you wish to debug a core file instead, you must kill the 12468 subprocess in which the program is running. To do this, use the 12469 `kill' command (*note Killing the Child Process: Kill Process.). 12470 12471`add-symbol-file FILENAME ADDRESS' 12472`add-symbol-file FILENAME ADDRESS [ -readnow ]' 12473`add-symbol-file FILENAME -sSECTION ADDRESS ...' 12474 The `add-symbol-file' command reads additional symbol table 12475 information from the file FILENAME. You would use this command 12476 when FILENAME has been dynamically loaded (by some other means) 12477 into the program that is running. ADDRESS should be the memory 12478 address at which the file has been loaded; GDB cannot figure this 12479 out for itself. You can additionally specify an arbitrary number 12480 of `-sSECTION ADDRESS' pairs, to give an explicit section name and 12481 base address for that section. You can specify any ADDRESS as an 12482 expression. 12483 12484 The symbol table of the file FILENAME is added to the symbol table 12485 originally read with the `symbol-file' command. You can use the 12486 `add-symbol-file' command any number of times; the new symbol data 12487 thus read keeps adding to the old. To discard all old symbol data 12488 instead, use the `symbol-file' command without any arguments. 12489 12490 Although FILENAME is typically a shared library file, an 12491 executable file, or some other object file which has been fully 12492 relocated for loading into a process, you can also load symbolic 12493 information from relocatable `.o' files, as long as: 12494 12495 * the file's symbolic information refers only to linker symbols 12496 defined in that file, not to symbols defined by other object 12497 files, 12498 12499 * every section the file's symbolic information refers to has 12500 actually been loaded into the inferior, as it appears in the 12501 file, and 12502 12503 * you can determine the address at which every section was 12504 loaded, and provide these to the `add-symbol-file' command. 12505 12506 Some embedded operating systems, like Sun Chorus and VxWorks, can 12507 load relocatable files into an already running program; such 12508 systems typically make the requirements above easy to meet. 12509 However, it's important to recognize that many native systems use 12510 complex link procedures (`.linkonce' section factoring and C++ 12511 constructor table assembly, for example) that make the 12512 requirements difficult to meet. In general, one cannot assume 12513 that using `add-symbol-file' to read a relocatable object file's 12514 symbolic information will have the same effect as linking the 12515 relocatable object file into the program in the normal way. 12516 12517 `add-symbol-file' does not repeat if you press <RET> after using 12518 it. 12519 12520`add-symbol-file-from-memory ADDRESS' 12521 Load symbols from the given ADDRESS in a dynamically loaded object 12522 file whose image is mapped directly into the inferior's memory. 12523 For example, the Linux kernel maps a `syscall DSO' into each 12524 process's address space; this DSO provides kernel-specific code for 12525 some system calls. The argument can be any expression whose 12526 evaluation yields the address of the file's shared object file 12527 header. For this command to work, you must have used 12528 `symbol-file' or `exec-file' commands in advance. 12529 12530`add-shared-symbol-files LIBRARY-FILE' 12531`assf LIBRARY-FILE' 12532 The `add-shared-symbol-files' command can currently be used only 12533 in the Cygwin build of GDB on MS-Windows OS, where it is an alias 12534 for the `dll-symbols' command (*note Cygwin Native::). GDB 12535 automatically looks for shared libraries, however if GDB does not 12536 find yours, you can invoke `add-shared-symbol-files'. It takes 12537 one argument: the shared library's file name. `assf' is a 12538 shorthand alias for `add-shared-symbol-files'. 12539 12540`section SECTION ADDR' 12541 The `section' command changes the base address of the named 12542 SECTION of the exec file to ADDR. This can be used if the exec 12543 file does not contain section addresses, (such as in the `a.out' 12544 format), or when the addresses specified in the file itself are 12545 wrong. Each section must be changed separately. The `info files' 12546 command, described below, lists all the sections and their 12547 addresses. 12548 12549`info files' 12550`info target' 12551 `info files' and `info target' are synonymous; both print the 12552 current target (*note Specifying a Debugging Target: Targets.), 12553 including the names of the executable and core dump files 12554 currently in use by GDB, and the files from which symbols were 12555 loaded. The command `help target' lists all possible targets 12556 rather than current ones. 12557 12558`maint info sections' 12559 Another command that can give you extra information about program 12560 sections is `maint info sections'. In addition to the section 12561 information displayed by `info files', this command displays the 12562 flags and file offset of each section in the executable and core 12563 dump files. In addition, `maint info sections' provides the 12564 following command options (which may be arbitrarily combined): 12565 12566 `ALLOBJ' 12567 Display sections for all loaded object files, including 12568 shared libraries. 12569 12570 `SECTIONS' 12571 Display info only for named SECTIONS. 12572 12573 `SECTION-FLAGS' 12574 Display info only for sections for which SECTION-FLAGS are 12575 true. The section flags that GDB currently knows about are: 12576 `ALLOC' 12577 Section will have space allocated in the process when 12578 loaded. Set for all sections except those containing 12579 debug information. 12580 12581 `LOAD' 12582 Section will be loaded from the file into the child 12583 process memory. Set for pre-initialized code and data, 12584 clear for `.bss' sections. 12585 12586 `RELOC' 12587 Section needs to be relocated before loading. 12588 12589 `READONLY' 12590 Section cannot be modified by the child process. 12591 12592 `CODE' 12593 Section contains executable code only. 12594 12595 `DATA' 12596 Section contains data only (no executable code). 12597 12598 `ROM' 12599 Section will reside in ROM. 12600 12601 `CONSTRUCTOR' 12602 Section contains data for constructor/destructor lists. 12603 12604 `HAS_CONTENTS' 12605 Section is not empty. 12606 12607 `NEVER_LOAD' 12608 An instruction to the linker to not output the section. 12609 12610 `COFF_SHARED_LIBRARY' 12611 A notification to the linker that the section contains 12612 COFF shared library information. 12613 12614 `IS_COMMON' 12615 Section contains common symbols. 12616 12617`set trust-readonly-sections on' 12618 Tell GDB that readonly sections in your object file really are 12619 read-only (i.e. that their contents will not change). In that 12620 case, GDB can fetch values from these sections out of the object 12621 file, rather than from the target program. For some targets 12622 (notably embedded ones), this can be a significant enhancement to 12623 debugging performance. 12624 12625 The default is off. 12626 12627`set trust-readonly-sections off' 12628 Tell GDB not to trust readonly sections. This means that the 12629 contents of the section might change while the program is running, 12630 and must therefore be fetched from the target when needed. 12631 12632`show trust-readonly-sections' 12633 Show the current setting of trusting readonly sections. 12634 12635 All file-specifying commands allow both absolute and relative file 12636names as arguments. GDB always converts the file name to an absolute 12637file name and remembers it that way. 12638 12639 GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and 12640IBM RS/6000 AIX shared libraries. 12641 12642 On MS-Windows GDB must be linked with the Expat library to support 12643shared libraries. *Note Expat::. 12644 12645 GDB automatically loads symbol definitions from shared libraries 12646when you use the `run' command, or when you examine a core file. 12647(Before you issue the `run' command, GDB does not understand references 12648to a function in a shared library, however--unless you are debugging a 12649core file). 12650 12651 On HP-UX, if the program loads a library explicitly, GDB 12652automatically loads the symbols at the time of the `shl_load' call. 12653 12654 There are times, however, when you may wish to not automatically load 12655symbol definitions from shared libraries, such as when they are 12656particularly large or there are many of them. 12657 12658 To control the automatic loading of shared library symbols, use the 12659commands: 12660 12661`set auto-solib-add MODE' 12662 If MODE is `on', symbols from all shared object libraries will be 12663 loaded automatically when the inferior begins execution, you 12664 attach to an independently started inferior, or when the dynamic 12665 linker informs GDB that a new library has been loaded. If MODE is 12666 `off', symbols must be loaded manually, using the `sharedlibrary' 12667 command. The default value is `on'. 12668 12669 If your program uses lots of shared libraries with debug info that 12670 takes large amounts of memory, you can decrease the GDB memory 12671 footprint by preventing it from automatically loading the symbols 12672 from shared libraries. To that end, type `set auto-solib-add off' 12673 before running the inferior, then load each library whose debug 12674 symbols you do need with `sharedlibrary REGEXP', where REGEXP is a 12675 regular expression that matches the libraries whose symbols you 12676 want to be loaded. 12677 12678`show auto-solib-add' 12679 Display the current autoloading mode. 12680 12681 To explicitly load shared library symbols, use the `sharedlibrary' 12682command: 12683 12684`info share REGEX' 12685`info sharedlibrary REGEX' 12686 Print the names of the shared libraries which are currently loaded 12687 that match REGEX. If REGEX is omitted then print all shared 12688 libraries that are loaded. 12689 12690`sharedlibrary REGEX' 12691`share REGEX' 12692 Load shared object library symbols for files matching a Unix 12693 regular expression. As with files loaded automatically, it only 12694 loads shared libraries required by your program for a core file or 12695 after typing `run'. If REGEX is omitted all shared libraries 12696 required by your program are loaded. 12697 12698`nosharedlibrary' 12699 Unload all shared object library symbols. This discards all 12700 symbols that have been loaded from all shared libraries. Symbols 12701 from shared libraries that were loaded by explicit user requests 12702 are not discarded. 12703 12704 Sometimes you may wish that GDB stops and gives you control when any 12705of shared library events happen. Use the `set stop-on-solib-events' 12706command for this: 12707 12708`set stop-on-solib-events' 12709 This command controls whether GDB should give you control when the 12710 dynamic linker notifies it about some shared library event. The 12711 most common event of interest is loading or unloading of a new 12712 shared library. 12713 12714`show stop-on-solib-events' 12715 Show whether GDB stops and gives you control when shared library 12716 events happen. 12717 12718 Shared libraries are also supported in many cross or remote debugging 12719configurations. GDB needs to have access to the target's libraries; 12720this can be accomplished either by providing copies of the libraries on 12721the host system, or by asking GDB to automatically retrieve the 12722libraries from the target. If copies of the target libraries are 12723provided, they need to be the same as the target libraries, although the 12724copies on the target can be stripped as long as the copies on the host 12725are not. 12726 12727 For remote debugging, you need to tell GDB where the target 12728libraries are, so that it can load the correct copies--otherwise, it 12729may try to load the host's libraries. GDB has two variables to specify 12730the search directories for target libraries. 12731 12732`set sysroot PATH' 12733 Use PATH as the system root for the program being debugged. Any 12734 absolute shared library paths will be prefixed with PATH; many 12735 runtime loaders store the absolute paths to the shared library in 12736 the target program's memory. If you use `set sysroot' to find 12737 shared libraries, they need to be laid out in the same way that 12738 they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy 12739 under PATH. 12740 12741 If PATH starts with the sequence `remote:', GDB will retrieve the 12742 target libraries from the remote system. This is only supported 12743 when using a remote target that supports the `remote get' command 12744 (*note Sending files to a remote system: File Transfer.). The 12745 part of PATH following the initial `remote:' (if present) is used 12746 as system root prefix on the remote file system. (1) 12747 12748 For targets with an MS-DOS based filesystem, such as MS-Windows and 12749 SymbianOS, GDB tries prefixing a few variants of the target 12750 absolute file name with PATH. But first, on Unix hosts, GDB 12751 converts all backslash directory separators into forward slashes, 12752 because the backslash is not a directory separator on Unix: 12753 12754 c:\foo\bar.dll => c:/foo/bar.dll 12755 12756 Then, GDB attempts prefixing the target file name with PATH, and 12757 looks for the resulting file name in the host file system: 12758 12759 c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll 12760 12761 If that does not find the shared library, GDB tries removing the 12762 `:' character from the drive spec, both for convenience, and, for 12763 the case of the host file system not supporting file names with 12764 colons: 12765 12766 c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll 12767 12768 This makes it possible to have a system root that mirrors a target 12769 with more than one drive. E.g., you may want to setup your local 12770 copies of the target system shared libraries like so (note `c' vs 12771 `z'): 12772 12773 `/path/to/sysroot/c/sys/bin/foo.dll' 12774 `/path/to/sysroot/c/sys/bin/bar.dll' 12775 `/path/to/sysroot/z/sys/bin/bar.dll' 12776 12777 and point the system root at `/path/to/sysroot', so that GDB can 12778 find the correct copies of both `c:\sys\bin\foo.dll', and 12779 `z:\sys\bin\bar.dll'. 12780 12781 If that still does not find the shared library, GDB tries removing 12782 the whole drive spec from the target file name: 12783 12784 c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll 12785 12786 This last lookup makes it possible to not care about the drive 12787 name, if you don't want or need to. 12788 12789 The `set solib-absolute-prefix' command is an alias for `set 12790 sysroot'. 12791 12792 You can set the default system root by using the configure-time 12793 `--with-sysroot' option. If the system root is inside GDB's 12794 configured binary prefix (set with `--prefix' or `--exec-prefix'), 12795 then the default system root will be updated automatically if the 12796 installed GDB is moved to a new location. 12797 12798`show sysroot' 12799 Display the current shared library prefix. 12800 12801`set solib-search-path PATH' 12802 If this variable is set, PATH is a colon-separated list of 12803 directories to search for shared libraries. `solib-search-path' 12804 is used after `sysroot' fails to locate the library, or if the 12805 path to the library is relative instead of absolute. If you want 12806 to use `solib-search-path' instead of `sysroot', be sure to set 12807 `sysroot' to a nonexistent directory to prevent GDB from finding 12808 your host's libraries. `sysroot' is preferred; setting it to a 12809 nonexistent directory may interfere with automatic loading of 12810 shared library symbols. 12811 12812`show solib-search-path' 12813 Display the current shared library search path. 12814 12815`set target-file-system-kind KIND' 12816 Set assumed file system kind for target reported file names. 12817 12818 Shared library file names as reported by the target system may not 12819 make sense as is on the system GDB is running on. For example, 12820 when remote debugging a target that has MS-DOS based file system 12821 semantics, from a Unix host, the target may be reporting to GDB a 12822 list of loaded shared libraries with file names such as 12823 `c:\Windows\kernel32.dll'. On Unix hosts, there's no concept of 12824 drive letters, so the `c:\' prefix is not normally understood as 12825 indicating an absolute file name, and neither is the backslash 12826 normally considered a directory separator character. In that case, 12827 the native file system would interpret this whole absolute file 12828 name as a relative file name with no directory components. This 12829 would make it impossible to point GDB at a copy of the remote 12830 target's shared libraries on the host using `set sysroot', and 12831 impractical with `set solib-search-path'. Setting 12832 `target-file-system-kind' to `dos-based' tells GDB to interpret 12833 such file names similarly to how the target would, and to map them 12834 to file names valid on GDB's native file system semantics. The 12835 value of KIND can be `"auto"', in addition to one of the supported 12836 file system kinds. In that case, GDB tries to determine the 12837 appropriate file system variant based on the current target's 12838 operating system (*note Configuring the Current ABI: ABI.). The 12839 supported file system settings are: 12840 12841 `unix' 12842 Instruct GDB to assume the target file system is of Unix 12843 kind. Only file names starting the forward slash (`/') 12844 character are considered absolute, and the directory 12845 separator character is also the forward slash. 12846 12847 `dos-based' 12848 Instruct GDB to assume the target file system is DOS based. 12849 File names starting with either a forward slash, or a drive 12850 letter followed by a colon (e.g., `c:'), are considered 12851 absolute, and both the slash (`/') and the backslash (`\\') 12852 characters are considered directory separators. 12853 12854 `auto' 12855 Instruct GDB to use the file system kind associated with the 12856 target operating system (*note Configuring the Current ABI: 12857 ABI.). This is the default. 12858 12859 ---------- Footnotes ---------- 12860 12861 (1) If you want to specify a local system root using a directory 12862that happens to be named `remote:', you need to use some equivalent 12863variant of the name like `./remote:'. 12864 12865 12866File: gdb.info, Node: Separate Debug Files, Next: Index Files, Prev: Files, Up: GDB Files 12867 1286818.2 Debugging Information in Separate Files 12869============================================ 12870 12871GDB allows you to put a program's debugging information in a file 12872separate from the executable itself, in a way that allows GDB to find 12873and load the debugging information automatically. Since debugging 12874information can be very large--sometimes larger than the executable 12875code itself--some systems distribute debugging information for their 12876executables in separate files, which users can install only when they 12877need to debug a problem. 12878 12879 GDB supports two ways of specifying the separate debug info file: 12880 12881 * The executable contains a "debug link" that specifies the name of 12882 the separate debug info file. The separate debug file's name is 12883 usually `EXECUTABLE.debug', where EXECUTABLE is the name of the 12884 corresponding executable file without leading directories (e.g., 12885 `ls.debug' for `/usr/bin/ls'). In addition, the debug link 12886 specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for 12887 the debug file, which GDB uses to validate that the executable and 12888 the debug file came from the same build. 12889 12890 * The executable contains a "build ID", a unique bit string that is 12891 also present in the corresponding debug info file. (This is 12892 supported only on some operating systems, notably those which use 12893 the ELF format for binary files and the GNU Binutils.) For more 12894 details about this feature, see the description of the `--build-id' 12895 command-line option in *note Command Line Options: 12896 (ld.info)Options. The debug info file's name is not specified 12897 explicitly by the build ID, but can be computed from the build ID, 12898 see below. 12899 12900 Depending on the way the debug info file is specified, GDB uses two 12901different methods of looking for the debug file: 12902 12903 * For the "debug link" method, GDB looks up the named file in the 12904 directory of the executable file, then in a subdirectory of that 12905 directory named `.debug', and finally under the global debug 12906 directory, in a subdirectory whose name is identical to the leading 12907 directories of the executable's absolute file name. 12908 12909 * For the "build ID" method, GDB looks in the `.build-id' 12910 subdirectory of the global debug directory for a file named 12911 `NN/NNNNNNNN.debug', where NN are the first 2 hex characters of 12912 the build ID bit string, and NNNNNNNN are the rest of the bit 12913 string. (Real build ID strings are 32 or more hex characters, not 12914 10.) 12915 12916 So, for example, suppose you ask GDB to debug `/usr/bin/ls', which 12917has a debug link that specifies the file `ls.debug', and a build ID 12918whose value in hex is `abcdef1234'. If the global debug directory is 12919`/usr/lib/debug', then GDB will look for the following debug 12920information files, in the indicated order: 12921 12922 - `/usr/lib/debug/.build-id/ab/cdef1234.debug' 12923 12924 - `/usr/bin/ls.debug' 12925 12926 - `/usr/bin/.debug/ls.debug' 12927 12928 - `/usr/lib/debug/usr/bin/ls.debug'. 12929 12930 You can set the global debugging info directory's name, and view the 12931name GDB is currently using. 12932 12933`set debug-file-directory DIRECTORIES' 12934 Set the directories which GDB searches for separate debugging 12935 information files to DIRECTORY. Multiple directory components can 12936 be set concatenating them by a directory separator. 12937 12938`show debug-file-directory' 12939 Show the directories GDB searches for separate debugging 12940 information files. 12941 12942 12943 A debug link is a special section of the executable file named 12944`.gnu_debuglink'. The section must contain: 12945 12946 * A filename, with any leading directory components removed, 12947 followed by a zero byte, 12948 12949 * zero to three bytes of padding, as needed to reach the next 12950 four-byte boundary within the section, and 12951 12952 * a four-byte CRC checksum, stored in the same endianness used for 12953 the executable file itself. The checksum is computed on the 12954 debugging information file's full contents by the function given 12955 below, passing zero as the CRC argument. 12956 12957 Any executable file format can carry a debug link, as long as it can 12958contain a section named `.gnu_debuglink' with the contents described 12959above. 12960 12961 The build ID is a special section in the executable file (and in 12962other ELF binary files that GDB may consider). This section is often 12963named `.note.gnu.build-id', but that name is not mandatory. It 12964contains unique identification for the built files--the ID remains the 12965same across multiple builds of the same build tree. The default 12966algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the 12967content for the build ID string. The same section with an identical 12968value is present in the original built binary with symbols, in its 12969stripped variant, and in the separate debugging information file. 12970 12971 The debugging information file itself should be an ordinary 12972executable, containing a full set of linker symbols, sections, and 12973debugging information. The sections of the debugging information file 12974should have the same names, addresses, and sizes as the original file, 12975but they need not contain any data--much like a `.bss' section in an 12976ordinary executable. 12977 12978 The GNU binary utilities (Binutils) package includes the `objcopy' 12979utility that can produce the separated executable / debugging 12980information file pairs using the following commands: 12981 12982 objcopy --only-keep-debug foo foo.debug 12983 strip -g foo 12984 12985These commands remove the debugging information from the executable 12986file `foo' and place it in the file `foo.debug'. You can use the 12987first, second or both methods to link the two files: 12988 12989 * The debug link method needs the following additional command to 12990 also leave behind a debug link in `foo': 12991 12992 objcopy --add-gnu-debuglink=foo.debug foo 12993 12994 Ulrich Drepper's `elfutils' package, starting with version 0.53, 12995 contains a version of the `strip' command such that the command 12996 `strip foo -f foo.debug' has the same functionality as the two 12997 `objcopy' commands and the `ln -s' command above, together. 12998 12999 * Build ID gets embedded into the main executable using `ld 13000 --build-id' or the GCC counterpart `gcc -Wl,--build-id'. Build ID 13001 support plus compatibility fixes for debug files separation are 13002 present in GNU binary utilities (Binutils) package since version 13003 2.18. 13004 13005The CRC used in `.gnu_debuglink' is the CRC-32 defined in IEEE 802.3 13006using the polynomial: 13007 13008 x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 13009 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1 13010 13011 The function is computed byte at a time, taking the least 13012significant bit of each byte first. The initial pattern `0xffffffff' 13013is used, to ensure leading zeros affect the CRC and the final result is 13014inverted to ensure trailing zeros also affect the CRC. 13015 13016 _Note:_ This is the same CRC polynomial as used in handling the 13017"Remote Serial Protocol" `qCRC' packet (*note GDB Remote Serial 13018Protocol: Remote Protocol.). However in the case of the Remote Serial 13019Protocol, the CRC is computed _most_ significant bit first, and the 13020result is not inverted, so trailing zeros have no effect on the CRC 13021value. 13022 13023 To complete the description, we show below the code of the function 13024which produces the CRC used in `.gnu_debuglink'. Inverting the 13025initially supplied `crc' argument means that an initial call to this 13026function passing in zero will start computing the CRC using 13027`0xffffffff'. 13028 13029 unsigned long 13030 gnu_debuglink_crc32 (unsigned long crc, 13031 unsigned char *buf, size_t len) 13032 { 13033 static const unsigned long crc32_table[256] = 13034 { 13035 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 13036 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 13037 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 13038 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 13039 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 13040 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 13041 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 13042 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 13043 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 13044 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 13045 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 13046 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 13047 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 13048 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 13049 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 13050 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 13051 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 13052 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 13053 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 13054 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 13055 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 13056 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 13057 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 13058 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 13059 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 13060 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 13061 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 13062 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 13063 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 13064 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 13065 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 13066 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 13067 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 13068 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 13069 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 13070 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 13071 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 13072 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 13073 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 13074 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 13075 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 13076 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 13077 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 13078 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 13079 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 13080 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 13081 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 13082 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 13083 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 13084 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 13085 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 13086 0x2d02ef8d 13087 }; 13088 unsigned char *end; 13089 13090 crc = ~crc & 0xffffffff; 13091 for (end = buf + len; buf < end; ++buf) 13092 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); 13093 return ~crc & 0xffffffff; 13094 } 13095 13096This computation does not apply to the "build ID" method. 13097 13098 13099File: gdb.info, Node: Index Files, Next: Symbol Errors, Prev: Separate Debug Files, Up: GDB Files 13100 1310118.3 Index Files Speed Up GDB 13102============================= 13103 13104When GDB finds a symbol file, it scans the symbols in the file in order 13105to construct an internal symbol table. This lets most GDB operations 13106work quickly--at the cost of a delay early on. For large programs, 13107this delay can be quite lengthy, so GDB provides a way to build an 13108index, which speeds up startup. 13109 13110 The index is stored as a section in the symbol file. GDB can write 13111the index to a file, then you can put it into the symbol file using 13112`objcopy'. 13113 13114 To create an index file, use the `save gdb-index' command: 13115 13116`save gdb-index DIRECTORY' 13117 Create an index file for each symbol file currently known by GDB. 13118 Each file is named after its corresponding symbol file, with 13119 `.gdb-index' appended, and is written into the given DIRECTORY. 13120 13121 Once you have created an index file you can merge it into your symbol 13122file, here named `symfile', using `objcopy': 13123 13124 $ objcopy --add-section .gdb_index=symfile.gdb-index \ 13125 --set-section-flags .gdb_index=readonly symfile symfile 13126 13127 There are currently some limitation on indices. They only work when 13128for DWARF debugging information, not stabs. And, they do not currently 13129work for programs using Ada. 13130 13131 13132File: gdb.info, Node: Symbol Errors, Next: Data Files, Prev: Index Files, Up: GDB Files 13133 1313418.4 Errors Reading Symbol Files 13135================================ 13136 13137While reading a symbol file, GDB occasionally encounters problems, such 13138as symbol types it does not recognize, or known bugs in compiler 13139output. By default, GDB does not notify you of such problems, since 13140they are relatively common and primarily of interest to people 13141debugging compilers. If you are interested in seeing information about 13142ill-constructed symbol tables, you can either ask GDB to print only one 13143message about each such type of problem, no matter how many times the 13144problem occurs; or you can ask GDB to print more messages, to see how 13145many times the problems occur, with the `set complaints' command (*note 13146Optional Warnings and Messages: Messages/Warnings.). 13147 13148 The messages currently printed, and their meanings, include: 13149 13150`inner block not inside outer block in SYMBOL' 13151 The symbol information shows where symbol scopes begin and end 13152 (such as at the start of a function or a block of statements). 13153 This error indicates that an inner scope block is not fully 13154 contained in its outer scope blocks. 13155 13156 GDB circumvents the problem by treating the inner block as if it 13157 had the same scope as the outer block. In the error message, 13158 SYMBOL may be shown as "`(don't know)'" if the outer block is not a 13159 function. 13160 13161`block at ADDRESS out of order' 13162 The symbol information for symbol scope blocks should occur in 13163 order of increasing addresses. This error indicates that it does 13164 not do so. 13165 13166 GDB does not circumvent this problem, and has trouble locating 13167 symbols in the source file whose symbols it is reading. (You can 13168 often determine what source file is affected by specifying `set 13169 verbose on'. *Note Optional Warnings and Messages: 13170 Messages/Warnings.) 13171 13172`bad block start address patched' 13173 The symbol information for a symbol scope block has a start address 13174 smaller than the address of the preceding source line. This is 13175 known to occur in the SunOS 4.1.1 (and earlier) C compiler. 13176 13177 GDB circumvents the problem by treating the symbol scope block as 13178 starting on the previous source line. 13179 13180`bad string table offset in symbol N' 13181 Symbol number N contains a pointer into the string table which is 13182 larger than the size of the string table. 13183 13184 GDB circumvents the problem by considering the symbol to have the 13185 name `foo', which may cause other problems if many symbols end up 13186 with this name. 13187 13188`unknown symbol type `0xNN'' 13189 The symbol information contains new data types that GDB does not 13190 yet know how to read. `0xNN' is the symbol type of the 13191 uncomprehended information, in hexadecimal. 13192 13193 GDB circumvents the error by ignoring this symbol information. 13194 This usually allows you to debug your program, though certain 13195 symbols are not accessible. If you encounter such a problem and 13196 feel like debugging it, you can debug `gdb' with itself, breakpoint 13197 on `complain', then go up to the function `read_dbx_symtab' and 13198 examine `*bufp' to see the symbol. 13199 13200`stub type has NULL name' 13201 GDB could not find the full definition for a struct or class. 13202 13203`const/volatile indicator missing (ok if using g++ v1.x), got...' 13204 The symbol information for a C++ member function is missing some 13205 information that recent versions of the compiler should have 13206 output for it. 13207 13208`info mismatch between compiler and debugger' 13209 GDB could not parse a type specification output by the compiler. 13210 13211 13212 13213File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files 13214 1321518.5 GDB Data Files 13216=================== 13217 13218GDB will sometimes read an auxiliary data file. These files are kept 13219in a directory known as the "data directory". 13220 13221 You can set the data directory's name, and view the name GDB is 13222currently using. 13223 13224`set data-directory DIRECTORY' 13225 Set the directory which GDB searches for auxiliary data files to 13226 DIRECTORY. 13227 13228`show data-directory' 13229 Show the directory GDB searches for auxiliary data files. 13230 13231 You can set the default data directory by using the configure-time 13232`--with-gdb-datadir' option. If the data directory is inside GDB's 13233configured binary prefix (set with `--prefix' or `--exec-prefix'), then 13234the default data directory will be updated automatically if the 13235installed GDB is moved to a new location. 13236 13237 13238File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top 13239 1324019 Specifying a Debugging Target 13241******************************** 13242 13243A "target" is the execution environment occupied by your program. 13244 13245 Often, GDB runs in the same host environment as your program; in 13246that case, the debugging target is specified as a side effect when you 13247use the `file' or `core' commands. When you need more flexibility--for 13248example, running GDB on a physically separate host, or controlling a 13249standalone system over a serial port or a realtime system over a TCP/IP 13250connection--you can use the `target' command to specify one of the 13251target types configured for GDB (*note Commands for Managing Targets: 13252Target Commands.). 13253 13254 It is possible to build GDB for several different "target 13255architectures". When GDB is built like that, you can choose one of the 13256available architectures with the `set architecture' command. 13257 13258`set architecture ARCH' 13259 This command sets the current target architecture to ARCH. The 13260 value of ARCH can be `"auto"', in addition to one of the supported 13261 architectures. 13262 13263`show architecture' 13264 Show the current target architecture. 13265 13266`set processor' 13267`processor' 13268 These are alias commands for, respectively, `set architecture' and 13269 `show architecture'. 13270 13271* Menu: 13272 13273* Active Targets:: Active targets 13274* Target Commands:: Commands for managing targets 13275* Byte Order:: Choosing target byte order 13276 13277 13278File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets 13279 1328019.1 Active Targets 13281=================== 13282 13283There are multiple classes of targets such as: processes, executable 13284files or recording sessions. Core files belong to the process class, 13285making core file and process mutually exclusive. Otherwise, GDB can 13286work concurrently on multiple active targets, one in each class. This 13287allows you to (for example) start a process and inspect its activity, 13288while still having access to the executable file after the process 13289finishes. Or if you start process recording (*note Reverse 13290Execution::) and `reverse-step' there, you are presented a virtual 13291layer of the recording target, while the process target remains stopped 13292at the chronologically last point of the process execution. 13293 13294 Use the `core-file' and `exec-file' commands to select a new core 13295file or executable target (*note Commands to Specify Files: Files.). To 13296specify as a target a process that is already running, use the `attach' 13297command (*note Debugging an Already-running Process: Attach.). 13298 13299 13300File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets 13301 1330219.2 Commands for Managing Targets 13303================================== 13304 13305`target TYPE PARAMETERS' 13306 Connects the GDB host environment to a target machine or process. 13307 A target is typically a protocol for talking to debugging 13308 facilities. You use the argument TYPE to specify the type or 13309 protocol of the target machine. 13310 13311 Further PARAMETERS are interpreted by the target protocol, but 13312 typically include things like device names or host names to connect 13313 with, process numbers, and baud rates. 13314 13315 The `target' command does not repeat if you press <RET> again 13316 after executing the command. 13317 13318`help target' 13319 Displays the names of all targets available. To display targets 13320 currently selected, use either `info target' or `info files' 13321 (*note Commands to Specify Files: Files.). 13322 13323`help target NAME' 13324 Describe a particular target, including any parameters necessary to 13325 select it. 13326 13327`set gnutarget ARGS' 13328 GDB uses its own library BFD to read your files. GDB knows 13329 whether it is reading an "executable", a "core", or a ".o" file; 13330 however, you can specify the file format with the `set gnutarget' 13331 command. Unlike most `target' commands, with `gnutarget' the 13332 `target' refers to a program, not a machine. 13333 13334 _Warning:_ To specify a file format with `set gnutarget', you 13335 must know the actual BFD name. 13336 13337 *Note Commands to Specify Files: Files. 13338 13339`show gnutarget' 13340 Use the `show gnutarget' command to display what file format 13341 `gnutarget' is set to read. If you have not set `gnutarget', GDB 13342 will determine the file format for each file automatically, and 13343 `show gnutarget' displays `The current BDF target is "auto"'. 13344 13345 Here are some common targets (available, or not, depending on the GDB 13346configuration): 13347 13348`target exec PROGRAM' 13349 An executable file. `target exec PROGRAM' is the same as 13350 `exec-file PROGRAM'. 13351 13352`target core FILENAME' 13353 A core dump file. `target core FILENAME' is the same as 13354 `core-file FILENAME'. 13355 13356`target remote MEDIUM' 13357 A remote system connected to GDB via a serial line or network 13358 connection. This command tells GDB to use its own remote protocol 13359 over MEDIUM for debugging. *Note Remote Debugging::. 13360 13361 For example, if you have a board connected to `/dev/ttya' on the 13362 machine running GDB, you could say: 13363 13364 target remote /dev/ttya 13365 13366 `target remote' supports the `load' command. This is only useful 13367 if you have some other way of getting the stub to the target 13368 system, and you can put it somewhere in memory where it won't get 13369 clobbered by the download. 13370 13371`target sim [SIMARGS] ...' 13372 Builtin CPU simulator. GDB includes simulators for most 13373 architectures. In general, 13374 target sim 13375 load 13376 run 13377 works; however, you cannot assume that a specific memory map, 13378 device drivers, or even basic I/O is available, although some 13379 simulators do provide these. For info about any 13380 processor-specific simulator details, see the appropriate section 13381 in *note Embedded Processors: Embedded Processors. 13382 13383 13384 Some configurations may include these targets as well: 13385 13386`target nrom DEV' 13387 NetROM ROM emulator. This target only supports downloading. 13388 13389 13390 Different targets are available on different configurations of GDB; 13391your configuration may have more or fewer targets. 13392 13393 Many remote targets require you to download the executable's code 13394once you've successfully established a connection. You may wish to 13395control various aspects of this process. 13396 13397`set hash' 13398 This command controls whether a hash mark `#' is displayed while 13399 downloading a file to the remote monitor. If on, a hash mark is 13400 displayed after each S-record is successfully downloaded to the 13401 monitor. 13402 13403`show hash' 13404 Show the current status of displaying the hash mark. 13405 13406`set debug monitor' 13407 Enable or disable display of communications messages between GDB 13408 and the remote monitor. 13409 13410`show debug monitor' 13411 Show the current status of displaying communications between GDB 13412 and the remote monitor. 13413 13414`load FILENAME' 13415 Depending on what remote debugging facilities are configured into 13416 GDB, the `load' command may be available. Where it exists, it is 13417 meant to make FILENAME (an executable) available for debugging on 13418 the remote system--by downloading, or dynamic linking, for example. 13419 `load' also records the FILENAME symbol table in GDB, like the 13420 `add-symbol-file' command. 13421 13422 If your GDB does not have a `load' command, attempting to execute 13423 it gets the error message "`You can't do that when your target is 13424 ...'" 13425 13426 The file is loaded at whatever address is specified in the 13427 executable. For some object file formats, you can specify the 13428 load address when you link the program; for other formats, like 13429 a.out, the object file format specifies a fixed address. 13430 13431 Depending on the remote side capabilities, GDB may be able to load 13432 programs into flash memory. 13433 13434 `load' does not repeat if you press <RET> again after using it. 13435 13436 13437File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets 13438 1343919.3 Choosing Target Byte Order 13440=============================== 13441 13442Some types of processors, such as the MIPS, PowerPC, and Renesas SH, 13443offer the ability to run either big-endian or little-endian byte 13444orders. Usually the executable or symbol will include a bit to 13445designate the endian-ness, and you will not need to worry about which 13446to use. However, you may still find it useful to adjust GDB's idea of 13447processor endian-ness manually. 13448 13449`set endian big' 13450 Instruct GDB to assume the target is big-endian. 13451 13452`set endian little' 13453 Instruct GDB to assume the target is little-endian. 13454 13455`set endian auto' 13456 Instruct GDB to use the byte order associated with the executable. 13457 13458`show endian' 13459 Display GDB's current idea of the target byte order. 13460 13461 13462 Note that these commands merely adjust interpretation of symbolic 13463data on the host, and that they have absolutely no effect on the target 13464system. 13465 13466 13467File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top 13468 1346920 Debugging Remote Programs 13470**************************** 13471 13472If you are trying to debug a program running on a machine that cannot 13473run GDB in the usual way, it is often useful to use remote debugging. 13474For example, you might use remote debugging on an operating system 13475kernel, or on a small system which does not have a general purpose 13476operating system powerful enough to run a full-featured debugger. 13477 13478 Some configurations of GDB have special serial or TCP/IP interfaces 13479to make this work with particular debugging targets. In addition, GDB 13480comes with a generic serial protocol (specific to GDB, but not specific 13481to any particular target system) which you can use if you write the 13482remote stubs--the code that runs on the remote system to communicate 13483with GDB. 13484 13485 Other remote targets may be available in your configuration of GDB; 13486use `help target' to list them. 13487 13488* Menu: 13489 13490* Connecting:: Connecting to a remote target 13491* File Transfer:: Sending files to a remote system 13492* Server:: Using the gdbserver program 13493* Remote Configuration:: Remote configuration 13494* Remote Stub:: Implementing a remote stub 13495 13496 13497File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging 13498 1349920.1 Connecting to a Remote Target 13500================================== 13501 13502On the GDB host machine, you will need an unstripped copy of your 13503program, since GDB needs symbol and debugging information. Start up 13504GDB as usual, using the name of the local copy of your program as the 13505first argument. 13506 13507 GDB can communicate with the target over a serial line, or over an 13508IP network using TCP or UDP. In each case, GDB uses the same protocol 13509for debugging your program; only the medium carrying the debugging 13510packets varies. The `target remote' command establishes a connection 13511to the target. Its arguments indicate which medium to use: 13512 13513`target remote SERIAL-DEVICE' 13514 Use SERIAL-DEVICE to communicate with the target. For example, to 13515 use a serial line connected to the device named `/dev/ttyb': 13516 13517 target remote /dev/ttyb 13518 13519 If you're using a serial line, you may want to give GDB the 13520 `--baud' option, or use the `set remotebaud' command (*note set 13521 remotebaud: Remote Configuration.) before the `target' command. 13522 13523`target remote `HOST:PORT'' 13524`target remote `tcp:HOST:PORT'' 13525 Debug using a TCP connection to PORT on HOST. The HOST may be 13526 either a host name or a numeric IP address; PORT must be a decimal 13527 number. The HOST could be the target machine itself, if it is 13528 directly connected to the net, or it might be a terminal server 13529 which in turn has a serial line to the target. 13530 13531 For example, to connect to port 2828 on a terminal server named 13532 `manyfarms': 13533 13534 target remote manyfarms:2828 13535 13536 If your remote target is actually running on the same machine as 13537 your debugger session (e.g. a simulator for your target running on 13538 the same host), you can omit the hostname. For example, to 13539 connect to port 1234 on your local machine: 13540 13541 target remote :1234 13542 Note that the colon is still required here. 13543 13544`target remote `udp:HOST:PORT'' 13545 Debug using UDP packets to PORT on HOST. For example, to connect 13546 to UDP port 2828 on a terminal server named `manyfarms': 13547 13548 target remote udp:manyfarms:2828 13549 13550 When using a UDP connection for remote debugging, you should keep 13551 in mind that the `U' stands for "Unreliable". UDP can silently 13552 drop packets on busy or unreliable networks, which will cause 13553 havoc with your debugging session. 13554 13555`target remote | COMMAND' 13556 Run COMMAND in the background and communicate with it using a 13557 pipe. The COMMAND is a shell command, to be parsed and expanded 13558 by the system's command shell, `/bin/sh'; it should expect remote 13559 protocol packets on its standard input, and send replies on its 13560 standard output. You could use this to run a stand-alone simulator 13561 that speaks the remote debugging protocol, to make net connections 13562 using programs like `ssh', or for other similar tricks. 13563 13564 If COMMAND closes its standard output (perhaps by exiting), GDB 13565 will try to send it a `SIGTERM' signal. (If the program has 13566 already exited, this will have no effect.) 13567 13568 13569 Once the connection has been established, you can use all the usual 13570commands to examine and change data. The remote program is already 13571running; you can use `step' and `continue', and you do not need to use 13572`run'. 13573 13574 Whenever GDB is waiting for the remote program, if you type the 13575interrupt character (often `Ctrl-c'), GDB attempts to stop the program. 13576This may or may not succeed, depending in part on the hardware and the 13577serial drivers the remote system uses. If you type the interrupt 13578character once again, GDB displays this prompt: 13579 13580 Interrupted while waiting for the program. 13581 Give up (and stop debugging it)? (y or n) 13582 13583 If you type `y', GDB abandons the remote debugging session. (If you 13584decide you want to try again later, you can use `target remote' again 13585to connect once more.) If you type `n', GDB goes back to waiting. 13586 13587`detach' 13588 When you have finished debugging the remote program, you can use 13589 the `detach' command to release it from GDB control. Detaching 13590 from the target normally resumes its execution, but the results 13591 will depend on your particular remote stub. After the `detach' 13592 command, GDB is free to connect to another target. 13593 13594`disconnect' 13595 The `disconnect' command behaves like `detach', except that the 13596 target is generally not resumed. It will wait for GDB (this 13597 instance or another one) to connect and continue debugging. After 13598 the `disconnect' command, GDB is again free to connect to another 13599 target. 13600 13601`monitor CMD' 13602 This command allows you to send arbitrary commands directly to the 13603 remote monitor. Since GDB doesn't care about the commands it 13604 sends like this, this command is the way to extend GDB--you can 13605 add new commands that only the external monitor will understand 13606 and implement. 13607 13608 13609File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Remote Debugging 13610 1361120.2 Sending files to a remote system 13612===================================== 13613 13614Some remote targets offer the ability to transfer files over the same 13615connection used to communicate with GDB. This is convenient for 13616targets accessible through other means, e.g. GNU/Linux systems running 13617`gdbserver' over a network interface. For other targets, e.g. embedded 13618devices with only a single serial port, this may be the only way to 13619upload or download files. 13620 13621 Not all remote targets support these commands. 13622 13623`remote put HOSTFILE TARGETFILE' 13624 Copy file HOSTFILE from the host system (the machine running GDB) 13625 to TARGETFILE on the target system. 13626 13627`remote get TARGETFILE HOSTFILE' 13628 Copy file TARGETFILE from the target system to HOSTFILE on the 13629 host system. 13630 13631`remote delete TARGETFILE' 13632 Delete TARGETFILE from the target system. 13633 13634 13635 13636File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer, Up: Remote Debugging 13637 1363820.3 Using the `gdbserver' Program 13639================================== 13640 13641`gdbserver' is a control program for Unix-like systems, which allows 13642you to connect your program with a remote GDB via `target remote'--but 13643without linking in the usual debugging stub. 13644 13645 `gdbserver' is not a complete replacement for the debugging stubs, 13646because it requires essentially the same operating-system facilities 13647that GDB itself does. In fact, a system that can run `gdbserver' to 13648connect to a remote GDB could also run GDB locally! `gdbserver' is 13649sometimes useful nevertheless, because it is a much smaller program 13650than GDB itself. It is also easier to port than all of GDB, so you may 13651be able to get started more quickly on a new system by using 13652`gdbserver'. Finally, if you develop code for real-time systems, you 13653may find that the tradeoffs involved in real-time operation make it 13654more convenient to do as much development work as possible on another 13655system, for example by cross-compiling. You can use `gdbserver' to 13656make a similar choice for debugging. 13657 13658 GDB and `gdbserver' communicate via either a serial line or a TCP 13659connection, using the standard GDB remote serial protocol. 13660 13661 _Warning:_ `gdbserver' does not have any built-in security. Do 13662 not run `gdbserver' connected to any public network; a GDB 13663 connection to `gdbserver' provides access to the target system 13664 with the same privileges as the user running `gdbserver'. 13665 1366620.3.1 Running `gdbserver' 13667-------------------------- 13668 13669Run `gdbserver' on the target system. You need a copy of the program 13670you want to debug, including any libraries it requires. `gdbserver' 13671does not need your program's symbol table, so you can strip the program 13672if necessary to save space. GDB on the host system does all the symbol 13673handling. 13674 13675 To use the server, you must tell it how to communicate with GDB; the 13676name of your program; and the arguments for your program. The usual 13677syntax is: 13678 13679 target> gdbserver COMM PROGRAM [ ARGS ... ] 13680 13681 COMM is either a device name (to use a serial line) or a TCP 13682hostname and portnumber. For example, to debug Emacs with the argument 13683`foo.txt' and communicate with GDB over the serial port `/dev/com1': 13684 13685 target> gdbserver /dev/com1 emacs foo.txt 13686 13687 `gdbserver' waits passively for the host GDB to communicate with it. 13688 13689 To use a TCP connection instead of a serial line: 13690 13691 target> gdbserver host:2345 emacs foo.txt 13692 13693 The only difference from the previous example is the first argument, 13694specifying that you are communicating with the host GDB via TCP. The 13695`host:2345' argument means that `gdbserver' is to expect a TCP 13696connection from machine `host' to local TCP port 2345. (Currently, the 13697`host' part is ignored.) You can choose any number you want for the 13698port number as long as it does not conflict with any TCP ports already 13699in use on the target system (for example, `23' is reserved for 13700`telnet').(1) You must use the same port number with the host GDB 13701`target remote' command. 13702 1370320.3.1.1 Attaching to a Running Program 13704....................................... 13705 13706On some targets, `gdbserver' can also attach to running programs. This 13707is accomplished via the `--attach' argument. The syntax is: 13708 13709 target> gdbserver --attach COMM PID 13710 13711 PID is the process ID of a currently running process. It isn't 13712necessary to point `gdbserver' at a binary for the running process. 13713 13714 You can debug processes by name instead of process ID if your target 13715has the `pidof' utility: 13716 13717 target> gdbserver --attach COMM `pidof PROGRAM` 13718 13719 In case more than one copy of PROGRAM is running, or PROGRAM has 13720multiple threads, most versions of `pidof' support the `-s' option to 13721only return the first process ID. 13722 1372320.3.1.2 Multi-Process Mode for `gdbserver' 13724........................................... 13725 13726When you connect to `gdbserver' using `target remote', `gdbserver' 13727debugs the specified program only once. When the program exits, or you 13728detach from it, GDB closes the connection and `gdbserver' exits. 13729 13730 If you connect using `target extended-remote', `gdbserver' enters 13731multi-process mode. When the debugged program exits, or you detach 13732from it, GDB stays connected to `gdbserver' even though no program is 13733running. The `run' and `attach' commands instruct `gdbserver' to run 13734or attach to a new program. The `run' command uses `set remote 13735exec-file' (*note set remote exec-file::) to select the program to run. 13736Command line arguments are supported, except for wildcard expansion and 13737I/O redirection (*note Arguments::). 13738 13739 To start `gdbserver' without supplying an initial command to run or 13740process ID to attach, use the `--multi' command line option. Then you 13741can connect using `target extended-remote' and start the program you 13742want to debug. 13743 13744 `gdbserver' does not automatically exit in multi-process mode. You 13745can terminate it by using `monitor exit' (*note Monitor Commands for 13746gdbserver::). 13747 1374820.3.1.3 Other Command-Line Arguments for `gdbserver' 13749..................................................... 13750 13751The `--debug' option tells `gdbserver' to display extra status 13752information about the debugging process. The `--remote-debug' option 13753tells `gdbserver' to display remote protocol debug output. These 13754options are intended for `gdbserver' development and for bug reports to 13755the developers. 13756 13757 The `--wrapper' option specifies a wrapper to launch programs for 13758debugging. The option should be followed by the name of the wrapper, 13759then any command-line arguments to pass to the wrapper, then `--' 13760indicating the end of the wrapper arguments. 13761 13762 `gdbserver' runs the specified wrapper program with a combined 13763command line including the wrapper arguments, then the name of the 13764program to debug, then any arguments to the program. The wrapper runs 13765until it executes your program, and then GDB gains control. 13766 13767 You can use any program that eventually calls `execve' with its 13768arguments as a wrapper. Several standard Unix utilities do this, e.g. 13769`env' and `nohup'. Any Unix shell script ending with `exec "$@"' will 13770also work. 13771 13772 For example, you can use `env' to pass an environment variable to 13773the debugged program, without setting the variable in `gdbserver''s 13774environment: 13775 13776 $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog 13777 1377820.3.2 Connecting to `gdbserver' 13779-------------------------------- 13780 13781Run GDB on the host system. 13782 13783 First make sure you have the necessary symbol files. Load symbols 13784for your application using the `file' command before you connect. Use 13785`set sysroot' to locate target libraries (unless your GDB was compiled 13786with the correct sysroot using `--with-sysroot'). 13787 13788 The symbol file and target libraries must exactly match the 13789executable and libraries on the target, with one exception: the files 13790on the host system should not be stripped, even if the files on the 13791target system are. Mismatched or missing files will lead to confusing 13792results during debugging. On GNU/Linux targets, mismatched or missing 13793files may also prevent `gdbserver' from debugging multi-threaded 13794programs. 13795 13796 Connect to your target (*note Connecting to a Remote Target: 13797Connecting.). For TCP connections, you must start up `gdbserver' prior 13798to using the `target remote' command. Otherwise you may get an error 13799whose text depends on the host system, but which usually looks 13800something like `Connection refused'. Don't use the `load' command in 13801GDB when using `gdbserver', since the program is already on the target. 13802 1380320.3.3 Monitor Commands for `gdbserver' 13804--------------------------------------- 13805 13806During a GDB session using `gdbserver', you can use the `monitor' 13807command to send special requests to `gdbserver'. Here are the 13808available commands. 13809 13810`monitor help' 13811 List the available monitor commands. 13812 13813`monitor set debug 0' 13814`monitor set debug 1' 13815 Disable or enable general debugging messages. 13816 13817`monitor set remote-debug 0' 13818`monitor set remote-debug 1' 13819 Disable or enable specific debugging messages associated with the 13820 remote protocol (*note Remote Protocol::). 13821 13822`monitor set libthread-db-search-path [PATH]' 13823 When this command is issued, PATH is a colon-separated list of 13824 directories to search for `libthread_db' (*note set 13825 libthread-db-search-path: Threads.). If you omit PATH, 13826 `libthread-db-search-path' will be reset to an empty list. 13827 13828`monitor exit' 13829 Tell gdbserver to exit immediately. This command should be 13830 followed by `disconnect' to close the debugging session. 13831 `gdbserver' will detach from any attached processes and kill any 13832 processes it created. Use `monitor exit' to terminate `gdbserver' 13833 at the end of a multi-process mode debug session. 13834 13835 1383620.3.4 Tracepoints support in `gdbserver' 13837----------------------------------------- 13838 13839On some targets, `gdbserver' supports tracepoints, fast tracepoints and 13840static tracepoints. 13841 13842 For fast or static tracepoints to work, a special library called the 13843"in-process agent" (IPA), must be loaded in the inferior process. This 13844library is built and distributed as an integral part of `gdbserver'. 13845In addition, support for static tracepoints requires building the 13846in-process agent library with static tracepoints support. At present, 13847the UST (LTTng Userspace Tracer, `http://lttng.org/ust') tracing engine 13848is supported. This support is automatically available if UST 13849development headers are found in the standard include path when 13850`gdbserver' is built, or if `gdbserver' was explicitly configured using 13851`--with-ust' to point at such headers. You can explicitly disable the 13852support using `--with-ust=no'. 13853 13854 There are several ways to load the in-process agent in your program: 13855 13856`Specifying it as dependency at link time' 13857 You can link your program dynamically with the in-process agent 13858 library. On most systems, this is accomplished by adding 13859 `-linproctrace' to the link command. 13860 13861`Using the system's preloading mechanisms' 13862 You can force loading the in-process agent at startup time by using 13863 your system's support for preloading shared libraries. Many Unixes 13864 support the concept of preloading user defined libraries. In most 13865 cases, you do that by specifying `LD_PRELOAD=libinproctrace.so' in 13866 the environment. See also the description of `gdbserver''s 13867 `--wrapper' command line option. 13868 13869`Using GDB to force loading the agent at run time' 13870 On some systems, you can force the inferior to load a shared 13871 library, by calling a dynamic loader function in the inferior that 13872 takes care of dynamically looking up and loading a shared library. 13873 On most Unix systems, the function is `dlopen'. You'll use the 13874 `call' command for that. For example: 13875 13876 (gdb) call dlopen ("libinproctrace.so", ...) 13877 13878 Note that on most Unix systems, for the `dlopen' function to be 13879 available, the program needs to be linked with `-ldl'. 13880 13881 On systems that have a userspace dynamic loader, like most Unix 13882systems, when you connect to `gdbserver' using `target remote', you'll 13883find that the program is stopped at the dynamic loader's entry point, 13884and no shared library has been loaded in the program's address space 13885yet, including the in-process agent. In that case, before being able 13886to use any of the fast or static tracepoints features, you need to let 13887the loader run and load the shared libraries. The simplest way to do 13888that is to run the program to the main procedure. E.g., if debugging a 13889C or C++ program, start `gdbserver' like so: 13890 13891 $ gdbserver :9999 myprogram 13892 13893 Start GDB and connect to `gdbserver' like so, and run to main: 13894 13895 $ gdb myprogram 13896 (gdb) target remote myhost:9999 13897 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 13898 (gdb) b main 13899 (gdb) continue 13900 13901 The in-process tracing agent library should now be loaded into the 13902process; you can confirm it with the `info sharedlibrary' command, 13903which will list `libinproctrace.so' as loaded in the process. You are 13904now ready to install fast tracepoints, list static tracepoint markers, 13905probe static tracepoints markers, and start tracing. 13906 13907 ---------- Footnotes ---------- 13908 13909 (1) If you choose a port number that conflicts with another service, 13910`gdbserver' prints an error message and exits. 13911 13912 13913File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging 13914 1391520.4 Remote Configuration 13916========================= 13917 13918This section documents the configuration options available when 13919debugging remote programs. For the options related to the File I/O 13920extensions of the remote protocol, see *note system-call-allowed: 13921system. 13922 13923`set remoteaddresssize BITS' 13924 Set the maximum size of address in a memory packet to the specified 13925 number of bits. GDB will mask off the address bits above that 13926 number, when it passes addresses to the remote target. The 13927 default value is the number of bits in the target's address. 13928 13929`show remoteaddresssize' 13930 Show the current value of remote address size in bits. 13931 13932`set remotebaud N' 13933 Set the baud rate for the remote serial I/O to N baud. The value 13934 is used to set the speed of the serial port used for debugging 13935 remote targets. 13936 13937`show remotebaud' 13938 Show the current speed of the remote connection. 13939 13940`set remotebreak' 13941 If set to on, GDB sends a `BREAK' signal to the remote when you 13942 type `Ctrl-c' to interrupt the program running on the remote. If 13943 set to off, GDB sends the `Ctrl-C' character instead. The default 13944 is off, since most remote systems expect to see `Ctrl-C' as the 13945 interrupt signal. 13946 13947`show remotebreak' 13948 Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote 13949 program. 13950 13951`set remoteflow on' 13952`set remoteflow off' 13953 Enable or disable hardware flow control (`RTS'/`CTS') on the 13954 serial port used to communicate to the remote target. 13955 13956`show remoteflow' 13957 Show the current setting of hardware flow control. 13958 13959`set remotelogbase BASE' 13960 Set the base (a.k.a. radix) of logging serial protocol 13961 communications to BASE. Supported values of BASE are: `ascii', 13962 `octal', and `hex'. The default is `ascii'. 13963 13964`show remotelogbase' 13965 Show the current setting of the radix for logging remote serial 13966 protocol. 13967 13968`set remotelogfile FILE' 13969 Record remote serial communications on the named FILE. The 13970 default is not to record at all. 13971 13972`show remotelogfile.' 13973 Show the current setting of the file name on which to record the 13974 serial communications. 13975 13976`set remotetimeout NUM' 13977 Set the timeout limit to wait for the remote target to respond to 13978 NUM seconds. The default is 2 seconds. 13979 13980`show remotetimeout' 13981 Show the current number of seconds to wait for the remote target 13982 responses. 13983 13984`set remote hardware-watchpoint-limit LIMIT' 13985`set remote hardware-breakpoint-limit LIMIT' 13986 Restrict GDB to using LIMIT remote hardware breakpoint or 13987 watchpoints. A limit of -1, the default, is treated as unlimited. 13988 13989`set remote exec-file FILENAME' 13990`show remote exec-file' 13991 Select the file used for `run' with `target extended-remote'. 13992 This should be set to a filename valid on the target system. If 13993 it is not set, the target will use a default filename (e.g. the 13994 last program run). 13995 13996`set remote username USERNAME' 13997`show remote username' 13998 Set the username to be sent to targets that require a login. The 13999 username is an arbitary string. 14000 14001`set remote password PASSWORD' 14002`show remote password' 14003 Set the password to be sent to targets that require a login. The 14004 password is an arbitary string. At present it is stored as 14005 cleartext. 14006 14007`set remote interrupt-sequence' 14008 Allow the user to select one of `Ctrl-C', a `BREAK' or `BREAK-g' 14009 as the sequence to the remote target in order to interrupt the 14010 execution. `Ctrl-C' is a default. Some system prefers `BREAK' 14011 which is high level of serial line for some certain time. Linux 14012 kernel prefers `BREAK-g', a.k.a Magic SysRq g. It is `BREAK' 14013 signal followed by character `g'. 14014 14015`show interrupt-sequence' 14016 Show which of `Ctrl-C', `BREAK' or `BREAK-g' is sent by GDB to 14017 interrupt the remote program. `BREAK-g' is BREAK signal followed 14018 by `g' and also known as Magic SysRq g. 14019 14020`set remote interrupt-on-connect' 14021 Specify whether interrupt-sequence is sent to remote target when 14022 GDB connects to it. This is mostly needed when you debug Linux 14023 kernel. Linux kernel expects `BREAK' followed by `g' which is 14024 known as Magic SysRq g in order to connect GDB. 14025 14026`show interrupt-on-connect' 14027 Show whether interrupt-sequence is sent to remote target when GDB 14028 connects to it. 14029 14030`set tcp auto-retry on' 14031 Enable auto-retry for remote TCP connections. This is useful if 14032 the remote debugging agent is launched in parallel with GDB; there 14033 is a race condition because the agent may not become ready to 14034 accept the connection before GDB attempts to connect. When 14035 auto-retry is enabled, if the initial attempt to connect fails, 14036 GDB reattempts to establish the connection using the timeout 14037 specified by `set tcp connect-timeout'. 14038 14039`set tcp auto-retry off' 14040 Do not auto-retry failed TCP connections. 14041 14042`show tcp auto-retry' 14043 Show the current auto-retry setting. 14044 14045`set tcp connect-timeout SECONDS' 14046 Set the timeout for establishing a TCP connection to the remote 14047 target to SECONDS. The timeout affects both polling to retry 14048 failed connections (enabled by `set tcp auto-retry on') and 14049 waiting for connections that are merely slow to complete, and 14050 represents an approximate cumulative value. 14051 14052`show tcp connect-timeout' 14053 Show the current connection timeout setting. 14054 14055 The GDB remote protocol autodetects the packets supported by your 14056debugging stub. If you need to override the autodetection, you can use 14057these commands to enable or disable individual packets. Each packet 14058can be set to `on' (the remote target supports this packet), `off' (the 14059remote target does not support this packet), or `auto' (detect remote 14060target support for this packet). They all default to `auto'. For more 14061information about each packet, see *note Remote Protocol::. 14062 14063 During normal use, you should not have to use any of these commands. 14064If you do, that may be a bug in your remote debugging stub, or a bug in 14065GDB. You may want to report the problem to the GDB developers. 14066 14067 For each packet NAME, the command to enable or disable the packet is 14068`set remote NAME-packet'. The available settings are: 14069 14070Command Name Remote Packet Related Features 14071`fetch-register' `p' `info registers' 14072`set-register' `P' `set' 14073`binary-download' `X' `load', `set' 14074`read-aux-vector' `qXfer:auxv:read' `info auxv' 14075`symbol-lookup' `qSymbol' Detecting 14076 multiple threads 14077`attach' `vAttach' `attach' 14078`verbose-resume' `vCont' Stepping or 14079 resuming multiple 14080 threads 14081`run' `vRun' `run' 14082`software-breakpoint'`Z0' `break' 14083`hardware-breakpoint'`Z1' `hbreak' 14084`write-watchpoint' `Z2' `watch' 14085`read-watchpoint' `Z3' `rwatch' 14086`access-watchpoint' `Z4' `awatch' 14087`target-features' `qXfer:features:read' `set architecture' 14088`library-info' `qXfer:libraries:read' `info 14089 sharedlibrary' 14090`memory-map' `qXfer:memory-map:read' `info mem' 14091`read-sdata-object' `qXfer:sdata:read' `print $_sdata' 14092`read-spu-object' `qXfer:spu:read' `info spu' 14093`write-spu-object' `qXfer:spu:write' `info spu' 14094`read-siginfo-object'`qXfer:siginfo:read' `print $_siginfo' 14095`write-siginfo-object'`qXfer:siginfo:write' `set $_siginfo' 14096`threads' `qXfer:threads:read' `info threads' 14097`get-thread-local- `qGetTLSAddr' Displaying 14098storage-address' `__thread' 14099 variables 14100`get-thread-information-block-address'`qGetTIBAddr' Display 14101 MS-Windows Thread 14102 Information Block. 14103`search-memory' `qSearch:memory' `find' 14104`supported-packets' `qSupported' Remote 14105 communications 14106 parameters 14107`pass-signals' `QPassSignals' `handle SIGNAL' 14108`hostio-close-packet'`vFile:close' `remote get', 14109 `remote put' 14110`hostio-open-packet' `vFile:open' `remote get', 14111 `remote put' 14112`hostio-pread-packet'`vFile:pread' `remote get', 14113 `remote put' 14114`hostio-pwrite-packet'`vFile:pwrite' `remote get', 14115 `remote put' 14116`hostio-unlink-packet'`vFile:unlink' `remote delete' 14117`noack-packet' `QStartNoAckMode' Packet 14118 acknowledgment 14119`osdata' `qXfer:osdata:read' `info os' 14120`query-attached' `qAttached' Querying remote 14121 process attach 14122 state. 14123 14124 14125File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging 14126 1412720.5 Implementing a Remote Stub 14128=============================== 14129 14130The stub files provided with GDB implement the target side of the 14131communication protocol, and the GDB side is implemented in the GDB 14132source file `remote.c'. Normally, you can simply allow these 14133subroutines to communicate, and ignore the details. (If you're 14134implementing your own stub file, you can still ignore the details: start 14135with one of the existing stub files. `sparc-stub.c' is the best 14136organized, and therefore the easiest to read.) 14137 14138 To debug a program running on another machine (the debugging 14139"target" machine), you must first arrange for all the usual 14140prerequisites for the program to run by itself. For example, for a C 14141program, you need: 14142 14143 1. A startup routine to set up the C runtime environment; these 14144 usually have a name like `crt0'. The startup routine may be 14145 supplied by your hardware supplier, or you may have to write your 14146 own. 14147 14148 2. A C subroutine library to support your program's subroutine calls, 14149 notably managing input and output. 14150 14151 3. A way of getting your program to the other machine--for example, a 14152 download program. These are often supplied by the hardware 14153 manufacturer, but you may have to write your own from hardware 14154 documentation. 14155 14156 The next step is to arrange for your program to use a serial port to 14157communicate with the machine where GDB is running (the "host" machine). 14158In general terms, the scheme looks like this: 14159 14160_On the host,_ 14161 GDB already understands how to use this protocol; when everything 14162 else is set up, you can simply use the `target remote' command 14163 (*note Specifying a Debugging Target: Targets.). 14164 14165_On the target,_ 14166 you must link with your program a few special-purpose subroutines 14167 that implement the GDB remote serial protocol. The file 14168 containing these subroutines is called a "debugging stub". 14169 14170 On certain remote targets, you can use an auxiliary program 14171 `gdbserver' instead of linking a stub into your program. *Note 14172 Using the `gdbserver' Program: Server, for details. 14173 14174 The debugging stub is specific to the architecture of the remote 14175machine; for example, use `sparc-stub.c' to debug programs on SPARC 14176boards. 14177 14178 These working remote stubs are distributed with GDB: 14179 14180`i386-stub.c' 14181 For Intel 386 and compatible architectures. 14182 14183`m68k-stub.c' 14184 For Motorola 680x0 architectures. 14185 14186`sh-stub.c' 14187 For Renesas SH architectures. 14188 14189`sparc-stub.c' 14190 For SPARC architectures. 14191 14192`sparcl-stub.c' 14193 For Fujitsu SPARCLITE architectures. 14194 14195 14196 The `README' file in the GDB distribution may list other recently 14197added stubs. 14198 14199* Menu: 14200 14201* Stub Contents:: What the stub can do for you 14202* Bootstrapping:: What you must do for the stub 14203* Debug Session:: Putting it all together 14204 14205 14206File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub 14207 1420820.5.1 What the Stub Can Do for You 14209----------------------------------- 14210 14211The debugging stub for your architecture supplies these three 14212subroutines: 14213 14214`set_debug_traps' 14215 This routine arranges for `handle_exception' to run when your 14216 program stops. You must call this subroutine explicitly near the 14217 beginning of your program. 14218 14219`handle_exception' 14220 This is the central workhorse, but your program never calls it 14221 explicitly--the setup code arranges for `handle_exception' to run 14222 when a trap is triggered. 14223 14224 `handle_exception' takes control when your program stops during 14225 execution (for example, on a breakpoint), and mediates 14226 communications with GDB on the host machine. This is where the 14227 communications protocol is implemented; `handle_exception' acts as 14228 the GDB representative on the target machine. It begins by 14229 sending summary information on the state of your program, then 14230 continues to execute, retrieving and transmitting any information 14231 GDB needs, until you execute a GDB command that makes your program 14232 resume; at that point, `handle_exception' returns control to your 14233 own code on the target machine. 14234 14235`breakpoint' 14236 Use this auxiliary subroutine to make your program contain a 14237 breakpoint. Depending on the particular situation, this may be 14238 the only way for GDB to get control. For instance, if your target 14239 machine has some sort of interrupt button, you won't need to call 14240 this; pressing the interrupt button transfers control to 14241 `handle_exception'--in effect, to GDB. On some machines, simply 14242 receiving characters on the serial port may also trigger a trap; 14243 again, in that situation, you don't need to call `breakpoint' from 14244 your own program--simply running `target remote' from the host GDB 14245 session gets control. 14246 14247 Call `breakpoint' if none of these is true, or if you simply want 14248 to make certain your program stops at a predetermined point for the 14249 start of your debugging session. 14250 14251 14252File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub 14253 1425420.5.2 What You Must Do for the Stub 14255------------------------------------ 14256 14257The debugging stubs that come with GDB are set up for a particular chip 14258architecture, but they have no information about the rest of your 14259debugging target machine. 14260 14261 First of all you need to tell the stub how to communicate with the 14262serial port. 14263 14264`int getDebugChar()' 14265 Write this subroutine to read a single character from the serial 14266 port. It may be identical to `getchar' for your target system; a 14267 different name is used to allow you to distinguish the two if you 14268 wish. 14269 14270`void putDebugChar(int)' 14271 Write this subroutine to write a single character to the serial 14272 port. It may be identical to `putchar' for your target system; a 14273 different name is used to allow you to distinguish the two if you 14274 wish. 14275 14276 If you want GDB to be able to stop your program while it is running, 14277you need to use an interrupt-driven serial driver, and arrange for it 14278to stop when it receives a `^C' (`\003', the control-C character). 14279That is the character which GDB uses to tell the remote system to stop. 14280 14281 Getting the debugging target to return the proper status to GDB 14282probably requires changes to the standard stub; one quick and dirty way 14283is to just execute a breakpoint instruction (the "dirty" part is that 14284GDB reports a `SIGTRAP' instead of a `SIGINT'). 14285 14286 Other routines you need to supply are: 14287 14288`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' 14289 Write this function to install EXCEPTION_ADDRESS in the exception 14290 handling tables. You need to do this because the stub does not 14291 have any way of knowing what the exception handling tables on your 14292 target system are like (for example, the processor's table might 14293 be in ROM, containing entries which point to a table in RAM). 14294 EXCEPTION_NUMBER is the exception number which should be changed; 14295 its meaning is architecture-dependent (for example, different 14296 numbers might represent divide by zero, misaligned access, etc). 14297 When this exception occurs, control should be transferred directly 14298 to EXCEPTION_ADDRESS, and the processor state (stack, registers, 14299 and so on) should be just as it is when a processor exception 14300 occurs. So if you want to use a jump instruction to reach 14301 EXCEPTION_ADDRESS, it should be a simple jump, not a jump to 14302 subroutine. 14303 14304 For the 386, EXCEPTION_ADDRESS should be installed as an interrupt 14305 gate so that interrupts are masked while the handler runs. The 14306 gate should be at privilege level 0 (the most privileged level). 14307 The SPARC and 68k stubs are able to mask interrupts themselves 14308 without help from `exceptionHandler'. 14309 14310`void flush_i_cache()' 14311 On SPARC and SPARCLITE only, write this subroutine to flush the 14312 instruction cache, if any, on your target machine. If there is no 14313 instruction cache, this subroutine may be a no-op. 14314 14315 On target machines that have instruction caches, GDB requires this 14316 function to make certain that the state of your program is stable. 14317 14318You must also make sure this library routine is available: 14319 14320`void *memset(void *, int, int)' 14321 This is the standard library function `memset' that sets an area of 14322 memory to a known value. If you have one of the free versions of 14323 `libc.a', `memset' can be found there; otherwise, you must either 14324 obtain it from your hardware manufacturer, or write your own. 14325 14326 If you do not use the GNU C compiler, you may need other standard 14327library subroutines as well; this varies from one stub to another, but 14328in general the stubs are likely to use any of the common library 14329subroutines which `GCC' generates as inline code. 14330 14331 14332File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub 14333 1433420.5.3 Putting it All Together 14335------------------------------ 14336 14337In summary, when your program is ready to debug, you must follow these 14338steps. 14339 14340 1. Make sure you have defined the supporting low-level routines 14341 (*note What You Must Do for the Stub: Bootstrapping.): 14342 `getDebugChar', `putDebugChar', 14343 `flush_i_cache', `memset', `exceptionHandler'. 14344 14345 2. Insert these lines near the top of your program: 14346 14347 set_debug_traps(); 14348 breakpoint(); 14349 14350 3. For the 680x0 stub only, you need to provide a variable called 14351 `exceptionHook'. Normally you just use: 14352 14353 void (*exceptionHook)() = 0; 14354 14355 but if before calling `set_debug_traps', you set it to point to a 14356 function in your program, that function is called when `GDB' 14357 continues after stopping on a trap (for example, bus error). The 14358 function indicated by `exceptionHook' is called with one 14359 parameter: an `int' which is the exception number. 14360 14361 4. Compile and link together: your program, the GDB debugging stub for 14362 your target architecture, and the supporting subroutines. 14363 14364 5. Make sure you have a serial connection between your target machine 14365 and the GDB host, and identify the serial port on the host. 14366 14367 6. Download your program to your target machine (or get it there by 14368 whatever means the manufacturer provides), and start it. 14369 14370 7. Start GDB on the host, and connect to the target (*note Connecting 14371 to a Remote Target: Connecting.). 14372 14373 14374 14375File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top 14376 1437721 Configuration-Specific Information 14378************************************* 14379 14380While nearly all GDB commands are available for all native and cross 14381versions of the debugger, there are some exceptions. This chapter 14382describes things that are only available in certain configurations. 14383 14384 There are three major categories of configurations: native 14385configurations, where the host and target are the same, embedded 14386operating system configurations, which are usually the same for several 14387different processor architectures, and bare embedded processors, which 14388are quite different from each other. 14389 14390* Menu: 14391 14392* Native:: 14393* Embedded OS:: 14394* Embedded Processors:: 14395* Architectures:: 14396 14397 14398File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations 14399 1440021.1 Native 14401=========== 14402 14403This section describes details specific to particular native 14404configurations. 14405 14406* Menu: 14407 14408* HP-UX:: HP-UX 14409* BSD libkvm Interface:: Debugging BSD kernel memory images 14410* SVR4 Process Information:: SVR4 process information 14411* DJGPP Native:: Features specific to the DJGPP port 14412* Cygwin Native:: Features specific to the Cygwin port 14413* Hurd Native:: Features specific to GNU Hurd 14414* Neutrino:: Features specific to QNX Neutrino 14415* Darwin:: Features specific to Darwin 14416 14417 14418File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native 14419 1442021.1.1 HP-UX 14421------------ 14422 14423On HP-UX systems, if you refer to a function or variable name that 14424begins with a dollar sign, GDB searches for a user or system name 14425first, before it searches for a convenience variable. 14426 14427 14428File: gdb.info, Node: BSD libkvm Interface, Next: SVR4 Process Information, Prev: HP-UX, Up: Native 14429 1443021.1.2 BSD libkvm Interface 14431--------------------------- 14432 14433BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory 14434interface that provides a uniform interface for accessing kernel virtual 14435memory images, including live systems and crash dumps. GDB uses this 14436interface to allow you to debug live kernels and kernel crash dumps on 14437many native BSD configurations. This is implemented as a special `kvm' 14438debugging target. For debugging a live system, load the currently 14439running kernel into GDB and connect to the `kvm' target: 14440 14441 (gdb) target kvm 14442 14443 For debugging crash dumps, provide the file name of the crash dump 14444as an argument: 14445 14446 (gdb) target kvm /var/crash/bsd.0 14447 14448 Once connected to the `kvm' target, the following commands are 14449available: 14450 14451`kvm pcb' 14452 Set current context from the "Process Control Block" (PCB) address. 14453 14454`kvm proc' 14455 Set current context from proc address. This command isn't 14456 available on modern FreeBSD systems. 14457 14458 14459File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native 14460 1446121.1.3 SVR4 Process Information 14462------------------------------- 14463 14464Many versions of SVR4 and compatible systems provide a facility called 14465`/proc' that can be used to examine the image of a running process 14466using file-system subroutines. If GDB is configured for an operating 14467system with this facility, the command `info proc' is available to 14468report information about the process running your program, or about any 14469process running on your system. `info proc' works only on SVR4 systems 14470that include the `procfs' code. This includes, as of this writing, 14471GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not 14472HP-UX, for example. 14473 14474`info proc' 14475`info proc PROCESS-ID' 14476 Summarize available information about any running process. If a 14477 process ID is specified by PROCESS-ID, display information about 14478 that process; otherwise display information about the program being 14479 debugged. The summary includes the debugged process ID, the 14480 command line used to invoke it, its current working directory, and 14481 its executable file's absolute file name. 14482 14483 On some systems, PROCESS-ID can be of the form `[PID]/TID' which 14484 specifies a certain thread ID within a process. If the optional 14485 PID part is missing, it means a thread from the process being 14486 debugged (the leading `/' still needs to be present, or else GDB 14487 will interpret the number as a process ID rather than a thread ID). 14488 14489`info proc mappings' 14490 Report the memory address space ranges accessible in the program, 14491 with information on whether the process has read, write, or 14492 execute access rights to each range. On GNU/Linux systems, each 14493 memory range includes the object file which is mapped to that 14494 range, instead of the memory access rights to that range. 14495 14496`info proc stat' 14497`info proc status' 14498 These subcommands are specific to GNU/Linux systems. They show 14499 the process-related information, including the user ID and group 14500 ID; how many threads are there in the process; its virtual memory 14501 usage; the signals that are pending, blocked, and ignored; its 14502 TTY; its consumption of system and user time; its stack size; its 14503 `nice' value; etc. For more information, see the `proc' man page 14504 (type `man 5 proc' from your shell prompt). 14505 14506`info proc all' 14507 Show all the information about the process described under all of 14508 the above `info proc' subcommands. 14509 14510`set procfs-trace' 14511 This command enables and disables tracing of `procfs' API calls. 14512 14513`show procfs-trace' 14514 Show the current state of `procfs' API call tracing. 14515 14516`set procfs-file FILE' 14517 Tell GDB to write `procfs' API trace to the named FILE. GDB 14518 appends the trace info to the previous contents of the file. The 14519 default is to display the trace on the standard output. 14520 14521`show procfs-file' 14522 Show the file to which `procfs' API trace is written. 14523 14524`proc-trace-entry' 14525`proc-trace-exit' 14526`proc-untrace-entry' 14527`proc-untrace-exit' 14528 These commands enable and disable tracing of entries into and exits 14529 from the `syscall' interface. 14530 14531`info pidlist' 14532 For QNX Neutrino only, this command displays the list of all the 14533 processes and all the threads within each process. 14534 14535`info meminfo' 14536 For QNX Neutrino only, this command displays the list of all 14537 mapinfos. 14538 14539 14540File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native 14541 1454221.1.4 Features for Debugging DJGPP Programs 14543-------------------------------------------- 14544 14545DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows. 14546DJGPP programs are 32-bit protected-mode programs that use the "DPMI" 14547(DOS Protected-Mode Interface) API to run on top of real-mode DOS 14548systems and their emulations. 14549 14550 GDB supports native debugging of DJGPP programs, and defines a few 14551commands specific to the DJGPP port. This subsection describes those 14552commands. 14553 14554`info dos' 14555 This is a prefix of DJGPP-specific commands which print 14556 information about the target system and important OS structures. 14557 14558`info dos sysinfo' 14559 This command displays assorted information about the underlying 14560 platform: the CPU type and features, the OS version and flavor, the 14561 DPMI version, and the available conventional and DPMI memory. 14562 14563`info dos gdt' 14564`info dos ldt' 14565`info dos idt' 14566 These 3 commands display entries from, respectively, Global, Local, 14567 and Interrupt Descriptor Tables (GDT, LDT, and IDT). The 14568 descriptor tables are data structures which store a descriptor for 14569 each segment that is currently in use. The segment's selector is 14570 an index into a descriptor table; the table entry for that index 14571 holds the descriptor's base address and limit, and its attributes 14572 and access rights. 14573 14574 A typical DJGPP program uses 3 segments: a code segment, a data 14575 segment (used for both data and the stack), and a DOS segment 14576 (which allows access to DOS/BIOS data structures and absolute 14577 addresses in conventional memory). However, the DPMI host will 14578 usually define additional segments in order to support the DPMI 14579 environment. 14580 14581 These commands allow to display entries from the descriptor tables. 14582 Without an argument, all entries from the specified table are 14583 displayed. An argument, which should be an integer expression, 14584 means display a single entry whose index is given by the argument. 14585 For example, here's a convenient way to display information about 14586 the debugged program's data segment: 14587 14588 `(gdb) info dos ldt $ds' 14589 `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)' 14590 14591 14592 This comes in handy when you want to see whether a pointer is 14593 outside the data segment's limit (i.e. "garbled"). 14594 14595`info dos pde' 14596`info dos pte' 14597 These two commands display entries from, respectively, the Page 14598 Directory and the Page Tables. Page Directories and Page Tables 14599 are data structures which control how virtual memory addresses are 14600 mapped into physical addresses. A Page Table includes an entry 14601 for every page of memory that is mapped into the program's address 14602 space; there may be several Page Tables, each one holding up to 14603 4096 entries. A Page Directory has up to 4096 entries, one each 14604 for every Page Table that is currently in use. 14605 14606 Without an argument, `info dos pde' displays the entire Page 14607 Directory, and `info dos pte' displays all the entries in all of 14608 the Page Tables. An argument, an integer expression, given to the 14609 `info dos pde' command means display only that entry from the Page 14610 Directory table. An argument given to the `info dos pte' command 14611 means display entries from a single Page Table, the one pointed to 14612 by the specified entry in the Page Directory. 14613 14614 These commands are useful when your program uses "DMA" (Direct 14615 Memory Access), which needs physical addresses to program the DMA 14616 controller. 14617 14618 These commands are supported only with some DPMI servers. 14619 14620`info dos address-pte ADDR' 14621 This command displays the Page Table entry for a specified linear 14622 address. The argument ADDR is a linear address which should 14623 already have the appropriate segment's base address added to it, 14624 because this command accepts addresses which may belong to _any_ 14625 segment. For example, here's how to display the Page Table entry 14626 for the page where a variable `i' is stored: 14627 14628 `(gdb) info dos address-pte __djgpp_base_address + (char *)&i' 14629 `Page Table entry for address 0x11a00d30:' 14630 `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30' 14631 14632 14633 This says that `i' is stored at offset `0xd30' from the page whose 14634 physical base address is `0x02698000', and shows all the 14635 attributes of that page. 14636 14637 Note that you must cast the addresses of variables to a `char *', 14638 since otherwise the value of `__djgpp_base_address', the base 14639 address of all variables and functions in a DJGPP program, will be 14640 added using the rules of C pointer arithmetics: if `i' is declared 14641 an `int', GDB will add 4 times the value of `__djgpp_base_address' 14642 to the address of `i'. 14643 14644 Here's another example, it displays the Page Table entry for the 14645 transfer buffer: 14646 14647 `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)' 14648 `Page Table entry for address 0x29110:' 14649 `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110' 14650 14651 14652 (The `+ 3' offset is because the transfer buffer's address is the 14653 3rd member of the `_go32_info_block' structure.) The output 14654 clearly shows that this DPMI server maps the addresses in 14655 conventional memory 1:1, i.e. the physical (`0x00029000' + 14656 `0x110') and linear (`0x29110') addresses are identical. 14657 14658 This command is supported only with some DPMI servers. 14659 14660 In addition to native debugging, the DJGPP port supports remote 14661debugging via a serial data link. The following commands are specific 14662to remote serial debugging in the DJGPP port of GDB. 14663 14664`set com1base ADDR' 14665 This command sets the base I/O port address of the `COM1' serial 14666 port. 14667 14668`set com1irq IRQ' 14669 This command sets the "Interrupt Request" (`IRQ') line to use for 14670 the `COM1' serial port. 14671 14672 There are similar commands `set com2base', `set com3irq', etc. for 14673 setting the port address and the `IRQ' lines for the other 3 COM 14674 ports. 14675 14676 The related commands `show com1base', `show com1irq' etc. display 14677 the current settings of the base address and the `IRQ' lines used 14678 by the COM ports. 14679 14680`info serial' 14681 This command prints the status of the 4 DOS serial ports. For each 14682 port, it prints whether it's active or not, its I/O base address 14683 and IRQ number, whether it uses a 16550-style FIFO, its baudrate, 14684 and the counts of various errors encountered so far. 14685 14686 14687File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native 14688 1468921.1.5 Features for Debugging MS Windows PE Executables 14690------------------------------------------------------- 14691 14692GDB supports native debugging of MS Windows programs, including DLLs 14693with and without symbolic debugging information. 14694 14695 MS-Windows programs that call `SetConsoleMode' to switch off the 14696special meaning of the `Ctrl-C' keystroke cannot be interrupted by 14697typing `C-c'. For this reason, GDB on MS-Windows supports `C-<BREAK>' 14698as an alternative interrupt key sequence, which can be used to 14699interrupt the debuggee even if it ignores `C-c'. 14700 14701 There are various additional Cygwin-specific commands, described in 14702this section. Working with DLLs that have no debugging symbols is 14703described in *note Non-debug DLL Symbols::. 14704 14705`info w32' 14706 This is a prefix of MS Windows-specific commands which print 14707 information about the target system and important OS structures. 14708 14709`info w32 selector' 14710 This command displays information returned by the Win32 API 14711 `GetThreadSelectorEntry' function. It takes an optional argument 14712 that is evaluated to a long value to give the information about 14713 this given selector. Without argument, this command displays 14714 information about the six segment registers. 14715 14716`info w32 thread-information-block' 14717 This command displays thread specific information stored in the 14718 Thread Information Block (readable on the X86 CPU family using 14719 `$fs' selector for 32-bit programs and `$gs' for 64-bit programs). 14720 14721`info dll' 14722 This is a Cygwin-specific alias of `info shared'. 14723 14724`dll-symbols' 14725 This command loads symbols from a dll similarly to add-sym command 14726 but without the need to specify a base address. 14727 14728`set cygwin-exceptions MODE' 14729 If MODE is `on', GDB will break on exceptions that happen inside 14730 the Cygwin DLL. If MODE is `off', GDB will delay recognition of 14731 exceptions, and may ignore some exceptions which seem to be caused 14732 by internal Cygwin DLL "bookkeeping". This option is meant 14733 primarily for debugging the Cygwin DLL itself; the default value 14734 is `off' to avoid annoying GDB users with false `SIGSEGV' signals. 14735 14736`show cygwin-exceptions' 14737 Displays whether GDB will break on exceptions that happen inside 14738 the Cygwin DLL itself. 14739 14740`set new-console MODE' 14741 If MODE is `on' the debuggee will be started in a new console on 14742 next start. If MODE is `off', the debuggee will be started in the 14743 same console as the debugger. 14744 14745`show new-console' 14746 Displays whether a new console is used when the debuggee is 14747 started. 14748 14749`set new-group MODE' 14750 This boolean value controls whether the debuggee should start a 14751 new group or stay in the same group as the debugger. This affects 14752 the way the Windows OS handles `Ctrl-C'. 14753 14754`show new-group' 14755 Displays current value of new-group boolean. 14756 14757`set debugevents' 14758 This boolean value adds debug output concerning kernel events 14759 related to the debuggee seen by the debugger. This includes 14760 events that signal thread and process creation and exit, DLL 14761 loading and unloading, console interrupts, and debugging messages 14762 produced by the Windows `OutputDebugString' API call. 14763 14764`set debugexec' 14765 This boolean value adds debug output concerning execute events 14766 (such as resume thread) seen by the debugger. 14767 14768`set debugexceptions' 14769 This boolean value adds debug output concerning exceptions in the 14770 debuggee seen by the debugger. 14771 14772`set debugmemory' 14773 This boolean value adds debug output concerning debuggee memory 14774 reads and writes by the debugger. 14775 14776`set shell' 14777 This boolean values specifies whether the debuggee is called via a 14778 shell or directly (default value is on). 14779 14780`show shell' 14781 Displays if the debuggee will be started with a shell. 14782 14783 14784* Menu: 14785 14786* Non-debug DLL Symbols:: Support for DLLs without debugging symbols 14787 14788 14789File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native 14790 1479121.1.5.1 Support for DLLs without Debugging Symbols 14792................................................... 14793 14794Very often on windows, some of the DLLs that your program relies on do 14795not include symbolic debugging information (for example, 14796`kernel32.dll'). When GDB doesn't recognize any debugging symbols in a 14797DLL, it relies on the minimal amount of symbolic information contained 14798in the DLL's export table. This section describes working with such 14799symbols, known internally to GDB as "minimal symbols". 14800 14801 Note that before the debugged program has started execution, no DLLs 14802will have been loaded. The easiest way around this problem is simply to 14803start the program -- either by setting a breakpoint or letting the 14804program run once to completion. It is also possible to force GDB to 14805load a particular DLL before starting the executable -- see the shared 14806library information in *note Files::, or the `dll-symbols' command in 14807*note Cygwin Native::. Currently, explicitly loading symbols from a 14808DLL with no debugging information will cause the symbol names to be 14809duplicated in GDB's lookup table, which may adversely affect symbol 14810lookup performance. 14811 1481221.1.5.2 DLL Name Prefixes 14813.......................... 14814 14815In keeping with the naming conventions used by the Microsoft debugging 14816tools, DLL export symbols are made available with a prefix based on the 14817DLL name, for instance `KERNEL32!CreateFileA'. The plain name is also 14818entered into the symbol table, so `CreateFileA' is often sufficient. 14819In some cases there will be name clashes within a program (particularly 14820if the executable itself includes full debugging symbols) necessitating 14821the use of the fully qualified name when referring to the contents of 14822the DLL. Use single-quotes around the name to avoid the exclamation 14823mark ("!") being interpreted as a language operator. 14824 14825 Note that the internal name of the DLL may be all upper-case, even 14826though the file name of the DLL is lower-case, or vice-versa. Since 14827symbols within GDB are _case-sensitive_ this may cause some confusion. 14828If in doubt, try the `info functions' and `info variables' commands or 14829even `maint print msymbols' (*note Symbols::). Here's an example: 14830 14831 (gdb) info function CreateFileA 14832 All functions matching regular expression "CreateFileA": 14833 14834 Non-debugging symbols: 14835 0x77e885f4 CreateFileA 14836 0x77e885f4 KERNEL32!CreateFileA 14837 14838 (gdb) info function ! 14839 All functions matching regular expression "!": 14840 14841 Non-debugging symbols: 14842 0x6100114c cygwin1!__assert 14843 0x61004034 cygwin1!_dll_crt0@0 14844 0x61004240 cygwin1!dll_crt0(per_process *) 14845 [etc...] 14846 1484721.1.5.3 Working with Minimal Symbols 14848..................................... 14849 14850Symbols extracted from a DLL's export table do not contain very much 14851type information. All that GDB can do is guess whether a symbol refers 14852to a function or variable depending on the linker section that contains 14853the symbol. Also note that the actual contents of the memory contained 14854in a DLL are not available unless the program is running. This means 14855that you cannot examine the contents of a variable or disassemble a 14856function within a DLL without a running program. 14857 14858 Variables are generally treated as pointers and dereferenced 14859automatically. For this reason, it is often necessary to prefix a 14860variable name with the address-of operator ("&") and provide explicit 14861type information in the command. Here's an example of the type of 14862problem: 14863 14864 (gdb) print 'cygwin1!__argv' 14865 $1 = 268572168 14866 14867 (gdb) x 'cygwin1!__argv' 14868 0x10021610: "\230y\"" 14869 14870 And two possible solutions: 14871 14872 (gdb) print ((char **)'cygwin1!__argv')[0] 14873 $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" 14874 14875 (gdb) x/2x &'cygwin1!__argv' 14876 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 14877 (gdb) x/x 0x10021608 14878 0x10021608: 0x0022fd98 14879 (gdb) x/s 0x0022fd98 14880 0x22fd98: "/cygdrive/c/mydirectory/myprogram" 14881 14882 Setting a break point within a DLL is possible even before the 14883program starts execution. However, under these circumstances, GDB can't 14884examine the initial instructions of the function in order to skip the 14885function's frame set-up code. You can work around this by using "*&" to 14886set the breakpoint at a raw memory address: 14887 14888 (gdb) break *&'python22!PyOS_Readline' 14889 Breakpoint 1 at 0x1e04eff0 14890 14891 The author of these extensions is not entirely convinced that 14892setting a break point within a shared DLL like `kernel32.dll' is 14893completely safe. 14894 14895 14896File: gdb.info, Node: Hurd Native, Next: Neutrino, Prev: Cygwin Native, Up: Native 14897 1489821.1.6 Commands Specific to GNU Hurd Systems 14899-------------------------------------------- 14900 14901This subsection describes GDB commands specific to the GNU Hurd native 14902debugging. 14903 14904`set signals' 14905`set sigs' 14906 This command toggles the state of inferior signal interception by 14907 GDB. Mach exceptions, such as breakpoint traps, are not affected 14908 by this command. `sigs' is a shorthand alias for `signals'. 14909 14910`show signals' 14911`show sigs' 14912 Show the current state of intercepting inferior's signals. 14913 14914`set signal-thread' 14915`set sigthread' 14916 This command tells GDB which thread is the `libc' signal thread. 14917 That thread is run when a signal is delivered to a running 14918 process. `set sigthread' is the shorthand alias of `set 14919 signal-thread'. 14920 14921`show signal-thread' 14922`show sigthread' 14923 These two commands show which thread will run when the inferior is 14924 delivered a signal. 14925 14926`set stopped' 14927 This commands tells GDB that the inferior process is stopped, as 14928 with the `SIGSTOP' signal. The stopped process can be continued 14929 by delivering a signal to it. 14930 14931`show stopped' 14932 This command shows whether GDB thinks the debuggee is stopped. 14933 14934`set exceptions' 14935 Use this command to turn off trapping of exceptions in the 14936 inferior. When exception trapping is off, neither breakpoints nor 14937 single-stepping will work. To restore the default, set exception 14938 trapping on. 14939 14940`show exceptions' 14941 Show the current state of trapping exceptions in the inferior. 14942 14943`set task pause' 14944 This command toggles task suspension when GDB has control. 14945 Setting it to on takes effect immediately, and the task is 14946 suspended whenever GDB gets control. Setting it to off will take 14947 effect the next time the inferior is continued. If this option is 14948 set to off, you can use `set thread default pause on' or `set 14949 thread pause on' (see below) to pause individual threads. 14950 14951`show task pause' 14952 Show the current state of task suspension. 14953 14954`set task detach-suspend-count' 14955 This command sets the suspend count the task will be left with when 14956 GDB detaches from it. 14957 14958`show task detach-suspend-count' 14959 Show the suspend count the task will be left with when detaching. 14960 14961`set task exception-port' 14962`set task excp' 14963 This command sets the task exception port to which GDB will 14964 forward exceptions. The argument should be the value of the "send 14965 rights" of the task. `set task excp' is a shorthand alias. 14966 14967`set noninvasive' 14968 This command switches GDB to a mode that is the least invasive as 14969 far as interfering with the inferior is concerned. This is the 14970 same as using `set task pause', `set exceptions', and `set 14971 signals' to values opposite to the defaults. 14972 14973`info send-rights' 14974`info receive-rights' 14975`info port-rights' 14976`info port-sets' 14977`info dead-names' 14978`info ports' 14979`info psets' 14980 These commands display information about, respectively, send 14981 rights, receive rights, port rights, port sets, and dead names of 14982 a task. There are also shorthand aliases: `info ports' for `info 14983 port-rights' and `info psets' for `info port-sets'. 14984 14985`set thread pause' 14986 This command toggles current thread suspension when GDB has 14987 control. Setting it to on takes effect immediately, and the 14988 current thread is suspended whenever GDB gets control. Setting it 14989 to off will take effect the next time the inferior is continued. 14990 Normally, this command has no effect, since when GDB has control, 14991 the whole task is suspended. However, if you used `set task pause 14992 off' (see above), this command comes in handy to suspend only the 14993 current thread. 14994 14995`show thread pause' 14996 This command shows the state of current thread suspension. 14997 14998`set thread run' 14999 This command sets whether the current thread is allowed to run. 15000 15001`show thread run' 15002 Show whether the current thread is allowed to run. 15003 15004`set thread detach-suspend-count' 15005 This command sets the suspend count GDB will leave on a thread 15006 when detaching. This number is relative to the suspend count 15007 found by GDB when it notices the thread; use `set thread 15008 takeover-suspend-count' to force it to an absolute value. 15009 15010`show thread detach-suspend-count' 15011 Show the suspend count GDB will leave on the thread when detaching. 15012 15013`set thread exception-port' 15014`set thread excp' 15015 Set the thread exception port to which to forward exceptions. This 15016 overrides the port set by `set task exception-port' (see above). 15017 `set thread excp' is the shorthand alias. 15018 15019`set thread takeover-suspend-count' 15020 Normally, GDB's thread suspend counts are relative to the value 15021 GDB finds when it notices each thread. This command changes the 15022 suspend counts to be absolute instead. 15023 15024`set thread default' 15025`show thread default' 15026 Each of the above `set thread' commands has a `set thread default' 15027 counterpart (e.g., `set thread default pause', `set thread default 15028 exception-port', etc.). The `thread default' variety of commands 15029 sets the default thread properties for all threads; you can then 15030 change the properties of individual threads with the non-default 15031 commands. 15032 15033 15034File: gdb.info, Node: Neutrino, Next: Darwin, Prev: Hurd Native, Up: Native 15035 1503621.1.7 QNX Neutrino 15037------------------- 15038 15039GDB provides the following commands specific to the QNX Neutrino target: 15040 15041`set debug nto-debug' 15042 When set to on, enables debugging messages specific to the QNX 15043 Neutrino support. 15044 15045`show debug nto-debug' 15046 Show the current state of QNX Neutrino messages. 15047 15048 15049File: gdb.info, Node: Darwin, Prev: Neutrino, Up: Native 15050 1505121.1.8 Darwin 15052------------- 15053 15054GDB provides the following commands specific to the Darwin target: 15055 15056`set debug darwin NUM' 15057 When set to a non zero value, enables debugging messages specific 15058 to the Darwin support. Higher values produce more verbose output. 15059 15060`show debug darwin' 15061 Show the current state of Darwin messages. 15062 15063`set debug mach-o NUM' 15064 When set to a non zero value, enables debugging messages while GDB 15065 is reading Darwin object files. ("Mach-O" is the file format used 15066 on Darwin for object and executable files.) Higher values produce 15067 more verbose output. This is a command to diagnose problems 15068 internal to GDB and should not be needed in normal usage. 15069 15070`show debug mach-o' 15071 Show the current state of Mach-O file messages. 15072 15073`set mach-exceptions on' 15074`set mach-exceptions off' 15075 On Darwin, faults are first reported as a Mach exception and are 15076 then mapped to a Posix signal. Use this command to turn on 15077 trapping of Mach exceptions in the inferior. This might be 15078 sometimes useful to better understand the cause of a fault. The 15079 default is off. 15080 15081`show mach-exceptions' 15082 Show the current state of exceptions trapping. 15083 15084 15085File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations 15086 1508721.2 Embedded Operating Systems 15088=============================== 15089 15090This section describes configurations involving the debugging of 15091embedded operating systems that are available for several different 15092architectures. 15093 15094* Menu: 15095 15096* VxWorks:: Using GDB with VxWorks 15097 15098 GDB includes the ability to debug programs running on various 15099real-time operating systems. 15100 15101 15102File: gdb.info, Node: VxWorks, Up: Embedded OS 15103 1510421.2.1 Using GDB with VxWorks 15105----------------------------- 15106 15107`target vxworks MACHINENAME' 15108 A VxWorks system, attached via TCP/IP. The argument MACHINENAME 15109 is the target system's machine name or IP address. 15110 15111 15112 On VxWorks, `load' links FILENAME dynamically on the current target 15113system as well as adding its symbols in GDB. 15114 15115 GDB enables developers to spawn and debug tasks running on networked 15116VxWorks targets from a Unix host. Already-running tasks spawned from 15117the VxWorks shell can also be debugged. GDB uses code that runs on 15118both the Unix host and on the VxWorks target. The program `gdb' is 15119installed and executed on the Unix host. (It may be installed with the 15120name `vxgdb', to distinguish it from a GDB for debugging programs on 15121the host itself.) 15122 15123`VxWorks-timeout ARGS' 15124 All VxWorks-based targets now support the option `vxworks-timeout'. 15125 This option is set by the user, and ARGS represents the number of 15126 seconds GDB waits for responses to rpc's. You might use this if 15127 your VxWorks target is a slow software simulator or is on the far 15128 side of a thin network line. 15129 15130 The following information on connecting to VxWorks was current when 15131this manual was produced; newer releases of VxWorks may use revised 15132procedures. 15133 15134 To use GDB with VxWorks, you must rebuild your VxWorks kernel to 15135include the remote debugging interface routines in the VxWorks library 15136`rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration 15137file `configAll.h' and rebuild your VxWorks kernel. The resulting 15138kernel contains `rdb.a', and spawns the source debugging task 15139`tRdbTask' when VxWorks is booted. For more information on configuring 15140and remaking VxWorks, see the manufacturer's manual. 15141 15142 Once you have included `rdb.a' in your VxWorks system image and set 15143your Unix execution search path to find GDB, you are ready to run GDB. 15144From your Unix host, run `gdb' (or `vxgdb', depending on your 15145installation). 15146 15147 GDB comes up showing the prompt: 15148 15149 (vxgdb) 15150 15151* Menu: 15152 15153* VxWorks Connection:: Connecting to VxWorks 15154* VxWorks Download:: VxWorks download 15155* VxWorks Attach:: Running tasks 15156 15157 15158File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks 15159 1516021.2.1.1 Connecting to VxWorks 15161.............................. 15162 15163The GDB command `target' lets you connect to a VxWorks target on the 15164network. To connect to a target whose host name is "`tt'", type: 15165 15166 (vxgdb) target vxworks tt 15167 15168 GDB displays messages like these: 15169 15170 Attaching remote machine across net... 15171 Connected to tt. 15172 15173 GDB then attempts to read the symbol tables of any object modules 15174loaded into the VxWorks target since it was last booted. GDB locates 15175these files by searching the directories listed in the command search 15176path (*note Your Program's Environment: Environment.); if it fails to 15177find an object file, it displays a message such as: 15178 15179 prog.o: No such file or directory. 15180 15181 When this happens, add the appropriate directory to the search path 15182with the GDB command `path', and execute the `target' command again. 15183 15184 15185File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks 15186 1518721.2.1.2 VxWorks Download 15188......................... 15189 15190If you have connected to the VxWorks target and you want to debug an 15191object that has not yet been loaded, you can use the GDB `load' command 15192to download a file from Unix to VxWorks incrementally. The object file 15193given as an argument to the `load' command is actually opened twice: 15194first by the VxWorks target in order to download the code, then by GDB 15195in order to read the symbol table. This can lead to problems if the 15196current working directories on the two systems differ. If both systems 15197have NFS mounted the same filesystems, you can avoid these problems by 15198using absolute paths. Otherwise, it is simplest to set the working 15199directory on both systems to the directory in which the object file 15200resides, and then to reference the file by its name, without any path. 15201For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in 15202VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this 15203program, type this on VxWorks: 15204 15205 -> cd "VXPATH/vw/demo/rdb" 15206 15207Then, in GDB, type: 15208 15209 (vxgdb) cd HOSTPATH/vw/demo/rdb 15210 (vxgdb) load prog.o 15211 15212 GDB displays a response similar to this: 15213 15214 Reading symbol data from wherever/vw/demo/rdb/prog.o... done. 15215 15216 You can also use the `load' command to reload an object module after 15217editing and recompiling the corresponding source file. Note that this 15218makes GDB delete all currently-defined breakpoints, auto-displays, and 15219convenience variables, and to clear the value history. (This is 15220necessary in order to preserve the integrity of debugger's data 15221structures that reference the target system's symbol table.) 15222 15223 15224File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks 15225 1522621.2.1.3 Running Tasks 15227...................... 15228 15229You can also attach to an existing task using the `attach' command as 15230follows: 15231 15232 (vxgdb) attach TASK 15233 15234where TASK is the VxWorks hexadecimal task ID. The task can be running 15235or suspended when you attach to it. Running tasks are suspended at the 15236time of attachment. 15237 15238 15239File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations 15240 1524121.3 Embedded Processors 15242======================== 15243 15244This section goes into details specific to particular embedded 15245configurations. 15246 15247 Whenever a specific embedded processor has a simulator, GDB allows 15248to send an arbitrary command to the simulator. 15249 15250`sim COMMAND' 15251 Send an arbitrary COMMAND string to the simulator. Consult the 15252 documentation for the specific simulator in use for information 15253 about acceptable commands. 15254 15255* Menu: 15256 15257* ARM:: ARM RDI 15258* M32R/D:: Renesas M32R/D 15259* M68K:: Motorola M68K 15260* MicroBlaze:: Xilinx MicroBlaze 15261* MIPS Embedded:: MIPS Embedded 15262* OpenRISC 1000:: OpenRisc 1000 15263* PA:: HP PA Embedded 15264* PowerPC Embedded:: PowerPC Embedded 15265* Sparclet:: Tsqware Sparclet 15266* Sparclite:: Fujitsu Sparclite 15267* Z8000:: Zilog Z8000 15268* AVR:: Atmel AVR 15269* CRIS:: CRIS 15270* Super-H:: Renesas Super-H 15271 15272 15273File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors 15274 1527521.3.1 ARM 15276---------- 15277 15278`target rdi DEV' 15279 ARM Angel monitor, via RDI library interface to ADP protocol. You 15280 may use this target to communicate with both boards running the 15281 Angel monitor, or with the EmbeddedICE JTAG debug device. 15282 15283`target rdp DEV' 15284 ARM Demon monitor. 15285 15286 15287 GDB provides the following ARM-specific commands: 15288 15289`set arm disassembler' 15290 This commands selects from a list of disassembly styles. The 15291 `"std"' style is the standard style. 15292 15293`show arm disassembler' 15294 Show the current disassembly style. 15295 15296`set arm apcs32' 15297 This command toggles ARM operation mode between 32-bit and 26-bit. 15298 15299`show arm apcs32' 15300 Display the current usage of the ARM 32-bit mode. 15301 15302`set arm fpu FPUTYPE' 15303 This command sets the ARM floating-point unit (FPU) type. The 15304 argument FPUTYPE can be one of these: 15305 15306 `auto' 15307 Determine the FPU type by querying the OS ABI. 15308 15309 `softfpa' 15310 Software FPU, with mixed-endian doubles on little-endian ARM 15311 processors. 15312 15313 `fpa' 15314 GCC-compiled FPA co-processor. 15315 15316 `softvfp' 15317 Software FPU with pure-endian doubles. 15318 15319 `vfp' 15320 VFP co-processor. 15321 15322`show arm fpu' 15323 Show the current type of the FPU. 15324 15325`set arm abi' 15326 This command forces GDB to use the specified ABI. 15327 15328`show arm abi' 15329 Show the currently used ABI. 15330 15331`set arm fallback-mode (arm|thumb|auto)' 15332 GDB uses the symbol table, when available, to determine whether 15333 instructions are ARM or Thumb. This command controls GDB's 15334 default behavior when the symbol table is not available. The 15335 default is `auto', which causes GDB to use the current execution 15336 mode (from the `T' bit in the `CPSR' register). 15337 15338`show arm fallback-mode' 15339 Show the current fallback instruction mode. 15340 15341`set arm force-mode (arm|thumb|auto)' 15342 This command overrides use of the symbol table to determine whether 15343 instructions are ARM or Thumb. The default is `auto', which 15344 causes GDB to use the symbol table and then the setting of `set 15345 arm fallback-mode'. 15346 15347`show arm force-mode' 15348 Show the current forced instruction mode. 15349 15350`set debug arm' 15351 Toggle whether to display ARM-specific debugging messages from the 15352 ARM target support subsystem. 15353 15354`show debug arm' 15355 Show whether ARM-specific debugging messages are enabled. 15356 15357 The following commands are available when an ARM target is debugged 15358using the RDI interface: 15359 15360`rdilogfile [FILE]' 15361 Set the filename for the ADP (Angel Debugger Protocol) packet log. 15362 With an argument, sets the log file to the specified FILE. With 15363 no argument, show the current log file name. The default log file 15364 is `rdi.log'. 15365 15366`rdilogenable [ARG]' 15367 Control logging of ADP packets. With an argument of 1 or `"yes"' 15368 enables logging, with an argument 0 or `"no"' disables it. With 15369 no arguments displays the current setting. When logging is 15370 enabled, ADP packets exchanged between GDB and the RDI target 15371 device are logged to a file. 15372 15373`set rdiromatzero' 15374 Tell GDB whether the target has ROM at address 0. If on, vector 15375 catching is disabled, so that zero address can be used. If off 15376 (the default), vector catching is enabled. For this command to 15377 take effect, it needs to be invoked prior to the `target rdi' 15378 command. 15379 15380`show rdiromatzero' 15381 Show the current setting of ROM at zero address. 15382 15383`set rdiheartbeat' 15384 Enable or disable RDI heartbeat packets. It is not recommended to 15385 turn on this option, since it confuses ARM and EPI JTAG interface, 15386 as well as the Angel monitor. 15387 15388`show rdiheartbeat' 15389 Show the setting of RDI heartbeat packets. 15390 15391`target sim [SIMARGS] ...' 15392 The GDB ARM simulator accepts the following optional arguments. 15393 15394 `--swi-support=TYPE' 15395 Tell the simulator which SWI interfaces to support. TYPE may 15396 be a comma separated list of the following values. The 15397 default value is `all'. 15398 15399 `none' 15400 15401 `demon' 15402 15403 `angel' 15404 15405 `redboot' 15406 15407 `all' 15408 15409 15410File: gdb.info, Node: M32R/D, Next: M68K, Prev: ARM, Up: Embedded Processors 15411 1541221.3.2 Renesas M32R/D and M32R/SDI 15413---------------------------------- 15414 15415`target m32r DEV' 15416 Renesas M32R/D ROM monitor. 15417 15418`target m32rsdi DEV' 15419 Renesas M32R SDI server, connected via parallel port to the board. 15420 15421 The following GDB commands are specific to the M32R monitor: 15422 15423`set download-path PATH' 15424 Set the default path for finding downloadable SREC files. 15425 15426`show download-path' 15427 Show the default path for downloadable SREC files. 15428 15429`set board-address ADDR' 15430 Set the IP address for the M32R-EVA target board. 15431 15432`show board-address' 15433 Show the current IP address of the target board. 15434 15435`set server-address ADDR' 15436 Set the IP address for the download server, which is the GDB's 15437 host machine. 15438 15439`show server-address' 15440 Display the IP address of the download server. 15441 15442`upload [FILE]' 15443 Upload the specified SREC FILE via the monitor's Ethernet upload 15444 capability. If no FILE argument is given, the current executable 15445 file is uploaded. 15446 15447`tload [FILE]' 15448 Test the `upload' command. 15449 15450 The following commands are available for M32R/SDI: 15451 15452`sdireset' 15453 This command resets the SDI connection. 15454 15455`sdistatus' 15456 This command shows the SDI connection status. 15457 15458`debug_chaos' 15459 Instructs the remote that M32R/Chaos debugging is to be used. 15460 15461`use_debug_dma' 15462 Instructs the remote to use the DEBUG_DMA method of accessing 15463 memory. 15464 15465`use_mon_code' 15466 Instructs the remote to use the MON_CODE method of accessing 15467 memory. 15468 15469`use_ib_break' 15470 Instructs the remote to set breakpoints by IB break. 15471 15472`use_dbt_break' 15473 Instructs the remote to set breakpoints by DBT. 15474 15475 15476File: gdb.info, Node: M68K, Next: MicroBlaze, Prev: M32R/D, Up: Embedded Processors 15477 1547821.3.3 M68k 15479----------- 15480 15481The Motorola m68k configuration includes ColdFire support, and a target 15482command for the following ROM monitor. 15483 15484`target dbug DEV' 15485 dBUG ROM monitor for Motorola ColdFire. 15486 15487 15488 15489File: gdb.info, Node: MicroBlaze, Next: MIPS Embedded, Prev: M68K, Up: Embedded Processors 15490 1549121.3.4 MicroBlaze 15492----------------- 15493 15494The MicroBlaze is a soft-core processor supported on various Xilinx 15495FPGAs, such as Spartan or Virtex series. Boards with these processors 15496usually have JTAG ports which connect to a host system running the 15497Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK). 15498This host system is used to download the configuration bitstream to the 15499target FPGA. The Xilinx Microprocessor Debugger (XMD) program 15500communicates with the target board using the JTAG interface and 15501presents a `gdbserver' interface to the board. By default `xmd' uses 15502port `1234'. (While it is possible to change this default port, it 15503requires the use of undocumented `xmd' commands. Contact Xilinx 15504support if you need to do this.) 15505 15506 Use these GDB commands to connect to the MicroBlaze target processor. 15507 15508`target remote :1234' 15509 Use this command to connect to the target if you are running GDB 15510 on the same system as `xmd'. 15511 15512`target remote XMD-HOST:1234' 15513 Use this command to connect to the target if it is connected to 15514 `xmd' running on a different system named XMD-HOST. 15515 15516`load' 15517 Use this command to download a program to the MicroBlaze target. 15518 15519`set debug microblaze N' 15520 Enable MicroBlaze-specific debugging messages if non-zero. 15521 15522`show debug microblaze N' 15523 Show MicroBlaze-specific debugging level. 15524 15525 15526File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze, Up: Embedded Processors 15527 1552821.3.5 MIPS Embedded 15529-------------------- 15530 15531GDB can use the MIPS remote debugging protocol to talk to a MIPS board 15532attached to a serial line. This is available when you configure GDB 15533with `--target=mips-idt-ecoff'. 15534 15535 Use these GDB commands to specify the connection to your target 15536board: 15537 15538`target mips PORT' 15539 To run a program on the board, start up `gdb' with the name of 15540 your program as the argument. To connect to the board, use the 15541 command `target mips PORT', where PORT is the name of the serial 15542 port connected to the board. If the program has not already been 15543 downloaded to the board, you may use the `load' command to 15544 download it. You can then use all the usual GDB commands. 15545 15546 For example, this sequence connects to the target board through a 15547 serial port, and loads and runs a program called PROG through the 15548 debugger: 15549 15550 host$ gdb PROG 15551 GDB is free software and ... 15552 (gdb) target mips /dev/ttyb 15553 (gdb) load PROG 15554 (gdb) run 15555 15556`target mips HOSTNAME:PORTNUMBER' 15557 On some GDB host configurations, you can specify a TCP connection 15558 (for instance, to a serial line managed by a terminal 15559 concentrator) instead of a serial port, using the syntax 15560 `HOSTNAME:PORTNUMBER'. 15561 15562`target pmon PORT' 15563 PMON ROM monitor. 15564 15565`target ddb PORT' 15566 NEC's DDB variant of PMON for Vr4300. 15567 15568`target lsi PORT' 15569 LSI variant of PMON. 15570 15571`target r3900 DEV' 15572 Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. 15573 15574`target array DEV' 15575 Array Tech LSI33K RAID controller board. 15576 15577 15578GDB also supports these special commands for MIPS targets: 15579 15580`set mipsfpu double' 15581`set mipsfpu single' 15582`set mipsfpu none' 15583`set mipsfpu auto' 15584`show mipsfpu' 15585 If your target board does not support the MIPS floating point 15586 coprocessor, you should use the command `set mipsfpu none' (if you 15587 need this, you may wish to put the command in your GDB init file). 15588 This tells GDB how to find the return value of functions which 15589 return floating point values. It also allows GDB to avoid saving 15590 the floating point registers when calling functions on the board. 15591 If you are using a floating point coprocessor with only single 15592 precision floating point support, as on the R4650 processor, use 15593 the command `set mipsfpu single'. The default double precision 15594 floating point coprocessor may be selected using `set mipsfpu 15595 double'. 15596 15597 In previous versions the only choices were double precision or no 15598 floating point, so `set mipsfpu on' will select double precision 15599 and `set mipsfpu off' will select no floating point. 15600 15601 As usual, you can inquire about the `mipsfpu' variable with `show 15602 mipsfpu'. 15603 15604`set timeout SECONDS' 15605`set retransmit-timeout SECONDS' 15606`show timeout' 15607`show retransmit-timeout' 15608 You can control the timeout used while waiting for a packet, in 15609 the MIPS remote protocol, with the `set timeout SECONDS' command. 15610 The default is 5 seconds. Similarly, you can control the timeout 15611 used while waiting for an acknowledgment of a packet with the `set 15612 retransmit-timeout SECONDS' command. The default is 3 seconds. 15613 You can inspect both values with `show timeout' and `show 15614 retransmit-timeout'. (These commands are _only_ available when 15615 GDB is configured for `--target=mips-idt-ecoff'.) 15616 15617 The timeout set by `set timeout' does not apply when GDB is 15618 waiting for your program to stop. In that case, GDB waits forever 15619 because it has no way of knowing how long the program is going to 15620 run before stopping. 15621 15622`set syn-garbage-limit NUM' 15623 Limit the maximum number of characters GDB should ignore when it 15624 tries to synchronize with the remote target. The default is 10 15625 characters. Setting the limit to -1 means there's no limit. 15626 15627`show syn-garbage-limit' 15628 Show the current limit on the number of characters to ignore when 15629 trying to synchronize with the remote system. 15630 15631`set monitor-prompt PROMPT' 15632 Tell GDB to expect the specified PROMPT string from the remote 15633 monitor. The default depends on the target: 15634 pmon target 15635 `PMON' 15636 15637 ddb target 15638 `NEC010' 15639 15640 lsi target 15641 `PMON>' 15642 15643`show monitor-prompt' 15644 Show the current strings GDB expects as the prompt from the remote 15645 monitor. 15646 15647`set monitor-warnings' 15648 Enable or disable monitor warnings about hardware breakpoints. 15649 This has effect only for the `lsi' target. When on, GDB will 15650 display warning messages whose codes are returned by the `lsi' 15651 PMON monitor for breakpoint commands. 15652 15653`show monitor-warnings' 15654 Show the current setting of printing monitor warnings. 15655 15656`pmon COMMAND' 15657 This command allows sending an arbitrary COMMAND string to the 15658 monitor. The monitor must be in debug mode for this to work. 15659 15660 15661File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors 15662 1566321.3.6 OpenRISC 1000 15664-------------------- 15665 15666See OR1k Architecture document (`www.opencores.org') for more 15667information about platform and commands. 15668 15669`target jtag jtag://HOST:PORT' 15670 Connects to remote JTAG server. JTAG remote server can be either 15671 an or1ksim or JTAG server, connected via parallel port to the 15672 board. 15673 15674 Example: `target jtag jtag://localhost:9999' 15675 15676`or1ksim COMMAND' 15677 If connected to `or1ksim' OpenRISC 1000 Architectural Simulator, 15678 proprietary commands can be executed. 15679 15680`info or1k spr' 15681 Displays spr groups. 15682 15683`info or1k spr GROUP' 15684`info or1k spr GROUPNO' 15685 Displays register names in selected group. 15686 15687`info or1k spr GROUP REGISTER' 15688`info or1k spr REGISTER' 15689`info or1k spr GROUPNO REGISTERNO' 15690`info or1k spr REGISTERNO' 15691 Shows information about specified spr register. 15692 15693`spr GROUP REGISTER VALUE' 15694`spr REGISTER VALUE' 15695`spr GROUPNO REGISTERNO VALUE' 15696`spr REGISTERNO VALUE' 15697 Writes VALUE to specified spr register. 15698 15699 Some implementations of OpenRISC 1000 Architecture also have 15700hardware trace. It is very similar to GDB trace, except it does not 15701interfere with normal program execution and is thus much faster. 15702Hardware breakpoints/watchpoint triggers can be set using: 15703`$LEA/$LDATA' 15704 Load effective address/data 15705 15706`$SEA/$SDATA' 15707 Store effective address/data 15708 15709`$AEA/$ADATA' 15710 Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) 15711 15712`$FETCH' 15713 Fetch data 15714 15715 When triggered, it can capture low level data, like: `PC', `LSEA', 15716`LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'. 15717 15718 `htrace' commands: 15719`hwatch CONDITIONAL' 15720 Set hardware watchpoint on combination of Load/Store Effective 15721 Address(es) or Data. For example: 15722 15723 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && 15724 ($SDATA >= 50)' 15725 15726 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && 15727 ($SDATA >= 50)' 15728 15729`htrace info' 15730 Display information about current HW trace configuration. 15731 15732`htrace trigger CONDITIONAL' 15733 Set starting criteria for HW trace. 15734 15735`htrace qualifier CONDITIONAL' 15736 Set acquisition qualifier for HW trace. 15737 15738`htrace stop CONDITIONAL' 15739 Set HW trace stopping criteria. 15740 15741`htrace record [DATA]*' 15742 Selects the data to be recorded, when qualifier is met and HW 15743 trace was triggered. 15744 15745`htrace enable' 15746`htrace disable' 15747 Enables/disables the HW trace. 15748 15749`htrace rewind [FILENAME]' 15750 Clears currently recorded trace data. 15751 15752 If filename is specified, new trace file is made and any newly 15753 collected data will be written there. 15754 15755`htrace print [START [LEN]]' 15756 Prints trace buffer, using current record configuration. 15757 15758`htrace mode continuous' 15759 Set continuous trace mode. 15760 15761`htrace mode suspend' 15762 Set suspend trace mode. 15763 15764 15765 15766File: gdb.info, Node: PowerPC Embedded, Next: Sparclet, Prev: PA, Up: Embedded Processors 15767 1576821.3.7 PowerPC Embedded 15769----------------------- 15770 15771GDB supports using the DVC (Data Value Compare) register to implement 15772in hardware simple hardware watchpoint conditions of the form: 15773 15774 (gdb) watch ADDRESS|VARIABLE \ 15775 if ADDRESS|VARIABLE == CONSTANT EXPRESSION 15776 15777 The DVC register will be automatically used whenever GDB detects 15778such pattern in a condition expression. This feature is available in 15779native GDB running on a Linux kernel version 2.6.34 or newer. 15780 15781 GDB provides the following PowerPC-specific commands: 15782 15783`set powerpc soft-float' 15784`show powerpc soft-float' 15785 Force GDB to use (or not use) a software floating point calling 15786 convention. By default, GDB selects the calling convention based 15787 on the selected architecture and the provided executable file. 15788 15789`set powerpc vector-abi' 15790`show powerpc vector-abi' 15791 Force GDB to use the specified calling convention for vector 15792 arguments and return values. The valid options are `auto'; 15793 `generic', to avoid vector registers even if they are present; 15794 `altivec', to use AltiVec registers; and `spe' to use SPE 15795 registers. By default, GDB selects the calling convention based 15796 on the selected architecture and the provided executable file. 15797 15798`target dink32 DEV' 15799 DINK32 ROM monitor. 15800 15801`target ppcbug DEV' 15802 15803`target ppcbug1 DEV' 15804 PPCBUG ROM monitor for PowerPC. 15805 15806`target sds DEV' 15807 SDS monitor, running on a PowerPC board (such as Motorola's ADS). 15808 15809 The following commands specific to the SDS protocol are supported by 15810GDB: 15811 15812`set sdstimeout NSEC' 15813 Set the timeout for SDS protocol reads to be NSEC seconds. The 15814 default is 2 seconds. 15815 15816`show sdstimeout' 15817 Show the current value of the SDS timeout. 15818 15819`sds COMMAND' 15820 Send the specified COMMAND string to the SDS monitor. 15821 15822 15823File: gdb.info, Node: PA, Next: PowerPC Embedded, Prev: OpenRISC 1000, Up: Embedded Processors 15824 1582521.3.8 HP PA Embedded 15826--------------------- 15827 15828`target op50n DEV' 15829 OP50N monitor, running on an OKI HPPA board. 15830 15831`target w89k DEV' 15832 W89K monitor, running on a Winbond HPPA board. 15833 15834 15835 15836File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PowerPC Embedded, Up: Embedded Processors 15837 1583821.3.9 Tsqware Sparclet 15839----------------------- 15840 15841GDB enables developers to debug tasks running on Sparclet targets from 15842a Unix host. GDB uses code that runs on both the Unix host and on the 15843Sparclet target. The program `gdb' is installed and executed on the 15844Unix host. 15845 15846`remotetimeout ARGS' 15847 GDB supports the option `remotetimeout'. This option is set by 15848 the user, and ARGS represents the number of seconds GDB waits for 15849 responses. 15850 15851 When compiling for debugging, include the options `-g' to get debug 15852information and `-Ttext' to relocate the program to where you wish to 15853load it on the target. You may also want to add the options `-n' or 15854`-N' in order to reduce the size of the sections. Example: 15855 15856 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N 15857 15858 You can use `objdump' to verify that the addresses are what you 15859intended: 15860 15861 sparclet-aout-objdump --headers --syms prog 15862 15863 Once you have set your Unix execution search path to find GDB, you 15864are ready to run GDB. From your Unix host, run `gdb' (or 15865`sparclet-aout-gdb', depending on your installation). 15866 15867 GDB comes up showing the prompt: 15868 15869 (gdbslet) 15870 15871* Menu: 15872 15873* Sparclet File:: Setting the file to debug 15874* Sparclet Connection:: Connecting to Sparclet 15875* Sparclet Download:: Sparclet download 15876* Sparclet Execution:: Running and debugging 15877 15878 15879File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet 15880 1588121.3.9.1 Setting File to Debug 15882.............................. 15883 15884The GDB command `file' lets you choose with program to debug. 15885 15886 (gdbslet) file prog 15887 15888 GDB then attempts to read the symbol table of `prog'. GDB locates 15889the file by searching the directories listed in the command search path. 15890If the file was compiled with debug information (option `-g'), source 15891files will be searched as well. GDB locates the source files by 15892searching the directories listed in the directory search path (*note 15893Your Program's Environment: Environment.). If it fails to find a file, 15894it displays a message such as: 15895 15896 prog: No such file or directory. 15897 15898 When this happens, add the appropriate directories to the search 15899paths with the GDB commands `path' and `dir', and execute the `target' 15900command again. 15901 15902 15903File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet 15904 1590521.3.9.2 Connecting to Sparclet 15906............................... 15907 15908The GDB command `target' lets you connect to a Sparclet target. To 15909connect to a target on serial port "`ttya'", type: 15910 15911 (gdbslet) target sparclet /dev/ttya 15912 Remote target sparclet connected to /dev/ttya 15913 main () at ../prog.c:3 15914 15915 GDB displays messages like these: 15916 15917 Connected to ttya. 15918 15919 15920File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet 15921 1592221.3.9.3 Sparclet Download 15923.......................... 15924 15925Once connected to the Sparclet target, you can use the GDB `load' 15926command to download the file from the host to the target. The file 15927name and load offset should be given as arguments to the `load' command. 15928Since the file format is aout, the program must be loaded to the 15929starting address. You can use `objdump' to find out what this value 15930is. The load offset is an offset which is added to the VMA (virtual 15931memory address) of each of the file's sections. For instance, if the 15932program `prog' was linked to text address 0x1201000, with data at 159330x12010160 and bss at 0x12010170, in GDB, type: 15934 15935 (gdbslet) load prog 0x12010000 15936 Loading section .text, size 0xdb0 vma 0x12010000 15937 15938 If the code is loaded at a different address then what the program 15939was linked to, you may need to use the `section' and `add-symbol-file' 15940commands to tell GDB where to map the symbol table. 15941 15942 15943File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet 15944 1594521.3.9.4 Running and Debugging 15946.............................. 15947 15948You can now begin debugging the task using GDB's execution control 15949commands, `b', `step', `run', etc. See the GDB manual for the list of 15950commands. 15951 15952 (gdbslet) b main 15953 Breakpoint 1 at 0x12010000: file prog.c, line 3. 15954 (gdbslet) run 15955 Starting program: prog 15956 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 15957 3 char *symarg = 0; 15958 (gdbslet) step 15959 4 char *execarg = "hello!"; 15960 (gdbslet) 15961 15962 15963File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded Processors 15964 1596521.3.10 Fujitsu Sparclite 15966------------------------- 15967 15968`target sparclite DEV' 15969 Fujitsu sparclite boards, used only for the purpose of loading. 15970 You must use an additional command to debug the program. For 15971 example: target remote DEV using GDB standard remote protocol. 15972 15973 15974 15975File: gdb.info, Node: Z8000, Next: AVR, Prev: Sparclite, Up: Embedded Processors 15976 1597721.3.11 Zilog Z8000 15978------------------- 15979 15980When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 15981simulator. 15982 15983 For the Z8000 family, `target sim' simulates either the Z8002 (the 15984unsegmented variant of the Z8000 architecture) or the Z8001 (the 15985segmented variant). The simulator recognizes which architecture is 15986appropriate by inspecting the object code. 15987 15988`target sim ARGS' 15989 Debug programs on a simulated CPU. If the simulator supports setup 15990 options, specify them via ARGS. 15991 15992After specifying this target, you can debug programs for the simulated 15993CPU in the same style as programs for your host computer; use the 15994`file' command to load a new program image, the `run' command to run 15995your program, and so on. 15996 15997 As well as making available all the usual machine registers (*note 15998Registers: Registers.), the Z8000 simulator provides three additional 15999items of information as specially named registers: 16000 16001`cycles' 16002 Counts clock-ticks in the simulator. 16003 16004`insts' 16005 Counts instructions run in the simulator. 16006 16007`time' 16008 Execution time in 60ths of a second. 16009 16010 16011 You can refer to these values in GDB expressions with the usual 16012conventions; for example, `b fputc if $cycles>5000' sets a conditional 16013breakpoint that suspends only after at least 5000 simulated clock ticks. 16014 16015 16016File: gdb.info, Node: AVR, Next: CRIS, Prev: Z8000, Up: Embedded Processors 16017 1601821.3.12 Atmel AVR 16019----------------- 16020 16021When configured for debugging the Atmel AVR, GDB supports the following 16022AVR-specific commands: 16023 16024`info io_registers' 16025 This command displays information about the AVR I/O registers. For 16026 each register, GDB prints its number and value. 16027 16028 16029File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors 16030 1603121.3.13 CRIS 16032------------ 16033 16034When configured for debugging CRIS, GDB provides the following 16035CRIS-specific commands: 16036 16037`set cris-version VER' 16038 Set the current CRIS version to VER, either `10' or `32'. The 16039 CRIS version affects register names and sizes. This command is 16040 useful in case autodetection of the CRIS version fails. 16041 16042`show cris-version' 16043 Show the current CRIS version. 16044 16045`set cris-dwarf2-cfi' 16046 Set the usage of DWARF-2 CFI for CRIS debugging. The default is 16047 `on'. Change to `off' when using `gcc-cris' whose version is below 16048 `R59'. 16049 16050`show cris-dwarf2-cfi' 16051 Show the current state of using DWARF-2 CFI. 16052 16053`set cris-mode MODE' 16054 Set the current CRIS mode to MODE. It should only be changed when 16055 debugging in guru mode, in which case it should be set to `guru' 16056 (the default is `normal'). 16057 16058`show cris-mode' 16059 Show the current CRIS mode. 16060 16061 16062File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors 16063 1606421.3.14 Renesas Super-H 16065----------------------- 16066 16067For the Renesas Super-H processor, GDB provides these commands: 16068 16069`regs' 16070 Show the values of all Super-H registers. 16071 16072`set sh calling-convention CONVENTION' 16073 Set the calling-convention used when calling functions from GDB. 16074 Allowed values are `gcc', which is the default setting, and 16075 `renesas'. With the `gcc' setting, functions are called using the 16076 GCC calling convention. If the DWARF-2 information of the called 16077 function specifies that the function follows the Renesas calling 16078 convention, the function is called using the Renesas calling 16079 convention. If the calling convention is set to `renesas', the 16080 Renesas calling convention is always used, regardless of the 16081 DWARF-2 information. This can be used to override the default of 16082 `gcc' if debug information is missing, or the compiler does not 16083 emit the DWARF-2 calling convention entry for a function. 16084 16085`show sh calling-convention' 16086 Show the current calling convention setting. 16087 16088 16089 16090File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations 16091 1609221.4 Architectures 16093================== 16094 16095This section describes characteristics of architectures that affect all 16096uses of GDB with the architecture, both native and cross. 16097 16098* Menu: 16099 16100* i386:: 16101* A29K:: 16102* Alpha:: 16103* MIPS:: 16104* HPPA:: HP PA architecture 16105* SPU:: Cell Broadband Engine SPU architecture 16106* PowerPC:: 16107 16108 16109File: gdb.info, Node: i386, Next: A29K, Up: Architectures 16110 1611121.4.1 x86 Architecture-specific Issues 16112--------------------------------------- 16113 16114`set struct-convention MODE' 16115 Set the convention used by the inferior to return `struct's and 16116 `union's from functions to MODE. Possible values of MODE are 16117 `"pcc"', `"reg"', and `"default"' (the default). `"default"' or 16118 `"pcc"' means that `struct's are returned on the stack, while 16119 `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4, 16120 or 8 bytes will be returned in a register. 16121 16122`show struct-convention' 16123 Show the current setting of the convention to return `struct's 16124 from functions. 16125 16126 16127File: gdb.info, Node: A29K, Next: Alpha, Prev: i386, Up: Architectures 16128 1612921.4.2 A29K 16130----------- 16131 16132`set rstack_high_address ADDRESS' 16133 On AMD 29000 family processors, registers are saved in a separate 16134 "register stack". There is no way for GDB to determine the extent 16135 of this stack. Normally, GDB just assumes that the stack is 16136 "large enough". This may result in GDB referencing memory 16137 locations that do not exist. If necessary, you can get around 16138 this problem by specifying the ending address of the register 16139 stack with the `set rstack_high_address' command. The argument 16140 should be an address, which you probably want to precede with `0x' 16141 to specify in hexadecimal. 16142 16143`show rstack_high_address' 16144 Display the current limit of the register stack, on AMD 29000 16145 family processors. 16146 16147 16148 16149File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures 16150 1615121.4.3 Alpha 16152------------ 16153 16154See the following section. 16155 16156 16157File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures 16158 1615921.4.4 MIPS 16160----------- 16161 16162Alpha- and MIPS-based computers use an unusual stack frame, which 16163sometimes requires GDB to search backward in the object code to find 16164the beginning of a function. 16165 16166 To improve response time (especially for embedded applications, where 16167GDB may be restricted to a slow serial line for this search) you may 16168want to limit the size of this search, using one of these commands: 16169 16170`set heuristic-fence-post LIMIT' 16171 Restrict GDB to examining at most LIMIT bytes in its search for 16172 the beginning of a function. A value of 0 (the default) means 16173 there is no limit. However, except for 0, the larger the limit 16174 the more bytes `heuristic-fence-post' must search and therefore 16175 the longer it takes to run. You should only need to use this 16176 command when debugging a stripped executable. 16177 16178`show heuristic-fence-post' 16179 Display the current limit. 16180 16181These commands are available _only_ when GDB is configured for 16182debugging programs on Alpha or MIPS processors. 16183 16184 Several MIPS-specific commands are available when debugging MIPS 16185programs: 16186 16187`set mips abi ARG' 16188 Tell GDB which MIPS ABI is used by the inferior. Possible values 16189 of ARG are: 16190 16191 `auto' 16192 The default ABI associated with the current binary (this is 16193 the default). 16194 16195 `o32' 16196 16197 `o64' 16198 16199 `n32' 16200 16201 `n64' 16202 16203 `eabi32' 16204 16205 `eabi64' 16206 16207`show mips abi' 16208 Show the MIPS ABI used by GDB to debug the inferior. 16209 16210`set mips compression ARG' 16211 Tell GDB which MIPS compressed ISA encoding is used by the 16212 inferior. GDB uses this for code disassembly and other internal 16213 interpretation purposes. This setting is only referred to when no 16214 executable has been associated with the debugging session or the 16215 executable does not provide information about the encoding it uses. 16216 Otherwise this setting is automatically updated from information 16217 provided by the executable. 16218 16219 Possible values of ARG are `mips16' and `micromips'. The default 16220 compressed ISA encoding is `mips16', as executables containing 16221 MIPS16 code frequently are not identified as such. 16222 16223 This setting is "sticky"; that is, it retains its value across 16224 debugging sessions until reset either explicitly with this command 16225 or implicitly from an executable. 16226 16227 The compiler and/or assembler typically add symbol table 16228 annotations to identify functions compiled for the MIPS16 or 16229 microMIPS ISAs. If these function-scope annotations are present, 16230 GDB uses them in preference to the global compressed ISA encoding 16231 setting. 16232 16233`show mips compression' 16234 Show the MIPS compressed ISA encoding used by GDB to debug the 16235 inferior. 16236 16237`set mipsfpu' 16238`show mipsfpu' 16239 *Note set mipsfpu: MIPS Embedded. 16240 16241`set mips mask-address ARG' 16242 This command determines whether the most-significant 32 bits of 16243 64-bit MIPS addresses are masked off. The argument ARG can be 16244 `on', `off', or `auto'. The latter is the default setting, which 16245 lets GDB determine the correct value. 16246 16247`show mips mask-address' 16248 Show whether the upper 32 bits of MIPS addresses are masked off or 16249 not. 16250 16251`set remote-mips64-transfers-32bit-regs' 16252 This command controls compatibility with 64-bit MIPS targets that 16253 transfer data in 32-bit quantities. If you have an old MIPS 64 16254 target that transfers 32 bits for some registers, like SR and FSR, 16255 and 64 bits for other registers, set this option to `on'. 16256 16257`show remote-mips64-transfers-32bit-regs' 16258 Show the current setting of compatibility with older MIPS 64 16259 targets. 16260 16261`set debug mips' 16262 This command turns on and off debugging messages for the 16263 MIPS-specific target code in GDB. 16264 16265`show debug mips' 16266 Show the current setting of MIPS debugging messages. 16267 16268 16269File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures 16270 1627121.4.5 HPPA 16272----------- 16273 16274When GDB is debugging the HP PA architecture, it provides the following 16275special commands: 16276 16277`set debug hppa' 16278 This command determines whether HPPA architecture-specific 16279 debugging messages are to be displayed. 16280 16281`show debug hppa' 16282 Show whether HPPA debugging messages are displayed. 16283 16284`maint print unwind ADDRESS' 16285 This command displays the contents of the unwind table entry at the 16286 given ADDRESS. 16287 16288 16289 16290File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures 16291 1629221.4.6 Cell Broadband Engine SPU architecture 16293--------------------------------------------- 16294 16295When GDB is debugging the Cell Broadband Engine SPU architecture, it 16296provides the following special commands: 16297 16298`info spu event' 16299 Display SPU event facility status. Shows current event mask and 16300 pending event status. 16301 16302`info spu signal' 16303 Display SPU signal notification facility status. Shows pending 16304 signal-control word and signal notification mode of both signal 16305 notification channels. 16306 16307`info spu mailbox' 16308 Display SPU mailbox facility status. Shows all pending entries, 16309 in order of processing, in each of the SPU Write Outbound, SPU 16310 Write Outbound Interrupt, and SPU Read Inbound mailboxes. 16311 16312`info spu dma' 16313 Display MFC DMA status. Shows all pending commands in the MFC DMA 16314 queue. For each entry, opcode, tag, class IDs, effective and 16315 local store addresses and transfer size are shown. 16316 16317`info spu proxydma' 16318 Display MFC Proxy-DMA status. Shows all pending commands in the 16319 MFC Proxy-DMA queue. For each entry, opcode, tag, class IDs, 16320 effective and local store addresses and transfer size are shown. 16321 16322 16323 When GDB is debugging a combined PowerPC/SPU application on the Cell 16324Broadband Engine, it provides in addition the following special 16325commands: 16326 16327`set spu stop-on-load ARG' 16328 Set whether to stop for new SPE threads. When set to `on', GDB 16329 will give control to the user when a new SPE thread enters its 16330 `main' function. The default is `off'. 16331 16332`show spu stop-on-load' 16333 Show whether to stop for new SPE threads. 16334 16335`set spu auto-flush-cache ARG' 16336 Set whether to automatically flush the software-managed cache. 16337 When set to `on', GDB will automatically cause the SPE 16338 software-managed cache to be flushed whenever SPE execution stops. 16339 This provides a consistent view of PowerPC memory that is accessed 16340 via the cache. If an application does not use the 16341 software-managed cache, this option has no effect. 16342 16343`show spu auto-flush-cache' 16344 Show whether to automatically flush the software-managed cache. 16345 16346 16347 16348File: gdb.info, Node: PowerPC, Prev: SPU, Up: Architectures 16349 1635021.4.7 PowerPC 16351-------------- 16352 16353When GDB is debugging the PowerPC architecture, it provides a set of 16354pseudo-registers to enable inspection of 128-bit wide Decimal Floating 16355Point numbers stored in the floating point registers. These values must 16356be stored in two consecutive registers, always starting at an even 16357register like `f0' or `f2'. 16358 16359 The pseudo-registers go from `$dl0' through `$dl15', and are formed 16360by joining the even/odd register pairs `f0' and `f1' for `$dl0', `f2' 16361and `f3' for `$dl1' and so on. 16362 16363 For POWER7 processors, GDB provides a set of pseudo-registers, the 1636464-bit wide Extended Floating Point Registers (`f32' through `f63'). 16365 16366 16367File: gdb.info, Node: Controlling GDB, Next: Extending GDB, Prev: Configurations, Up: Top 16368 1636922 Controlling GDB 16370****************** 16371 16372You can alter the way GDB interacts with you by using the `set' 16373command. For commands controlling how GDB displays data, see *note 16374Print Settings: Print Settings. Other settings are described here. 16375 16376* Menu: 16377 16378* Prompt:: Prompt 16379* Editing:: Command editing 16380* Command History:: Command history 16381* Screen Size:: Screen size 16382* Numbers:: Numbers 16383* ABI:: Configuring the current ABI 16384* Messages/Warnings:: Optional warnings and messages 16385* Debugging Output:: Optional messages about internal happenings 16386* Other Misc Settings:: Other Miscellaneous Settings 16387 16388 16389File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB 16390 1639122.1 Prompt 16392=========== 16393 16394GDB indicates its readiness to read a command by printing a string 16395called the "prompt". This string is normally `(gdb)'. You can change 16396the prompt string with the `set prompt' command. For instance, when 16397debugging GDB with GDB, it is useful to change the prompt in one of the 16398GDB sessions so that you can always tell which one you are talking to. 16399 16400 _Note:_ `set prompt' does not add a space for you after the prompt 16401you set. This allows you to set a prompt which ends in a space or a 16402prompt that does not. 16403 16404`set prompt NEWPROMPT' 16405 Directs GDB to use NEWPROMPT as its prompt string henceforth. 16406 16407`show prompt' 16408 Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT' 16409 16410 16411File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB 16412 1641322.2 Command Editing 16414==================== 16415 16416GDB reads its input commands via the "Readline" interface. This GNU 16417library provides consistent behavior for programs which provide a 16418command line interface to the user. Advantages are GNU Emacs-style or 16419"vi"-style inline editing of commands, `csh'-like history substitution, 16420and a storage and recall of command history across debugging sessions. 16421 16422 You may control the behavior of command line editing in GDB with the 16423command `set'. 16424 16425`set editing' 16426`set editing on' 16427 Enable command line editing (enabled by default). 16428 16429`set editing off' 16430 Disable command line editing. 16431 16432`show editing' 16433 Show whether command line editing is enabled. 16434 16435 *Note Command Line Editing::, for more details about the Readline 16436interface. Users unfamiliar with GNU Emacs or `vi' are encouraged to 16437read that chapter. 16438 16439 16440File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB 16441 1644222.3 Command History 16443==================== 16444 16445GDB can keep track of the commands you type during your debugging 16446sessions, so that you can be certain of precisely what happened. Use 16447these commands to manage the GDB command history facility. 16448 16449 GDB uses the GNU History library, a part of the Readline package, to 16450provide the history facility. *Note Using History Interactively::, for 16451the detailed description of the History library. 16452 16453 To issue a command to GDB without affecting certain aspects of the 16454state which is seen by users, prefix it with `server ' (*note Server 16455Prefix::). This means that this command will not affect the command 16456history, nor will it affect GDB's notion of which command to repeat if 16457<RET> is pressed on a line by itself. 16458 16459 The server prefix does not affect the recording of values into the 16460value history; to print a value without recording it into the value 16461history, use the `output' command instead of the `print' command. 16462 16463 Here is the description of GDB commands related to command history. 16464 16465`set history filename FNAME' 16466 Set the name of the GDB command history file to FNAME. This is 16467 the file where GDB reads an initial command history list, and 16468 where it writes the command history from this session when it 16469 exits. You can access this list through history expansion or 16470 through the history command editing characters listed below. This 16471 file defaults to the value of the environment variable 16472 `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS) 16473 if this variable is not set. 16474 16475`set history save' 16476`set history save on' 16477 Record command history in a file, whose name may be specified with 16478 the `set history filename' command. By default, this option is 16479 disabled. 16480 16481`set history save off' 16482 Stop recording command history in a file. 16483 16484`set history size SIZE' 16485 Set the number of commands which GDB keeps in its history list. 16486 This defaults to the value of the environment variable `HISTSIZE', 16487 or to 256 if this variable is not set. 16488 16489 History expansion assigns special meaning to the character `!'. 16490*Note Event Designators::, for more details. 16491 16492 Since `!' is also the logical not operator in C, history expansion 16493is off by default. If you decide to enable history expansion with the 16494`set history expansion on' command, you may sometimes need to follow 16495`!' (when it is used as logical not, in an expression) with a space or 16496a tab to prevent it from being expanded. The readline history 16497facilities do not attempt substitution on the strings `!=' and `!(', 16498even when history expansion is enabled. 16499 16500 The commands to control history expansion are: 16501 16502`set history expansion on' 16503`set history expansion' 16504 Enable history expansion. History expansion is off by default. 16505 16506`set history expansion off' 16507 Disable history expansion. 16508 16509`show history' 16510`show history filename' 16511`show history save' 16512`show history size' 16513`show history expansion' 16514 These commands display the state of the GDB history parameters. 16515 `show history' by itself displays all four states. 16516 16517`show commands' 16518 Display the last ten commands in the command history. 16519 16520`show commands N' 16521 Print ten commands centered on command number N. 16522 16523`show commands +' 16524 Print ten commands just after the commands last printed. 16525 16526 16527File: gdb.info, Node: Screen Size, Next: Numbers, Prev: Command History, Up: Controlling GDB 16528 1652922.4 Screen Size 16530================ 16531 16532Certain commands to GDB may produce large amounts of information output 16533to the screen. To help you read all of it, GDB pauses and asks you for 16534input at the end of each page of output. Type <RET> when you want to 16535continue the output, or `q' to discard the remaining output. Also, the 16536screen width setting determines when to wrap lines of output. 16537Depending on what is being printed, GDB tries to break the line at a 16538readable place, rather than simply letting it overflow onto the 16539following line. 16540 16541 Normally GDB knows the size of the screen from the terminal driver 16542software. For example, on Unix GDB uses the termcap data base together 16543with the value of the `TERM' environment variable and the `stty rows' 16544and `stty cols' settings. If this is not correct, you can override it 16545with the `set height' and `set width' commands: 16546 16547`set height LPP' 16548`show height' 16549`set width CPL' 16550`show width' 16551 These `set' commands specify a screen height of LPP lines and a 16552 screen width of CPL characters. The associated `show' commands 16553 display the current settings. 16554 16555 If you specify a height of zero lines, GDB does not pause during 16556 output no matter how long the output is. This is useful if output 16557 is to a file or to an editor buffer. 16558 16559 Likewise, you can specify `set width 0' to prevent GDB from 16560 wrapping its output. 16561 16562`set pagination on' 16563`set pagination off' 16564 Turn the output pagination on or off; the default is on. Turning 16565 pagination off is the alternative to `set height 0'. Note that 16566 running GDB with the `--batch' option (*note -batch: Mode 16567 Options.) also automatically disables pagination. 16568 16569`show pagination' 16570 Show the current pagination mode. 16571 16572 16573File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB 16574 1657522.5 Numbers 16576============ 16577 16578You can always enter numbers in octal, decimal, or hexadecimal in GDB 16579by the usual conventions: octal numbers begin with `0', decimal numbers 16580end with `.', and hexadecimal numbers begin with `0x'. Numbers that 16581neither begin with `0' or `0x', nor end with a `.' are, by default, 16582entered in base 10; likewise, the default display for numbers--when no 16583particular format is specified--is base 10. You can change the default 16584base for both input and output with the commands described below. 16585 16586`set input-radix BASE' 16587 Set the default base for numeric input. Supported choices for 16588 BASE are decimal 8, 10, or 16. BASE must itself be specified 16589 either unambiguously or using the current input radix; for 16590 example, any of 16591 16592 set input-radix 012 16593 set input-radix 10. 16594 set input-radix 0xa 16595 16596 sets the input base to decimal. On the other hand, `set 16597 input-radix 10' leaves the input radix unchanged, no matter what 16598 it was, since `10', being without any leading or trailing signs of 16599 its base, is interpreted in the current radix. Thus, if the 16600 current radix is 16, `10' is interpreted in hex, i.e. as 16 16601 decimal, which doesn't change the radix. 16602 16603`set output-radix BASE' 16604 Set the default base for numeric display. Supported choices for 16605 BASE are decimal 8, 10, or 16. BASE must itself be specified 16606 either unambiguously or using the current input radix. 16607 16608`show input-radix' 16609 Display the current default base for numeric input. 16610 16611`show output-radix' 16612 Display the current default base for numeric display. 16613 16614`set radix [BASE]' 16615`show radix' 16616 These commands set and show the default base for both input and 16617 output of numbers. `set radix' sets the radix of input and output 16618 to the same base; without an argument, it resets the radix back to 16619 its default value of 10. 16620 16621 16622 16623File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Controlling GDB 16624 1662522.6 Configuring the Current ABI 16626================================ 16627 16628GDB can determine the "ABI" (Application Binary Interface) of your 16629application automatically. However, sometimes you need to override its 16630conclusions. Use these commands to manage GDB's view of the current 16631ABI. 16632 16633 One GDB configuration can debug binaries for multiple operating 16634system targets, either via remote debugging or native emulation. GDB 16635will autodetect the "OS ABI" (Operating System ABI) in use, but you can 16636override its conclusion using the `set osabi' command. One example 16637where this is useful is in debugging of binaries which use an alternate 16638C library (e.g. UCLIBC for GNU/Linux) which does not have the same 16639identifying marks that the standard C library for your platform 16640provides. 16641 16642`show osabi' 16643 Show the OS ABI currently in use. 16644 16645`set osabi' 16646 With no argument, show the list of registered available OS ABI's. 16647 16648`set osabi ABI' 16649 Set the current OS ABI to ABI. 16650 16651 Generally, the way that an argument of type `float' is passed to a 16652function depends on whether the function is prototyped. For a 16653prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed 16654unchanged, according to the architecture's convention for `float'. For 16655unprototyped (i.e. K&R style) functions, `float' arguments are first 16656promoted to type `double' and then passed. 16657 16658 Unfortunately, some forms of debug information do not reliably 16659indicate whether a function is prototyped. If GDB calls a function 16660that is not marked as prototyped, it consults `set 16661coerce-float-to-double'. 16662 16663`set coerce-float-to-double' 16664`set coerce-float-to-double on' 16665 Arguments of type `float' will be promoted to `double' when passed 16666 to an unprototyped function. This is the default setting. 16667 16668`set coerce-float-to-double off' 16669 Arguments of type `float' will be passed directly to unprototyped 16670 functions. 16671 16672`show coerce-float-to-double' 16673 Show the current setting of promoting `float' to `double'. 16674 16675 GDB needs to know the ABI used for your program's C++ objects. The 16676correct C++ ABI depends on which C++ compiler was used to build your 16677application. GDB only fully supports programs with a single C++ ABI; 16678if your program contains code using multiple C++ ABI's or if GDB can 16679not identify your program's ABI correctly, you can tell GDB which ABI 16680to use. Currently supported ABI's include "gnu-v2", for `g++' versions 16681before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for 16682the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or 16683"gnu-v3" ABI's as well. The default setting is "auto". 16684 16685`show cp-abi' 16686 Show the C++ ABI currently in use. 16687 16688`set cp-abi' 16689 With no argument, show the list of supported C++ ABI's. 16690 16691`set cp-abi ABI' 16692`set cp-abi auto' 16693 Set the current C++ ABI to ABI, or return to automatic detection. 16694 16695 16696File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI, Up: Controlling GDB 16697 1669822.7 Optional Warnings and Messages 16699=================================== 16700 16701By default, GDB is silent about its inner workings. If you are running 16702on a slow machine, you may want to use the `set verbose' command. This 16703makes GDB tell you when it does a lengthy internal operation, so you 16704will not think it has crashed. 16705 16706 Currently, the messages controlled by `set verbose' are those which 16707announce that the symbol table for a source file is being read; see 16708`symbol-file' in *note Commands to Specify Files: Files. 16709 16710`set verbose on' 16711 Enables GDB output of certain informational messages. 16712 16713`set verbose off' 16714 Disables GDB output of certain informational messages. 16715 16716`show verbose' 16717 Displays whether `set verbose' is on or off. 16718 16719 By default, if GDB encounters bugs in the symbol table of an object 16720file, it is silent; but if you are debugging a compiler, you may find 16721this information useful (*note Errors Reading Symbol Files: Symbol 16722Errors.). 16723 16724`set complaints LIMIT' 16725 Permits GDB to output LIMIT complaints about each type of unusual 16726 symbols before becoming silent about the problem. Set LIMIT to 16727 zero to suppress all complaints; set it to a large number to 16728 prevent complaints from being suppressed. 16729 16730`show complaints' 16731 Displays how many symbol complaints GDB is permitted to produce. 16732 16733 16734 By default, GDB is cautious, and asks what sometimes seems to be a 16735lot of stupid questions to confirm certain commands. For example, if 16736you try to run a program which is already running: 16737 16738 (gdb) run 16739 The program being debugged has been started already. 16740 Start it from the beginning? (y or n) 16741 16742 If you are willing to unflinchingly face the consequences of your own 16743commands, you can disable this "feature": 16744 16745`set confirm off' 16746 Disables confirmation requests. Note that running GDB with the 16747 `--batch' option (*note -batch: Mode Options.) also automatically 16748 disables confirmation requests. 16749 16750`set confirm on' 16751 Enables confirmation requests (the default). 16752 16753`show confirm' 16754 Displays state of confirmation requests. 16755 16756 16757 If you need to debug user-defined commands or sourced files you may 16758find it useful to enable "command tracing". In this mode each command 16759will be printed as it is executed, prefixed with one or more `+' 16760symbols, the quantity denoting the call depth of each command. 16761 16762`set trace-commands on' 16763 Enable command tracing. 16764 16765`set trace-commands off' 16766 Disable command tracing. 16767 16768`show trace-commands' 16769 Display the current state of command tracing. 16770 16771 16772File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB 16773 1677422.8 Optional Messages about Internal Happenings 16775================================================ 16776 16777GDB has commands that enable optional debugging messages from various 16778GDB subsystems; normally these commands are of interest to GDB 16779maintainers, or when reporting a bug. This section documents those 16780commands. 16781 16782`set exec-done-display' 16783 Turns on or off the notification of asynchronous commands' 16784 completion. When on, GDB will print a message when an 16785 asynchronous command finishes its execution. The default is off. 16786 16787`show exec-done-display' 16788 Displays the current setting of asynchronous command completion 16789 notification. 16790 16791`set debug arch' 16792 Turns on or off display of gdbarch debugging info. The default is 16793 off 16794 16795`show debug arch' 16796 Displays the current state of displaying gdbarch debugging info. 16797 16798`set debug aix-thread' 16799 Display debugging messages about inner workings of the AIX thread 16800 module. 16801 16802`show debug aix-thread' 16803 Show the current state of AIX thread debugging info display. 16804 16805`set debug dwarf2-die' 16806 Dump DWARF2 DIEs after they are read in. The value is the number 16807 of nesting levels to print. A value of zero turns off the display. 16808 16809`show debug dwarf2-die' 16810 Show the current state of DWARF2 DIE debugging. 16811 16812`set debug displaced' 16813 Turns on or off display of GDB debugging info for the displaced 16814 stepping support. The default is off. 16815 16816`show debug displaced' 16817 Displays the current state of displaying GDB debugging info 16818 related to displaced stepping. 16819 16820`set debug event' 16821 Turns on or off display of GDB event debugging info. The default 16822 is off. 16823 16824`show debug event' 16825 Displays the current state of displaying GDB event debugging info. 16826 16827`set debug expression' 16828 Turns on or off display of debugging info about GDB expression 16829 parsing. The default is off. 16830 16831`show debug expression' 16832 Displays the current state of displaying debugging info about GDB 16833 expression parsing. 16834 16835`set debug frame' 16836 Turns on or off display of GDB frame debugging info. The default 16837 is off. 16838 16839`show debug frame' 16840 Displays the current state of displaying GDB frame debugging info. 16841 16842`set debug gnu-nat' 16843 Turns on or off debugging messages from the GNU/Hurd debug support. 16844 16845`show debug gnu-nat' 16846 Show the current state of GNU/Hurd debugging messages. 16847 16848`set debug infrun' 16849 Turns on or off display of GDB debugging info for running the 16850 inferior. The default is off. `infrun.c' contains GDB's runtime 16851 state machine used for implementing operations such as 16852 single-stepping the inferior. 16853 16854`show debug infrun' 16855 Displays the current state of GDB inferior debugging. 16856 16857`set debug lin-lwp' 16858 Turns on or off debugging messages from the Linux LWP debug 16859 support. 16860 16861`show debug lin-lwp' 16862 Show the current state of Linux LWP debugging messages. 16863 16864`set debug lin-lwp-async' 16865 Turns on or off debugging messages from the Linux LWP async debug 16866 support. 16867 16868`show debug lin-lwp-async' 16869 Show the current state of Linux LWP async debugging messages. 16870 16871`set debug observer' 16872 Turns on or off display of GDB observer debugging. This includes 16873 info such as the notification of observable events. 16874 16875`show debug observer' 16876 Displays the current state of observer debugging. 16877 16878`set debug overload' 16879 Turns on or off display of GDB C++ overload debugging info. This 16880 includes info such as ranking of functions, etc. The default is 16881 off. 16882 16883`show debug overload' 16884 Displays the current state of displaying GDB C++ overload 16885 debugging info. 16886 16887`set debug parser' 16888 Turns on or off the display of expression parser debugging output. 16889 Internally, this sets the `yydebug' variable in the expression 16890 parser. *Note Tracing Your Parser: (bison)Tracing, for details. 16891 The default is off. 16892 16893`show debug parser' 16894 Show the current state of expression parser debugging. 16895 16896`set debug remote' 16897 Turns on or off display of reports on all packets sent back and 16898 forth across the serial line to the remote machine. The info is 16899 printed on the GDB standard output stream. The default is off. 16900 16901`show debug remote' 16902 Displays the state of display of remote packets. 16903 16904`set debug serial' 16905 Turns on or off display of GDB serial debugging info. The default 16906 is off. 16907 16908`show debug serial' 16909 Displays the current state of displaying GDB serial debugging info. 16910 16911`set debug solib-frv' 16912 Turns on or off debugging messages for FR-V shared-library code. 16913 16914`show debug solib-frv' 16915 Display the current state of FR-V shared-library code debugging 16916 messages. 16917 16918`set debug target' 16919 Turns on or off display of GDB target debugging info. This info 16920 includes what is going on at the target level of GDB, as it 16921 happens. The default is 0. Set it to 1 to track events, and to 2 16922 to also track the value of large memory transfers. Changes to 16923 this flag do not take effect until the next time you connect to a 16924 target or use the `run' command. 16925 16926`show debug target' 16927 Displays the current state of displaying GDB target debugging info. 16928 16929`set debug timestamp' 16930 Turns on or off display of timestamps with GDB debugging info. 16931 When enabled, seconds and microseconds are displayed before each 16932 debugging message. 16933 16934`show debug timestamp' 16935 Displays the current state of displaying timestamps with GDB 16936 debugging info. 16937 16938`set debugvarobj' 16939 Turns on or off display of GDB variable object debugging info. The 16940 default is off. 16941 16942`show debugvarobj' 16943 Displays the current state of displaying GDB variable object 16944 debugging info. 16945 16946`set debug xml' 16947 Turns on or off debugging messages for built-in XML parsers. 16948 16949`show debug xml' 16950 Displays the current state of XML debugging messages. 16951 16952 16953File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB 16954 1695522.9 Other Miscellaneous Settings 16956================================= 16957 16958`set interactive-mode' 16959 If `on', forces GDB to operate interactively. If `off', forces 16960 GDB to operate non-interactively, If `auto' (the default), GDB 16961 guesses which mode to use, based on whether the debugger was 16962 started in a terminal or not. 16963 16964 In the vast majority of cases, the debugger should be able to guess 16965 correctly which mode should be used. But this setting can be 16966 useful in certain specific cases, such as running a MinGW GDB 16967 inside a cygwin window. 16968 16969`show interactive-mode' 16970 Displays whether the debugger is operating in interactive mode or 16971 not. 16972 16973 16974File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top 16975 1697623 Extending GDB 16977**************** 16978 16979GDB provides two mechanisms for extension. The first is based on 16980composition of GDB commands, and the second is based on the Python 16981scripting language. 16982 16983 To facilitate the use of these extensions, GDB is capable of 16984evaluating the contents of a file. When doing so, GDB can recognize 16985which scripting language is being used by looking at the filename 16986extension. Files with an unrecognized filename extension are always 16987treated as a GDB Command Files. *Note Command files: Command Files. 16988 16989 You can control how GDB evaluates these files with the following 16990setting: 16991 16992`set script-extension off' 16993 All scripts are always evaluated as GDB Command Files. 16994 16995`set script-extension soft' 16996 The debugger determines the scripting language based on filename 16997 extension. If this scripting language is supported, GDB evaluates 16998 the script using that language. Otherwise, it evaluates the file 16999 as a GDB Command File. 17000 17001`set script-extension strict' 17002 The debugger determines the scripting language based on filename 17003 extension, and evaluates the script using that language. If the 17004 language is not supported, then the evaluation fails. 17005 17006`show script-extension' 17007 Display the current value of the `script-extension' option. 17008 17009 17010* Menu: 17011 17012* Sequences:: Canned Sequences of Commands 17013* Python:: Scripting GDB using Python 17014 17015 17016File: gdb.info, Node: Sequences, Next: Python, Up: Extending GDB 17017 1701823.1 Canned Sequences of Commands 17019================================= 17020 17021Aside from breakpoint commands (*note Breakpoint Command Lists: Break 17022Commands.), GDB provides two ways to store sequences of commands for 17023execution as a unit: user-defined commands and command files. 17024 17025* Menu: 17026 17027* Define:: How to define your own commands 17028* Hooks:: Hooks for user-defined commands 17029* Command Files:: How to write scripts of commands to be stored in a file 17030* Output:: Commands for controlled output 17031 17032 17033File: gdb.info, Node: Define, Next: Hooks, Up: Sequences 17034 1703523.1.1 User-defined Commands 17036---------------------------- 17037 17038A "user-defined command" is a sequence of GDB commands to which you 17039assign a new name as a command. This is done with the `define' 17040command. User commands may accept up to 10 arguments separated by 17041whitespace. Arguments are accessed within the user command via 17042`$arg0...$arg9'. A trivial example: 17043 17044 define adder 17045 print $arg0 + $arg1 + $arg2 17046 end 17047 17048To execute the command use: 17049 17050 adder 1 2 3 17051 17052This defines the command `adder', which prints the sum of its three 17053arguments. Note the arguments are text substitutions, so they may 17054reference variables, use complex expressions, or even perform inferior 17055functions calls. 17056 17057 In addition, `$argc' may be used to find out how many arguments have 17058been passed. This expands to a number in the range 0...10. 17059 17060 define adder 17061 if $argc == 2 17062 print $arg0 + $arg1 17063 end 17064 if $argc == 3 17065 print $arg0 + $arg1 + $arg2 17066 end 17067 end 17068 17069`define COMMANDNAME' 17070 Define a command named COMMANDNAME. If there is already a command 17071 by that name, you are asked to confirm that you want to redefine 17072 it. COMMANDNAME may be a bare command name consisting of letters, 17073 numbers, dashes, and underscores. It may also start with any 17074 predefined prefix command. For example, `define target my-target' 17075 creates a user-defined `target my-target' command. 17076 17077 The definition of the command is made up of other GDB command 17078 lines, which are given following the `define' command. The end of 17079 these commands is marked by a line containing `end'. 17080 17081`document COMMANDNAME' 17082 Document the user-defined command COMMANDNAME, so that it can be 17083 accessed by `help'. The command COMMANDNAME must already be 17084 defined. This command reads lines of documentation just as 17085 `define' reads the lines of the command definition, ending with 17086 `end'. After the `document' command is finished, `help' on command 17087 COMMANDNAME displays the documentation you have written. 17088 17089 You may use the `document' command again to change the 17090 documentation of a command. Redefining the command with `define' 17091 does not change the documentation. 17092 17093`dont-repeat' 17094 Used inside a user-defined command, this tells GDB that this 17095 command should not be repeated when the user hits <RET> (*note 17096 repeat last command: Command Syntax.). 17097 17098`help user-defined' 17099 List all user-defined commands, with the first line of the 17100 documentation (if any) for each. 17101 17102`show user' 17103`show user COMMANDNAME' 17104 Display the GDB commands used to define COMMANDNAME (but not its 17105 documentation). If no COMMANDNAME is given, display the 17106 definitions for all user-defined commands. 17107 17108`show max-user-call-depth' 17109`set max-user-call-depth' 17110 The value of `max-user-call-depth' controls how many recursion 17111 levels are allowed in user-defined commands before GDB suspects an 17112 infinite recursion and aborts the command. 17113 17114 In addition to the above commands, user-defined commands frequently 17115use control flow commands, described in *note Command Files::. 17116 17117 When user-defined commands are executed, the commands of the 17118definition are not printed. An error in any command stops execution of 17119the user-defined command. 17120 17121 If used interactively, commands that would ask for confirmation 17122proceed without asking when used inside a user-defined command. Many 17123GDB commands that normally print messages to say what they are doing 17124omit the messages when used in a user-defined command. 17125 17126 17127File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences 17128 1712923.1.2 User-defined Command Hooks 17130--------------------------------- 17131 17132You may define "hooks", which are a special kind of user-defined 17133command. Whenever you run the command `foo', if the user-defined 17134command `hook-foo' exists, it is executed (with no arguments) before 17135that command. 17136 17137 A hook may also be defined which is run after the command you 17138executed. Whenever you run the command `foo', if the user-defined 17139command `hookpost-foo' exists, it is executed (with no arguments) after 17140that command. Post-execution hooks may exist simultaneously with 17141pre-execution hooks, for the same command. 17142 17143 It is valid for a hook to call the command which it hooks. If this 17144occurs, the hook is not re-executed, thereby avoiding infinite 17145recursion. 17146 17147 In addition, a pseudo-command, `stop' exists. Defining 17148(`hook-stop') makes the associated commands execute every time 17149execution stops in your program: before breakpoint commands are run, 17150displays are printed, or the stack frame is printed. 17151 17152 For example, to ignore `SIGALRM' signals while single-stepping, but 17153treat them normally during normal execution, you could define: 17154 17155 define hook-stop 17156 handle SIGALRM nopass 17157 end 17158 17159 define hook-run 17160 handle SIGALRM pass 17161 end 17162 17163 define hook-continue 17164 handle SIGALRM pass 17165 end 17166 17167 As a further example, to hook at the beginning and end of the `echo' 17168command, and to add extra text to the beginning and end of the message, 17169you could define: 17170 17171 define hook-echo 17172 echo <<<--- 17173 end 17174 17175 define hookpost-echo 17176 echo --->>>\n 17177 end 17178 17179 (gdb) echo Hello World 17180 <<<---Hello World--->>> 17181 (gdb) 17182 17183 You can define a hook for any single-word command in GDB, but not 17184for command aliases; you should define a hook for the basic command 17185name, e.g. `backtrace' rather than `bt'. You can hook a multi-word 17186command by adding `hook-' or `hookpost-' to the last word of the 17187command, e.g. `define target hook-remote' to add a hook to `target 17188remote'. 17189 17190 If an error occurs during the execution of your hook, execution of 17191GDB commands stops and GDB issues a prompt (before the command that you 17192actually typed had a chance to run). 17193 17194 If you try to define a hook which does not match any known command, 17195you get a warning from the `define' command. 17196 17197 17198File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences 17199 1720023.1.3 Command Files 17201-------------------- 17202 17203A command file for GDB is a text file made of lines that are GDB 17204commands. Comments (lines starting with `#') may also be included. An 17205empty line in a command file does nothing; it does not mean to repeat 17206the last command, as it would from the terminal. 17207 17208 You can request the execution of a command file with the `source' 17209command. Note that the `source' command is also used to evaluate 17210scripts that are not Command Files. The exact behavior can be 17211configured using the `script-extension' setting. *Note Extending GDB: 17212Extending GDB. 17213 17214`source [-s] [-v] FILENAME' 17215 Execute the command file FILENAME. 17216 17217 The lines in a command file are generally executed sequentially, 17218unless the order of execution is changed by one of the _flow-control 17219commands_ described below. The commands are not printed as they are 17220executed. An error in any command terminates execution of the command 17221file and control is returned to the console. 17222 17223 GDB first searches for FILENAME in the current directory. If the 17224file is not found there, and FILENAME does not specify a directory, 17225then GDB also looks for the file on the source search path (specified 17226with the `directory' command); except that `$cdir' is not searched 17227because the compilation directory is not relevant to scripts. 17228 17229 If `-s' is specified, then GDB searches for FILENAME on the search 17230path even if FILENAME specifies a directory. The search is done by 17231appending FILENAME to each element of the search path. So, for 17232example, if FILENAME is `mylib/myscript' and the search path contains 17233`/home/user' then GDB will look for the script 17234`/home/user/mylib/myscript'. The search is also done if FILENAME is an 17235absolute path. For example, if FILENAME is `/tmp/myscript' and the 17236search path contains `/home/user' then GDB will look for the script 17237`/home/user/tmp/myscript'. For DOS-like systems, if FILENAME contains 17238a drive specification, it is stripped before concatenation. For 17239example, if FILENAME is `d:myscript' and the search path contains 17240`c:/tmp' then GDB will look for the script `c:/tmp/myscript'. 17241 17242 If `-v', for verbose mode, is given then GDB displays each command 17243as it is executed. The option must be given before FILENAME, and is 17244interpreted as part of the filename anywhere else. 17245 17246 Commands that would ask for confirmation if used interactively 17247proceed without asking when used in a command file. Many GDB commands 17248that normally print messages to say what they are doing omit the 17249messages when called from command files. 17250 17251 GDB also accepts command input from standard input. In this mode, 17252normal output goes to standard output and error output goes to standard 17253error. Errors in a command file supplied on standard input do not 17254terminate execution of the command file--execution continues with the 17255next command. 17256 17257 gdb < cmds > log 2>&1 17258 17259 (The syntax above will vary depending on the shell used.) This 17260example will execute commands from the file `cmds'. All output and 17261errors would be directed to `log'. 17262 17263 Since commands stored on command files tend to be more general than 17264commands typed interactively, they frequently need to deal with 17265complicated situations, such as different or unexpected values of 17266variables and symbols, changes in how the program being debugged is 17267built, etc. GDB provides a set of flow-control commands to deal with 17268these complexities. Using these commands, you can write complex 17269scripts that loop over data structures, execute commands conditionally, 17270etc. 17271 17272`if' 17273`else' 17274 This command allows to include in your script conditionally 17275 executed commands. The `if' command takes a single argument, which 17276 is an expression to evaluate. It is followed by a series of 17277 commands that are executed only if the expression is true (its 17278 value is nonzero). There can then optionally be an `else' line, 17279 followed by a series of commands that are only executed if the 17280 expression was false. The end of the list is marked by a line 17281 containing `end'. 17282 17283`while' 17284 This command allows to write loops. Its syntax is similar to 17285 `if': the command takes a single argument, which is an expression 17286 to evaluate, and must be followed by the commands to execute, one 17287 per line, terminated by an `end'. These commands are called the 17288 "body" of the loop. The commands in the body of `while' are 17289 executed repeatedly as long as the expression evaluates to true. 17290 17291`loop_break' 17292 This command exits the `while' loop in whose body it is included. 17293 Execution of the script continues after that `while's `end' line. 17294 17295`loop_continue' 17296 This command skips the execution of the rest of the body of 17297 commands in the `while' loop in whose body it is included. 17298 Execution branches to the beginning of the `while' loop, where it 17299 evaluates the controlling expression. 17300 17301`end' 17302 Terminate the block of commands that are the body of `if', `else', 17303 or `while' flow-control commands. 17304 17305 17306File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences 17307 1730823.1.4 Commands for Controlled Output 17309------------------------------------- 17310 17311During the execution of a command file or a user-defined command, normal 17312GDB output is suppressed; the only output that appears is what is 17313explicitly printed by the commands in the definition. This section 17314describes three commands useful for generating exactly the output you 17315want. 17316 17317`echo TEXT' 17318 Print TEXT. Nonprinting characters can be included in TEXT using 17319 C escape sequences, such as `\n' to print a newline. *No newline 17320 is printed unless you specify one.* In addition to the standard C 17321 escape sequences, a backslash followed by a space stands for a 17322 space. This is useful for displaying a string with spaces at the 17323 beginning or the end, since leading and trailing spaces are 17324 otherwise trimmed from all arguments. To print ` and foo = ', use 17325 the command `echo \ and foo = \ '. 17326 17327 A backslash at the end of TEXT can be used, as in C, to continue 17328 the command onto subsequent lines. For example, 17329 17330 echo This is some text\n\ 17331 which is continued\n\ 17332 onto several lines.\n 17333 17334 produces the same output as 17335 17336 echo This is some text\n 17337 echo which is continued\n 17338 echo onto several lines.\n 17339 17340`output EXPRESSION' 17341 Print the value of EXPRESSION and nothing but that value: no 17342 newlines, no `$NN = '. The value is not entered in the value 17343 history either. *Note Expressions: Expressions, for more 17344 information on expressions. 17345 17346`output/FMT EXPRESSION' 17347 Print the value of EXPRESSION in format FMT. You can use the same 17348 formats as for `print'. *Note Output Formats: Output Formats, for 17349 more information. 17350 17351`printf TEMPLATE, EXPRESSIONS...' 17352 Print the values of one or more EXPRESSIONS under the control of 17353 the string TEMPLATE. To print several values, make EXPRESSIONS be 17354 a comma-separated list of individual expressions, which may be 17355 either numbers or pointers. Their values are printed as specified 17356 by TEMPLATE, exactly as a C program would do by executing the code 17357 below: 17358 17359 printf (TEMPLATE, EXPRESSIONS...); 17360 17361 As in `C' `printf', ordinary characters in TEMPLATE are printed 17362 verbatim, while "conversion specification" introduced by the `%' 17363 character cause subsequent EXPRESSIONS to be evaluated, their 17364 values converted and formatted according to type and style 17365 information encoded in the conversion specifications, and then 17366 printed. 17367 17368 For example, you can print two values in hex like this: 17369 17370 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 17371 17372 `printf' supports all the standard `C' conversion specifications, 17373 including the flags and modifiers between the `%' character and 17374 the conversion letter, with the following exceptions: 17375 17376 * The argument-ordering modifiers, such as `2$', are not 17377 supported. 17378 17379 * The modifier `*' is not supported for specifying precision or 17380 width. 17381 17382 * The `'' flag (for separation of digits into groups according 17383 to `LC_NUMERIC'') is not supported. 17384 17385 * The type modifiers `hh', `j', `t', and `z' are not supported. 17386 17387 * The conversion letter `n' (as in `%n') is not supported. 17388 17389 * The conversion letters `a' and `A' are not supported. 17390 17391 Note that the `ll' type modifier is supported only if the 17392 underlying `C' implementation used to build GDB supports the `long 17393 long int' type, and the `L' type modifier is supported only if 17394 `long double' type is available. 17395 17396 As in `C', `printf' supports simple backslash-escape sequences, 17397 such as `\n', `\t', `\\', `\"', `\a', and `\f', that consist of 17398 backslash followed by a single character. Octal and hexadecimal 17399 escape sequences are not supported. 17400 17401 Additionally, `printf' supports conversion specifications for DFP 17402 ("Decimal Floating Point") types using the following length 17403 modifiers together with a floating point specifier. letters: 17404 17405 * `H' for printing `Decimal32' types. 17406 17407 * `D' for printing `Decimal64' types. 17408 17409 * `DD' for printing `Decimal128' types. 17410 17411 If the underlying `C' implementation used to build GDB has support 17412 for the three length modifiers for DFP types, other modifiers such 17413 as width and precision will also be available for GDB to use. 17414 17415 In case there is no such `C' support, no additional modifiers will 17416 be available and the value will be printed in the standard way. 17417 17418 Here's an example of printing DFP types using the above conversion 17419 letters: 17420 printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl 17421 17422`eval TEMPLATE, EXPRESSIONS...' 17423 Convert the values of one or more EXPRESSIONS under the control of 17424 the string TEMPLATE to a command line, and call it. 17425 17426 17427 17428File: gdb.info, Node: Python, Prev: Sequences, Up: Extending GDB 17429 1743023.2 Scripting GDB using Python 17431=============================== 17432 17433You can script GDB using the Python programming language 17434(http://www.python.org/). This feature is available only if GDB was 17435configured using `--with-python'. 17436 17437 Python scripts used by GDB should be installed in 17438`DATA-DIRECTORY/python', where DATA-DIRECTORY is the data directory as 17439determined at GDB startup (*note Data Files::). This directory, known 17440as the "python directory", is automatically added to the Python Search 17441Path in order to allow the Python interpreter to locate all scripts 17442installed at this location. 17443 17444* Menu: 17445 17446* Python Commands:: Accessing Python from GDB. 17447* Python API:: Accessing GDB from Python. 17448* Auto-loading:: Automatically loading Python code. 17449 17450 17451File: gdb.info, Node: Python Commands, Next: Python API, Up: Python 17452 1745323.2.1 Python Commands 17454---------------------- 17455 17456GDB provides one command for accessing the Python interpreter, and one 17457related setting: 17458 17459`python [CODE]' 17460 The `python' command can be used to evaluate Python code. 17461 17462 If given an argument, the `python' command will evaluate the 17463 argument as a Python command. For example: 17464 17465 (gdb) python print 23 17466 23 17467 17468 If you do not provide an argument to `python', it will act as a 17469 multi-line command, like `define'. In this case, the Python 17470 script is made up of subsequent command lines, given after the 17471 `python' command. This command list is terminated using a line 17472 containing `end'. For example: 17473 17474 (gdb) python 17475 Type python script 17476 End with a line saying just "end". 17477 >print 23 17478 >end 17479 23 17480 17481`maint set python print-stack' 17482 By default, GDB will print a stack trace when an error occurs in a 17483 Python script. This can be controlled using `maint set python 17484 print-stack': if `on', the default, then Python stack printing is 17485 enabled; if `off', then Python stack printing is disabled. 17486 17487 It is also possible to execute a Python script from the GDB 17488interpreter: 17489 17490`source `script-name'' 17491 The script name must end with `.py' and GDB must be configured to 17492 recognize the script language based on filename extension using 17493 the `script-extension' setting. *Note Extending GDB: Extending 17494 GDB. 17495 17496`python execfile ("script-name")' 17497 This method is based on the `execfile' Python built-in function, 17498 and thus is always available. 17499 17500 17501File: gdb.info, Node: Python API, Next: Auto-loading, Prev: Python Commands, Up: Python 17502 1750323.2.2 Python API 17504----------------- 17505 17506At startup, GDB overrides Python's `sys.stdout' and `sys.stderr' to 17507print using GDB's output-paging streams. A Python program which 17508outputs to one of these streams may have its output interrupted by the 17509user (*note Screen Size::). In this situation, a Python 17510`KeyboardInterrupt' exception is thrown. 17511 17512* Menu: 17513 17514* Basic Python:: Basic Python Functions. 17515* Exception Handling:: 17516* Values From Inferior:: 17517* Types In Python:: Python representation of types. 17518* Pretty Printing API:: Pretty-printing values. 17519* Selecting Pretty-Printers:: How GDB chooses a pretty-printer. 17520* Disabling Pretty-Printers:: Disabling broken printers. 17521* Inferiors In Python:: Python representation of inferiors (processes) 17522* Threads In Python:: Accessing inferior threads from Python. 17523* Commands In Python:: Implementing new commands in Python. 17524* Parameters In Python:: Adding new GDB parameters. 17525* Functions In Python:: Writing new convenience functions. 17526* Progspaces In Python:: Program spaces. 17527* Objfiles In Python:: Object files. 17528* Frames In Python:: Accessing inferior stack frames from Python. 17529* Blocks In Python:: Accessing frame blocks from Python. 17530* Symbols In Python:: Python representation of symbols. 17531* Symbol Tables In Python:: Python representation of symbol tables. 17532* Lazy Strings In Python:: Python representation of lazy strings. 17533* Breakpoints In Python:: Manipulating breakpoints using Python. 17534 17535 17536File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API 17537 1753823.2.2.1 Basic Python 17539..................... 17540 17541GDB introduces a new Python module, named `gdb'. All methods and 17542classes added by GDB are placed in this module. GDB automatically 17543`import's the `gdb' module for use in all scripts evaluated by the 17544`python' command. 17545 17546 -- Variable: PYTHONDIR 17547 A string containing the python directory (*note Python::). 17548 17549 -- Function: execute command [from_tty] [to_string] 17550 Evaluate COMMAND, a string, as a GDB CLI command. If a GDB 17551 exception happens while COMMAND runs, it is translated as 17552 described in *note Exception Handling: Exception Handling. 17553 17554 FROM_TTY specifies whether GDB ought to consider this command as 17555 having originated from the user invoking it interactively. It 17556 must be a boolean value. If omitted, it defaults to `False'. 17557 17558 By default, any output produced by COMMAND is sent to GDB's 17559 standard output. If the TO_STRING parameter is `True', then 17560 output will be collected by `gdb.execute' and returned as a 17561 string. The default is `False', in which case the return value is 17562 `None'. If TO_STRING is `True', the GDB virtual terminal will be 17563 temporarily set to unlimited width and height, and its pagination 17564 will be disabled; *note Screen Size::. 17565 17566 -- Function: breakpoints 17567 Return a sequence holding all of GDB's breakpoints. *Note 17568 Breakpoints In Python::, for more information. 17569 17570 -- Function: parameter parameter 17571 Return the value of a GDB parameter. PARAMETER is a string naming 17572 the parameter to look up; PARAMETER may contain spaces if the 17573 parameter has a multi-part name. For example, `print object' is a 17574 valid parameter name. 17575 17576 If the named parameter does not exist, this function throws a 17577 `RuntimeError'. Otherwise, the parameter's value is converted to 17578 a Python value of the appropriate type, and returned. 17579 17580 -- Function: history number 17581 Return a value from GDB's value history (*note Value History::). 17582 NUMBER indicates which history element to return. If NUMBER is 17583 negative, then GDB will take its absolute value and count backward 17584 from the last element (i.e., the most recent element) to find the 17585 value to return. If NUMBER is zero, then GDB will return the most 17586 recent element. If the element specified by NUMBER doesn't exist 17587 in the value history, a `RuntimeError' exception will be raised. 17588 17589 If no exception is raised, the return value is always an instance 17590 of `gdb.Value' (*note Values From Inferior::). 17591 17592 -- Function: parse_and_eval expression 17593 Parse EXPRESSION as an expression in the current language, 17594 evaluate it, and return the result as a `gdb.Value'. EXPRESSION 17595 must be a string. 17596 17597 This function can be useful when implementing a new command (*note 17598 Commands In Python::), as it provides a way to parse the command's 17599 argument as an expression. It is also useful simply to compute 17600 values, for example, it is the only way to get the value of a 17601 convenience variable (*note Convenience Vars::) as a `gdb.Value'. 17602 17603 -- Function: post_event event 17604 Put EVENT, a callable object taking no arguments, into GDB's 17605 internal event queue. This callable will be invoked at some later 17606 point, during GDB's event processing. Events posted using 17607 `post_event' will be run in the order in which they were posted; 17608 however, there is no way to know when they will be processed 17609 relative to other events inside GDB. 17610 17611 GDB is not thread-safe. If your Python program uses multiple 17612 threads, you must be careful to only call GDB-specific functions 17613 in the main GDB thread. `post_event' ensures this. For example: 17614 17615 (gdb) python 17616 >import threading 17617 > 17618 >class Writer(): 17619 > def __init__(self, message): 17620 > self.message = message; 17621 > def __call__(self): 17622 > gdb.write(self.message) 17623 > 17624 >class MyThread1 (threading.Thread): 17625 > def run (self): 17626 > gdb.post_event(Writer("Hello ")) 17627 > 17628 >class MyThread2 (threading.Thread): 17629 > def run (self): 17630 > gdb.post_event(Writer("World\n")) 17631 > 17632 >MyThread1().start() 17633 >MyThread2().start() 17634 >end 17635 (gdb) Hello World 17636 17637 -- Function: write string 17638 Print a string to GDB's paginated standard output stream. Writing 17639 to `sys.stdout' or `sys.stderr' will automatically call this 17640 function. 17641 17642 -- Function: flush 17643 Flush GDB's paginated standard output stream. Flushing 17644 `sys.stdout' or `sys.stderr' will automatically call this function. 17645 17646 -- Function: target_charset 17647 Return the name of the current target character set (*note 17648 Character Sets::). This differs from 17649 `gdb.parameter('target-charset')' in that `auto' is never returned. 17650 17651 -- Function: target_wide_charset 17652 Return the name of the current target wide character set (*note 17653 Character Sets::). This differs from 17654 `gdb.parameter('target-wide-charset')' in that `auto' is never 17655 returned. 17656 17657 -- Function: solib_name address 17658 Return the name of the shared library holding the given ADDRESS as 17659 a string, or `None'. 17660 17661 -- Function: decode_line [expression] 17662 Return locations of the line specified by EXPRESSION, or of the 17663 current line if no argument was given. This function returns a 17664 Python tuple containing two elements. The first element contains 17665 a string holding any unparsed section of EXPRESSION (or `None' if 17666 the expression has been fully parsed). The second element contains 17667 either `None' or another tuple that contains all the locations 17668 that match the expression represented as `gdb.Symtab_and_line' 17669 objects (*note Symbol Tables In Python::). If EXPRESSION is 17670 provided, it is decoded the way that GDB's inbuilt `break' or 17671 `edit' commands do (*note Specify Location::). 17672 17673 17674File: gdb.info, Node: Exception Handling, Next: Values From Inferior, Prev: Basic Python, Up: Python API 17675 1767623.2.2.2 Exception Handling 17677........................... 17678 17679When executing the `python' command, Python exceptions uncaught within 17680the Python code are translated to calls to GDB error-reporting 17681mechanism. If the command that called `python' does not handle the 17682error, GDB will terminate it and print an error message containing the 17683Python exception name, the associated value, and the Python call stack 17684backtrace at the point where the exception was raised. Example: 17685 17686 (gdb) python print foo 17687 Traceback (most recent call last): 17688 File "<string>", line 1, in <module> 17689 NameError: name 'foo' is not defined 17690 17691 GDB errors that happen in GDB commands invoked by Python code are 17692converted to Python `RuntimeError' exceptions. User interrupt (via 17693`C-c' or by typing `q' at a pagination prompt) is translated to a 17694Python `KeyboardInterrupt' exception. If you catch these exceptions in 17695your Python code, your exception handler will see `RuntimeError' or 17696`KeyboardInterrupt' as the exception type, the GDB error message as its 17697value, and the Python call stack backtrace at the Python statement 17698closest to where the GDB error occured as the traceback. 17699 17700 When implementing GDB commands in Python via `gdb.Command', it is 17701useful to be able to throw an exception that doesn't cause a traceback 17702to be printed. For example, the user may have invoked the command 17703incorrectly. Use the `gdb.GdbError' exception to handle this case. 17704Example: 17705 17706 (gdb) python 17707 >class HelloWorld (gdb.Command): 17708 > """Greet the whole world.""" 17709 > def __init__ (self): 17710 > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) 17711 > def invoke (self, args, from_tty): 17712 > argv = gdb.string_to_argv (args) 17713 > if len (argv) != 0: 17714 > raise gdb.GdbError ("hello-world takes no arguments") 17715 > print "Hello, World!" 17716 >HelloWorld () 17717 >end 17718 (gdb) hello-world 42 17719 hello-world takes no arguments 17720 17721 17722File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Exception Handling, Up: Python API 17723 1772423.2.2.3 Values From Inferior 17725............................. 17726 17727GDB provides values it obtains from the inferior program in an object 17728of type `gdb.Value'. GDB uses this object for its internal bookkeeping 17729of the inferior's values, and for fetching values when necessary. 17730 17731 Inferior values that are simple scalars can be used directly in 17732Python expressions that are valid for the value's data type. Here's an 17733example for an integer or floating-point value `some_val': 17734 17735 bar = some_val + 2 17736 17737As result of this, `bar' will also be a `gdb.Value' object whose values 17738are of the same type as those of `some_val'. 17739 17740 Inferior values that are structures or instances of some class can 17741be accessed using the Python "dictionary syntax". For example, if 17742`some_val' is a `gdb.Value' instance holding a structure, you can 17743access its `foo' element with: 17744 17745 bar = some_val['foo'] 17746 17747 Again, `bar' will also be a `gdb.Value' object. 17748 17749 A `gdb.Value' that represents a function can be executed via 17750inferior function call. Any arguments provided to the call must match 17751the function's prototype, and must be provided in the order specified 17752by that prototype. 17753 17754 For example, `some_val' is a `gdb.Value' instance representing a 17755function that takes two integers as arguments. To execute this 17756function, call it like so: 17757 17758 result = some_val (10,20) 17759 17760 Any values returned from a function call will be stored as a 17761`gdb.Value'. 17762 17763 The following attributes are provided: 17764 17765 -- Instance Variable of Value: address 17766 If this object is addressable, this read-only attribute holds 17767 a `gdb.Value' object representing the address. Otherwise, 17768 this attribute holds `None'. 17769 17770 -- Instance Variable of Value: is_optimized_out 17771 This read-only boolean attribute is true if the compiler 17772 optimized out this value, thus it is not available for 17773 fetching from the inferior. 17774 17775 -- Instance Variable of Value: type 17776 The type of this `gdb.Value'. The value of this attribute is 17777 a `gdb.Type' object. 17778 17779 -- Instance Variable of Value: dynamic_type 17780 The dynamic type of this `gdb.Value'. This uses C++ run-time 17781 type information to determine the dynamic type of the value. 17782 If this value is of class type, it will return the class in 17783 which the value is embedded, if any. If this value is of 17784 pointer or reference to a class type, it will compute the 17785 dynamic type of the referenced object, and return a pointer 17786 or reference to that type, respectively. In all other cases, 17787 it will return the value's static type. 17788 17789 The following methods are provided: 17790 17791 -- Method on Value: cast type 17792 Return a new instance of `gdb.Value' that is the result of 17793 casting this instance to the type described by TYPE, which 17794 must be a `gdb.Type' object. If the cast cannot be performed 17795 for some reason, this method throws an exception. 17796 17797 -- Method on Value: dereference 17798 For pointer data types, this method returns a new `gdb.Value' 17799 object whose contents is the object pointed to by the 17800 pointer. For example, if `foo' is a C pointer to an `int', 17801 declared in your C program as 17802 17803 int *foo; 17804 17805 then you can use the corresponding `gdb.Value' to access what 17806 `foo' points to like this: 17807 17808 bar = foo.dereference () 17809 17810 The result `bar' will be a `gdb.Value' object holding the 17811 value pointed to by `foo'. 17812 17813 -- Method on Value: dynamic_cast type 17814 Like `Value.cast', but works as if the C++ `dynamic_cast' 17815 operator were used. Consult a C++ reference for details. 17816 17817 -- Method on Value: reinterpret_cast type 17818 Like `Value.cast', but works as if the C++ `reinterpret_cast' 17819 operator were used. Consult a C++ reference for details. 17820 17821 -- Method on Value: string [encoding] [errors] [length] 17822 If this `gdb.Value' represents a string, then this method 17823 converts the contents to a Python string. Otherwise, this 17824 method will throw an exception. 17825 17826 Strings are recognized in a language-specific way; whether a 17827 given `gdb.Value' represents a string is determined by the 17828 current language. 17829 17830 For C-like languages, a value is a string if it is a pointer 17831 to or an array of characters or ints. The string is assumed 17832 to be terminated by a zero of the appropriate width. However 17833 if the optional length argument is given, the string will be 17834 converted to that given length, ignoring any embedded zeros 17835 that the string may contain. 17836 17837 If the optional ENCODING argument is given, it must be a 17838 string naming the encoding of the string in the `gdb.Value', 17839 such as `"ascii"', `"iso-8859-6"' or `"utf-8"'. It accepts 17840 the same encodings as the corresponding argument to Python's 17841 `string.decode' method, and the Python codec machinery will 17842 be used to convert the string. If ENCODING is not given, or 17843 if ENCODING is the empty string, then either the 17844 `target-charset' (*note Character Sets::) will be used, or a 17845 language-specific encoding will be used, if the current 17846 language is able to supply one. 17847 17848 The optional ERRORS argument is the same as the corresponding 17849 argument to Python's `string.decode' method. 17850 17851 If the optional LENGTH argument is given, the string will be 17852 fetched and converted to the given length. 17853 17854 -- Method on Value: lazy_string [encoding] [length] 17855 If this `gdb.Value' represents a string, then this method 17856 converts the contents to a `gdb.LazyString' (*note Lazy 17857 Strings In Python::). Otherwise, this method will throw an 17858 exception. 17859 17860 If the optional ENCODING argument is given, it must be a 17861 string naming the encoding of the `gdb.LazyString'. Some 17862 examples are: `ascii', `iso-8859-6' or `utf-8'. If the 17863 ENCODING argument is an encoding that GDB does recognize, GDB 17864 will raise an error. 17865 17866 When a lazy string is printed, the GDB encoding machinery is 17867 used to convert the string during printing. If the optional 17868 ENCODING argument is not provided, or is an empty string, GDB 17869 will automatically select the encoding most suitable for the 17870 string type. For further information on encoding in GDB 17871 please see *note Character Sets::. 17872 17873 If the optional LENGTH argument is given, the string will be 17874 fetched and encoded to the length of characters specified. If 17875 the LENGTH argument is not provided, the string will be 17876 fetched and encoded until a null of appropriate width is 17877 found. 17878 17879 17880File: gdb.info, Node: Types In Python, Next: Pretty Printing API, Prev: Values From Inferior, Up: Python API 17881 1788223.2.2.4 Types In Python 17883........................ 17884 17885GDB represents types from the inferior using the class `gdb.Type'. 17886 17887 The following type-related functions are available in the `gdb' 17888module: 17889 17890 -- Function: lookup_type name [block] 17891 This function looks up a type by name. NAME is the name of the 17892 type to look up. It must be a string. 17893 17894 If BLOCK is given, then NAME is looked up in that scope. 17895 Otherwise, it is searched for globally. 17896 17897 Ordinarily, this function will return an instance of `gdb.Type'. 17898 If the named type cannot be found, it will throw an exception. 17899 17900 An instance of `Type' has the following attributes: 17901 17902 -- Instance Variable of Type: code 17903 The type code for this type. The type code will be one of the 17904 `TYPE_CODE_' constants defined below. 17905 17906 -- Instance Variable of Type: sizeof 17907 The size of this type, in target `char' units. Usually, a 17908 target's `char' type will be an 8-bit byte. However, on some 17909 unusual platforms, this type may have a different size. 17910 17911 -- Instance Variable of Type: tag 17912 The tag name for this type. The tag name is the name after 17913 `struct', `union', or `enum' in C and C++; not all languages 17914 have this concept. If this type has no tag name, then `None' 17915 is returned. 17916 17917 The following methods are provided: 17918 17919 -- Method on Type: fields 17920 For structure and union types, this method returns the 17921 fields. Range types have two fields, the minimum and maximum 17922 values. Enum types have one field per enum constant. 17923 Function and method types have one field per parameter. The 17924 base types of C++ classes are also represented as fields. If 17925 the type has no fields, or does not fit into one of these 17926 categories, an empty sequence will be returned. 17927 17928 Each field is an object, with some pre-defined attributes: 17929 `bitpos' 17930 This attribute is not available for `static' fields (as 17931 in C++ or Java). For non-`static' fields, the value is 17932 the bit position of the field. 17933 17934 `name' 17935 The name of the field, or `None' for anonymous fields. 17936 17937 `artificial' 17938 This is `True' if the field is artificial, usually 17939 meaning that it was provided by the compiler and not the 17940 user. This attribute is always provided, and is `False' 17941 if the field is not artificial. 17942 17943 `is_base_class' 17944 This is `True' if the field represents a base class of a 17945 C++ structure. This attribute is always provided, and 17946 is `False' if the field is not a base class of the type 17947 that is the argument of `fields', or if that type was 17948 not a C++ class. 17949 17950 `bitsize' 17951 If the field is packed, or is a bitfield, then this will 17952 have a non-zero value, which is the size of the field in 17953 bits. Otherwise, this will be zero; in this case the 17954 field's size is given by its type. 17955 17956 `type' 17957 The type of the field. This is usually an instance of 17958 `Type', but it can be `None' in some situations. 17959 17960 -- Method on Type: array N1 [N2] 17961 Return a new `gdb.Type' object which represents an array of 17962 this type. If one argument is given, it is the inclusive 17963 upper bound of the array; in this case the lower bound is 17964 zero. If two arguments are given, the first argument is the 17965 lower bound of the array, and the second argument is the 17966 upper bound of the array. An array's length must not be 17967 negative, but the bounds can be. 17968 17969 -- Method on Type: const 17970 Return a new `gdb.Type' object which represents a 17971 `const'-qualified variant of this type. 17972 17973 -- Method on Type: volatile 17974 Return a new `gdb.Type' object which represents a 17975 `volatile'-qualified variant of this type. 17976 17977 -- Method on Type: unqualified 17978 Return a new `gdb.Type' object which represents an unqualified 17979 variant of this type. That is, the result is neither `const' 17980 nor `volatile'. 17981 17982 -- Method on Type: range 17983 Return a Python `Tuple' object that contains two elements: the 17984 low bound of the argument type and the high bound of that 17985 type. If the type does not have a range, GDB will raise a 17986 `RuntimeError' exception. 17987 17988 -- Method on Type: reference 17989 Return a new `gdb.Type' object which represents a reference 17990 to this type. 17991 17992 -- Method on Type: pointer 17993 Return a new `gdb.Type' object which represents a pointer to 17994 this type. 17995 17996 -- Method on Type: strip_typedefs 17997 Return a new `gdb.Type' that represents the real type, after 17998 removing all layers of typedefs. 17999 18000 -- Method on Type: target 18001 Return a new `gdb.Type' object which represents the target 18002 type of this type. 18003 18004 For a pointer type, the target type is the type of the 18005 pointed-to object. For an array type (meaning C-like 18006 arrays), the target type is the type of the elements of the 18007 array. For a function or method type, the target type is the 18008 type of the return value. For a complex type, the target 18009 type is the type of the elements. For a typedef, the target 18010 type is the aliased type. 18011 18012 If the type does not have a target, this method will throw an 18013 exception. 18014 18015 -- Method on Type: template_argument n [block] 18016 If this `gdb.Type' is an instantiation of a template, this 18017 will return a new `gdb.Type' which represents the type of the 18018 Nth template argument. 18019 18020 If this `gdb.Type' is not a template type, this will throw an 18021 exception. Ordinarily, only C++ code will have template 18022 types. 18023 18024 If BLOCK is given, then NAME is looked up in that scope. 18025 Otherwise, it is searched for globally. 18026 18027 Each type has a code, which indicates what category this type falls 18028into. The available type categories are represented by constants 18029defined in the `gdb' module: 18030 18031`TYPE_CODE_PTR' 18032 The type is a pointer. 18033 18034`TYPE_CODE_ARRAY' 18035 The type is an array. 18036 18037`TYPE_CODE_STRUCT' 18038 The type is a structure. 18039 18040`TYPE_CODE_UNION' 18041 The type is a union. 18042 18043`TYPE_CODE_ENUM' 18044 The type is an enum. 18045 18046`TYPE_CODE_FLAGS' 18047 A bit flags type, used for things such as status registers. 18048 18049`TYPE_CODE_FUNC' 18050 The type is a function. 18051 18052`TYPE_CODE_INT' 18053 The type is an integer type. 18054 18055`TYPE_CODE_FLT' 18056 A floating point type. 18057 18058`TYPE_CODE_VOID' 18059 The special type `void'. 18060 18061`TYPE_CODE_SET' 18062 A Pascal set type. 18063 18064`TYPE_CODE_RANGE' 18065 A range type, that is, an integer type with bounds. 18066 18067`TYPE_CODE_STRING' 18068 A string type. Note that this is only used for certain languages 18069 with language-defined string types; C strings are not represented 18070 this way. 18071 18072`TYPE_CODE_BITSTRING' 18073 A string of bits. 18074 18075`TYPE_CODE_ERROR' 18076 An unknown or erroneous type. 18077 18078`TYPE_CODE_METHOD' 18079 A method type, as found in C++ or Java. 18080 18081`TYPE_CODE_METHODPTR' 18082 A pointer-to-member-function. 18083 18084`TYPE_CODE_MEMBERPTR' 18085 A pointer-to-member. 18086 18087`TYPE_CODE_REF' 18088 A reference type. 18089 18090`TYPE_CODE_CHAR' 18091 A character type. 18092 18093`TYPE_CODE_BOOL' 18094 A boolean type. 18095 18096`TYPE_CODE_COMPLEX' 18097 A complex float type. 18098 18099`TYPE_CODE_TYPEDEF' 18100 A typedef to some other type. 18101 18102`TYPE_CODE_NAMESPACE' 18103 A C++ namespace. 18104 18105`TYPE_CODE_DECFLOAT' 18106 A decimal floating point type. 18107 18108`TYPE_CODE_INTERNAL_FUNCTION' 18109 A function internal to GDB. This is the type used to represent 18110 convenience functions. 18111 18112 18113File: gdb.info, Node: Pretty Printing API, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API 18114 1811523.2.2.5 Pretty Printing API 18116............................ 18117 18118An example output is provided (*note Pretty Printing::). 18119 18120 A pretty-printer is just an object that holds a value and implements 18121a specific interface, defined here. 18122 18123 -- Operation on pretty printer: children (self) 18124 GDB will call this method on a pretty-printer to compute the 18125 children of the pretty-printer's value. 18126 18127 This method must return an object conforming to the Python iterator 18128 protocol. Each item returned by the iterator must be a tuple 18129 holding two elements. The first element is the "name" of the 18130 child; the second element is the child's value. The value can be 18131 any Python object which is convertible to a GDB value. 18132 18133 This method is optional. If it does not exist, GDB will act as 18134 though the value has no children. 18135 18136 -- Operation on pretty printer: display_hint (self) 18137 The CLI may call this method and use its result to change the 18138 formatting of a value. The result will also be supplied to an MI 18139 consumer as a `displayhint' attribute of the variable being 18140 printed. 18141 18142 This method is optional. If it does exist, this method must 18143 return a string. 18144 18145 Some display hints are predefined by GDB: 18146 18147 `array' 18148 Indicate that the object being printed is "array-like". The 18149 CLI uses this to respect parameters such as `set print 18150 elements' and `set print array'. 18151 18152 `map' 18153 Indicate that the object being printed is "map-like", and 18154 that the children of this value can be assumed to alternate 18155 between keys and values. 18156 18157 `string' 18158 Indicate that the object being printed is "string-like". If 18159 the printer's `to_string' method returns a Python string of 18160 some kind, then GDB will call its internal language-specific 18161 string-printing function to format the string. For the CLI 18162 this means adding quotation marks, possibly escaping some 18163 characters, respecting `set print elements', and the like. 18164 18165 -- Operation on pretty printer: to_string (self) 18166 GDB will call this method to display the string representation of 18167 the value passed to the object's constructor. 18168 18169 When printing from the CLI, if the `to_string' method exists, then 18170 GDB will prepend its result to the values returned by `children'. 18171 Exactly how this formatting is done is dependent on the display 18172 hint, and may change as more hints are added. Also, depending on 18173 the print settings (*note Print Settings::), the CLI may print 18174 just the result of `to_string' in a stack trace, omitting the 18175 result of `children'. 18176 18177 If this method returns a string, it is printed verbatim. 18178 18179 Otherwise, if this method returns an instance of `gdb.Value', then 18180 GDB prints this value. This may result in a call to another 18181 pretty-printer. 18182 18183 If instead the method returns a Python value which is convertible 18184 to a `gdb.Value', then GDB performs the conversion and prints the 18185 resulting value. Again, this may result in a call to another 18186 pretty-printer. Python scalars (integers, floats, and booleans) 18187 and strings are convertible to `gdb.Value'; other types are not. 18188 18189 Finally, if this method returns `None' then no further operations 18190 are peformed in this method and nothing is printed. 18191 18192 If the result is not one of these types, an exception is raised. 18193 18194 GDB provides a function which can be used to look up the default 18195pretty-printer for a `gdb.Value': 18196 18197 -- Function: default_visualizer value 18198 This function takes a `gdb.Value' object as an argument. If a 18199 pretty-printer for this value exists, then it is returned. If no 18200 such printer exists, then this returns `None'. 18201 18202 18203File: gdb.info, Node: Selecting Pretty-Printers, Next: Disabling Pretty-Printers, Prev: Pretty Printing API, Up: Python API 18204 1820523.2.2.6 Selecting Pretty-Printers 18206.................................. 18207 18208The Python list `gdb.pretty_printers' contains an array of functions or 18209callable objects that have been registered via addition as a 18210pretty-printer. Each `gdb.Progspace' contains a `pretty_printers' 18211attribute. Each `gdb.Objfile' also contains a `pretty_printers' 18212attribute. 18213 18214 A function on one of these lists is passed a single `gdb.Value' 18215argument and should return a pretty-printer object conforming to the 18216interface definition above (*note Pretty Printing API::). If a function 18217cannot create a pretty-printer for the value, it should return `None'. 18218 18219 GDB first checks the `pretty_printers' attribute of each 18220`gdb.Objfile' in the current program space and iteratively calls each 18221enabled function (*note Disabling Pretty-Printers::) in the list for 18222that `gdb.Objfile' until it receives a pretty-printer object. If no 18223pretty-printer is found in the objfile lists, GDB then searches the 18224pretty-printer list of the current program space, calling each enabled 18225function until an object is returned. After these lists have been 18226exhausted, it tries the global `gdb.pretty_printers' list, again 18227calling each enabled function until an object is returned. 18228 18229 The order in which the objfiles are searched is not specified. For a 18230given list, functions are always invoked from the head of the list, and 18231iterated over sequentially until the end of the list, or a printer 18232object is returned. 18233 18234 Here is an example showing how a `std::string' printer might be 18235written: 18236 18237 class StdStringPrinter: 18238 "Print a std::string" 18239 18240 def __init__ (self, val): 18241 self.val = val 18242 18243 def to_string (self): 18244 return self.val['_M_dataplus']['_M_p'] 18245 18246 def display_hint (self): 18247 return 'string' 18248 18249 And here is an example showing how a lookup function for the printer 18250example above might be written. 18251 18252 def str_lookup_function (val): 18253 18254 lookup_tag = val.type.tag 18255 regex = re.compile ("^std::basic_string<char,.*>$") 18256 if lookup_tag == None: 18257 return None 18258 if regex.match (lookup_tag): 18259 return StdStringPrinter (val) 18260 18261 return None 18262 18263 The example lookup function extracts the value's type, and attempts 18264to match it to a type that it can pretty-print. If it is a type the 18265printer can pretty-print, it will return a printer object. If not, it 18266returns `None'. 18267 18268 We recommend that you put your core pretty-printers into a Python 18269package. If your pretty-printers are for use with a library, we 18270further recommend embedding a version number into the package name. 18271This practice will enable GDB to load multiple versions of your 18272pretty-printers at the same time, because they will have different 18273names. 18274 18275 You should write auto-loaded code (*note Auto-loading::) such that it 18276can be evaluated multiple times without changing its meaning. An ideal 18277auto-load file will consist solely of `import's of your printer 18278modules, followed by a call to a register pretty-printers with the 18279current objfile. 18280 18281 Taken as a whole, this approach will scale nicely to multiple 18282inferiors, each potentially using a different library version. 18283Embedding a version number in the Python package name will ensure that 18284GDB is able to load both sets of printers simultaneously. Then, 18285because the search for pretty-printers is done by objfile, and because 18286your auto-loaded code took care to register your library's printers 18287with a specific objfile, GDB will find the correct printers for the 18288specific version of the library used by each inferior. 18289 18290 To continue the `std::string' example (*note Pretty Printing API::), 18291this code might appear in `gdb.libstdcxx.v6': 18292 18293 def register_printers (objfile): 18294 objfile.pretty_printers.add (str_lookup_function) 18295 18296And then the corresponding contents of the auto-load file would be: 18297 18298 import gdb.libstdcxx.v6 18299 gdb.libstdcxx.v6.register_printers (gdb.current_objfile ()) 18300 18301 18302File: gdb.info, Node: Disabling Pretty-Printers, Next: Inferiors In Python, Prev: Selecting Pretty-Printers, Up: Python API 18303 1830423.2.2.7 Disabling Pretty-Printers 18305.................................. 18306 18307For various reasons a pretty-printer may not work. For example, the 18308underlying data structure may have changed and the pretty-printer is 18309out of date. 18310 18311 The consequences of a broken pretty-printer are severe enough that 18312GDB provides support for enabling and disabling individual printers. 18313For example, if `print frame-arguments' is on, a backtrace can become 18314highly illegible if any argument is printed with a broken printer. 18315 18316 Pretty-printers are enabled and disabled by attaching an `enabled' 18317attribute to the registered function or callable object. If this 18318attribute is present and its value is `False', the printer is disabled, 18319otherwise the printer is enabled. 18320 18321 18322File: gdb.info, Node: Inferiors In Python, Next: Threads In Python, Prev: Disabling Pretty-Printers, Up: Python API 18323 1832423.2.2.8 Inferiors In Python 18325............................ 18326 18327Programs which are being run under GDB are called inferiors (*note 18328Inferiors and Programs::). Python scripts can access information about 18329and manipulate inferiors controlled by GDB via objects of the 18330`gdb.Inferior' class. 18331 18332 The following inferior-related functions are available in the `gdb' 18333module: 18334 18335 -- Function: inferiors 18336 Return a tuple containing all inferior objects. 18337 18338 A `gdb.Inferior' object has the following attributes: 18339 18340 -- Instance Variable of Inferior: num 18341 ID of inferior, as assigned by GDB. 18342 18343 -- Instance Variable of Inferior: pid 18344 Process ID of the inferior, as assigned by the underlying 18345 operating system. 18346 18347 -- Instance Variable of Inferior: was_attached 18348 Boolean signaling whether the inferior was created using 18349 `attach', or started by GDB itself. 18350 18351 A `gdb.Inferior' object has the following methods: 18352 18353 -- Method on Inferior: threads 18354 This method returns a tuple holding all the threads which are 18355 valid when it is called. If there are no valid threads, the 18356 method will return an empty tuple. 18357 18358 -- Method on Inferior: read_memory address length 18359 Read LENGTH bytes of memory from the inferior, starting at 18360 ADDRESS. Returns a buffer object, which behaves much like an 18361 array or a string. It can be modified and given to the 18362 `gdb.write_memory' function. 18363 18364 -- Method on Inferior: write_memory address buffer [length] 18365 Write the contents of BUFFER to the inferior, starting at 18366 ADDRESS. The BUFFER parameter must be a Python object which 18367 supports the buffer protocol, i.e., a string, an array or the 18368 object returned from `gdb.read_memory'. If given, LENGTH 18369 determines the number of bytes from BUFFER to be written. 18370 18371 -- Method on Inferior: search_memory address length pattern 18372 Search a region of the inferior memory starting at ADDRESS 18373 with the given LENGTH using the search pattern supplied in 18374 PATTERN. The PATTERN parameter must be a Python object which 18375 supports the buffer protocol, i.e., a string, an array or the 18376 object returned from `gdb.read_memory'. Returns a Python 18377 `Long' containing the address where the pattern was found, or 18378 `None' if the pattern could not be found. 18379 18380 18381File: gdb.info, Node: Threads In Python, Next: Commands In Python, Prev: Inferiors In Python, Up: Python API 18382 1838323.2.2.9 Threads In Python 18384.......................... 18385 18386Python scripts can access information about, and manipulate inferior 18387threads controlled by GDB, via objects of the `gdb.InferiorThread' 18388class. 18389 18390 The following thread-related functions are available in the `gdb' 18391module: 18392 18393 -- Function: selected_thread 18394 This function returns the thread object for the selected thread. 18395 If there is no selected thread, this will return `None'. 18396 18397 A `gdb.InferiorThread' object has the following attributes: 18398 18399 -- Instance Variable of InferiorThread: num 18400 ID of the thread, as assigned by GDB. 18401 18402 -- Instance Variable of InferiorThread: ptid 18403 ID of the thread, as assigned by the operating system. This 18404 attribute is a tuple containing three integers. The first is 18405 the Process ID (PID); the second is the Lightweight Process 18406 ID (LWPID), and the third is the Thread ID (TID). Either the 18407 LWPID or TID may be 0, which indicates that the operating 18408 system does not use that identifier. 18409 18410 A `gdb.InferiorThread' object has the following methods: 18411 18412 -- Method on InferiorThread: switch 18413 This changes GDB's currently selected thread to the one 18414 represented by this object. 18415 18416 -- Method on InferiorThread: is_stopped 18417 Return a Boolean indicating whether the thread is stopped. 18418 18419 -- Method on InferiorThread: is_running 18420 Return a Boolean indicating whether the thread is running. 18421 18422 -- Method on InferiorThread: is_exited 18423 Return a Boolean indicating whether the thread is exited. 18424 18425 18426File: gdb.info, Node: Commands In Python, Next: Parameters In Python, Prev: Threads In Python, Up: Python API 18427 1842823.2.2.10 Commands In Python 18429............................ 18430 18431You can implement new GDB CLI commands in Python. A CLI command is 18432implemented using an instance of the `gdb.Command' class, most commonly 18433using a subclass. 18434 18435 -- Method on Command: __init__ name COMMAND_CLASS [COMPLETER_CLASS] 18436 [PREFIX] 18437 The object initializer for `Command' registers the new command 18438 with GDB. This initializer is normally invoked from the subclass' 18439 own `__init__' method. 18440 18441 NAME is the name of the command. If NAME consists of multiple 18442 words, then the initial words are looked for as prefix commands. 18443 In this case, if one of the prefix commands does not exist, an 18444 exception is raised. 18445 18446 There is no support for multi-line commands. 18447 18448 COMMAND_CLASS should be one of the `COMMAND_' constants defined 18449 below. This argument tells GDB how to categorize the new command 18450 in the help system. 18451 18452 COMPLETER_CLASS is an optional argument. If given, it should be 18453 one of the `COMPLETE_' constants defined below. This argument 18454 tells GDB how to perform completion for this command. If not 18455 given, GDB will attempt to complete using the object's `complete' 18456 method (see below); if no such method is found, an error will 18457 occur when completion is attempted. 18458 18459 PREFIX is an optional argument. If `True', then the new command 18460 is a prefix command; sub-commands of this command may be 18461 registered. 18462 18463 The help text for the new command is taken from the Python 18464 documentation string for the command's class, if there is one. If 18465 no documentation string is provided, the default value "This 18466 command is not documented." is used. 18467 18468 -- Method on Command: dont_repeat 18469 By default, a GDB command is repeated when the user enters a blank 18470 line at the command prompt. A command can suppress this behavior 18471 by invoking the `dont_repeat' method. This is similar to the user 18472 command `dont-repeat', see *note dont-repeat: Define. 18473 18474 -- Method on Command: invoke argument from_tty 18475 This method is called by GDB when this command is invoked. 18476 18477 ARGUMENT is a string. It is the argument to the command, after 18478 leading and trailing whitespace has been stripped. 18479 18480 FROM_TTY is a boolean argument. When true, this means that the 18481 command was entered by the user at the terminal; when false it 18482 means that the command came from elsewhere. 18483 18484 If this method throws an exception, it is turned into a GDB 18485 `error' call. Otherwise, the return value is ignored. 18486 18487 To break ARGUMENT up into an argv-like string use 18488 `gdb.string_to_argv'. This function behaves identically to GDB's 18489 internal argument lexer `buildargv'. It is recommended to use 18490 this for consistency. Arguments are separated by spaces and may 18491 be quoted. Example: 18492 18493 print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") 18494 ['1', '2 "3', '4 "5', "6 '7"] 18495 18496 18497 -- Method on Command: complete text word 18498 This method is called by GDB when the user attempts completion on 18499 this command. All forms of completion are handled by this method, 18500 that is, the <TAB> and <M-?> key bindings (*note Completion::), 18501 and the `complete' command (*note complete: Help.). 18502 18503 The arguments TEXT and WORD are both strings. TEXT holds the 18504 complete command line up to the cursor's location. WORD holds the 18505 last word of the command line; this is computed using a 18506 word-breaking heuristic. 18507 18508 The `complete' method can return several values: 18509 * If the return value is a sequence, the contents of the 18510 sequence are used as the completions. It is up to `complete' 18511 to ensure that the contents actually do complete the word. A 18512 zero-length sequence is allowed, it means that there were no 18513 completions available. Only string elements of the sequence 18514 are used; other elements in the sequence are ignored. 18515 18516 * If the return value is one of the `COMPLETE_' constants 18517 defined below, then the corresponding GDB-internal completion 18518 function is invoked, and its result is used. 18519 18520 * All other results are treated as though there were no 18521 available completions. 18522 18523 When a new command is registered, it must be declared as a member of 18524some general class of commands. This is used to classify top-level 18525commands in the on-line help system; note that prefix commands are not 18526listed under their own category but rather that of their top-level 18527command. The available classifications are represented by constants 18528defined in the `gdb' module: 18529 18530`COMMAND_NONE' 18531 The command does not belong to any particular class. A command in 18532 this category will not be displayed in any of the help categories. 18533 18534`COMMAND_RUNNING' 18535 The command is related to running the inferior. For example, 18536 `start', `step', and `continue' are in this category. Type `help 18537 running' at the GDB prompt to see a list of commands in this 18538 category. 18539 18540`COMMAND_DATA' 18541 The command is related to data or variables. For example, `call', 18542 `find', and `print' are in this category. Type `help data' at the 18543 GDB prompt to see a list of commands in this category. 18544 18545`COMMAND_STACK' 18546 The command has to do with manipulation of the stack. For example, 18547 `backtrace', `frame', and `return' are in this category. Type 18548 `help stack' at the GDB prompt to see a list of commands in this 18549 category. 18550 18551`COMMAND_FILES' 18552 This class is used for file-related commands. For example, 18553 `file', `list' and `section' are in this category. Type `help 18554 files' at the GDB prompt to see a list of commands in this 18555 category. 18556 18557`COMMAND_SUPPORT' 18558 This should be used for "support facilities", generally meaning 18559 things that are useful to the user when interacting with GDB, but 18560 not related to the state of the inferior. For example, `help', 18561 `make', and `shell' are in this category. Type `help support' at 18562 the GDB prompt to see a list of commands in this category. 18563 18564`COMMAND_STATUS' 18565 The command is an `info'-related command, that is, related to the 18566 state of GDB itself. For example, `info', `macro', and `show' are 18567 in this category. Type `help status' at the GDB prompt to see a 18568 list of commands in this category. 18569 18570`COMMAND_BREAKPOINTS' 18571 The command has to do with breakpoints. For example, `break', 18572 `clear', and `delete' are in this category. Type `help 18573 breakpoints' at the GDB prompt to see a list of commands in this 18574 category. 18575 18576`COMMAND_TRACEPOINTS' 18577 The command has to do with tracepoints. For example, `trace', 18578 `actions', and `tfind' are in this category. Type `help 18579 tracepoints' at the GDB prompt to see a list of commands in this 18580 category. 18581 18582`COMMAND_OBSCURE' 18583 The command is only used in unusual circumstances, or is not of 18584 general interest to users. For example, `checkpoint', `fork', and 18585 `stop' are in this category. Type `help obscure' at the GDB 18586 prompt to see a list of commands in this category. 18587 18588`COMMAND_MAINTENANCE' 18589 The command is only useful to GDB maintainers. The `maintenance' 18590 and `flushregs' commands are in this category. Type `help 18591 internals' at the GDB prompt to see a list of commands in this 18592 category. 18593 18594 A new command can use a predefined completion function, either by 18595specifying it via an argument at initialization, or by returning it 18596from the `complete' method. These predefined completion constants are 18597all defined in the `gdb' module: 18598 18599`COMPLETE_NONE' 18600 This constant means that no completion should be done. 18601 18602`COMPLETE_FILENAME' 18603 This constant means that filename completion should be performed. 18604 18605`COMPLETE_LOCATION' 18606 This constant means that location completion should be done. 18607 *Note Specify Location::. 18608 18609`COMPLETE_COMMAND' 18610 This constant means that completion should examine GDB command 18611 names. 18612 18613`COMPLETE_SYMBOL' 18614 This constant means that completion should be done using symbol 18615 names as the source. 18616 18617 The following code snippet shows how a trivial CLI command can be 18618implemented in Python: 18619 18620 class HelloWorld (gdb.Command): 18621 """Greet the whole world.""" 18622 18623 def __init__ (self): 18624 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) 18625 18626 def invoke (self, arg, from_tty): 18627 print "Hello, World!" 18628 18629 HelloWorld () 18630 18631 The last line instantiates the class, and is necessary to trigger the 18632registration of the command with GDB. Depending on how the Python code 18633is read into GDB, you may need to import the `gdb' module explicitly. 18634 18635 18636File: gdb.info, Node: Parameters In Python, Next: Functions In Python, Prev: Commands In Python, Up: Python API 18637 1863823.2.2.11 Parameters In Python 18639.............................. 18640 18641You can implement new GDB parameters using Python. A new parameter is 18642implemented as an instance of the `gdb.Parameter' class. 18643 18644 Parameters are exposed to the user via the `set' and `show' 18645commands. *Note Help::. 18646 18647 There are many parameters that already exist and can be set in GDB. 18648Two examples are: `set follow fork' and `set charset'. Setting these 18649parameters influences certain behavior in GDB. Similarly, you can 18650define parameters that can be used to influence behavior in custom 18651Python scripts and commands. 18652 18653 -- Method on Parameter: __init__ name COMMAND-CLASS PARAMETER-CLASS 18654 [ENUM-SEQUENCE] 18655 The object initializer for `Parameter' registers the new parameter 18656 with GDB. This initializer is normally invoked from the subclass' 18657 own `__init__' method. 18658 18659 NAME is the name of the new parameter. If NAME consists of 18660 multiple words, then the initial words are looked for as prefix 18661 parameters. An example of this can be illustrated with the `set 18662 print' set of parameters. If NAME is `print foo', then `print' 18663 will be searched as the prefix parameter. In this case the 18664 parameter can subsequently be accessed in GDB as `set print foo'. 18665 18666 If NAME consists of multiple words, and no prefix parameter group 18667 can be found, an exception is raised. 18668 18669 COMMAND-CLASS should be one of the `COMMAND_' constants (*note 18670 Commands In Python::). This argument tells GDB how to categorize 18671 the new parameter in the help system. 18672 18673 PARAMETER-CLASS should be one of the `PARAM_' constants defined 18674 below. This argument tells GDB the type of the new parameter; 18675 this information is used for input validation and completion. 18676 18677 If PARAMETER-CLASS is `PARAM_ENUM', then ENUM-SEQUENCE must be a 18678 sequence of strings. These strings represent the possible values 18679 for the parameter. 18680 18681 If PARAMETER-CLASS is not `PARAM_ENUM', then the presence of a 18682 fourth argument will cause an exception to be thrown. 18683 18684 The help text for the new parameter is taken from the Python 18685 documentation string for the parameter's class, if there is one. 18686 If there is no documentation string, a default value is used. 18687 18688 -- Instance Variable of Parameter: set_doc 18689 If this attribute exists, and is a string, then its value is used 18690 as the help text for this parameter's `set' command. The value is 18691 examined when `Parameter.__init__' is invoked; subsequent changes 18692 have no effect. 18693 18694 -- Instance Variable of Parameter: show_doc 18695 If this attribute exists, and is a string, then its value is used 18696 as the help text for this parameter's `show' command. The value is 18697 examined when `Parameter.__init__' is invoked; subsequent changes 18698 have no effect. 18699 18700 -- Instance Variable of Parameter: value 18701 The `value' attribute holds the underlying value of the parameter. 18702 It can be read and assigned to just as any other attribute. GDB 18703 does validation when assignments are made. 18704 18705 When a new parameter is defined, its type must be specified. The 18706available types are represented by constants defined in the `gdb' 18707module: 18708 18709`PARAM_BOOLEAN' 18710 The value is a plain boolean. The Python boolean values, `True' 18711 and `False' are the only valid values. 18712 18713`PARAM_AUTO_BOOLEAN' 18714 The value has three possible states: true, false, and `auto'. In 18715 Python, true and false are represented using boolean constants, and 18716 `auto' is represented using `None'. 18717 18718`PARAM_UINTEGER' 18719 The value is an unsigned integer. The value of 0 should be 18720 interpreted to mean "unlimited". 18721 18722`PARAM_INTEGER' 18723 The value is a signed integer. The value of 0 should be 18724 interpreted to mean "unlimited". 18725 18726`PARAM_STRING' 18727 The value is a string. When the user modifies the string, any 18728 escape sequences, such as `\t', `\f', and octal escapes, are 18729 translated into corresponding characters and encoded into the 18730 current host charset. 18731 18732`PARAM_STRING_NOESCAPE' 18733 The value is a string. When the user modifies the string, escapes 18734 are passed through untranslated. 18735 18736`PARAM_OPTIONAL_FILENAME' 18737 The value is a either a filename (a string), or `None'. 18738 18739`PARAM_FILENAME' 18740 The value is a filename. This is just like 18741 `PARAM_STRING_NOESCAPE', but uses file names for completion. 18742 18743`PARAM_ZINTEGER' 18744 The value is an integer. This is like `PARAM_INTEGER', except 0 18745 is interpreted as itself. 18746 18747`PARAM_ENUM' 18748 The value is a string, which must be one of a collection string 18749 constants provided when the parameter is created. 18750 18751 18752File: gdb.info, Node: Functions In Python, Next: Progspaces In Python, Prev: Parameters In Python, Up: Python API 18753 1875423.2.2.12 Writing new convenience functions 18755........................................... 18756 18757You can implement new convenience functions (*note Convenience Vars::) 18758in Python. A convenience function is an instance of a subclass of the 18759class `gdb.Function'. 18760 18761 -- Method on Function: __init__ name 18762 The initializer for `Function' registers the new function with 18763 GDB. The argument NAME is the name of the function, a string. 18764 The function will be visible to the user as a convenience variable 18765 of type `internal function', whose name is the same as the given 18766 NAME. 18767 18768 The documentation for the new function is taken from the 18769 documentation string for the new class. 18770 18771 -- Method on Function: invoke *ARGS 18772 When a convenience function is evaluated, its arguments are 18773 converted to instances of `gdb.Value', and then the function's 18774 `invoke' method is called. Note that GDB does not predetermine 18775 the arity of convenience functions. Instead, all available 18776 arguments are passed to `invoke', following the standard Python 18777 calling convention. In particular, a convenience function can 18778 have default values for parameters without ill effect. 18779 18780 The return value of this method is used as its value in the 18781 enclosing expression. If an ordinary Python value is returned, it 18782 is converted to a `gdb.Value' following the usual rules. 18783 18784 The following code snippet shows how a trivial convenience function 18785can be implemented in Python: 18786 18787 class Greet (gdb.Function): 18788 """Return string to greet someone. 18789 Takes a name as argument.""" 18790 18791 def __init__ (self): 18792 super (Greet, self).__init__ ("greet") 18793 18794 def invoke (self, name): 18795 return "Hello, %s!" % name.string () 18796 18797 Greet () 18798 18799 The last line instantiates the class, and is necessary to trigger the 18800registration of the function with GDB. Depending on how the Python 18801code is read into GDB, you may need to import the `gdb' module 18802explicitly. 18803 18804 18805File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API 18806 1880723.2.2.13 Program Spaces In Python 18808.................................. 18809 18810A program space, or "progspace", represents a symbolic view of an 18811address space. It consists of all of the objfiles of the program. 18812*Note Objfiles In Python::. *Note program spaces: Inferiors and 18813Programs, for more details about program spaces. 18814 18815 The following progspace-related functions are available in the `gdb' 18816module: 18817 18818 -- Function: current_progspace 18819 This function returns the program space of the currently selected 18820 inferior. *Note Inferiors and Programs::. 18821 18822 -- Function: progspaces 18823 Return a sequence of all the progspaces currently known to GDB. 18824 18825 Each progspace is represented by an instance of the `gdb.Progspace' 18826class. 18827 18828 -- Instance Variable of Progspace: filename 18829 The file name of the progspace as a string. 18830 18831 -- Instance Variable of Progspace: pretty_printers 18832 The `pretty_printers' attribute is a list of functions. It is 18833 used to look up pretty-printers. A `Value' is passed to each 18834 function in order; if the function returns `None', then the search 18835 continues. Otherwise, the return value should be an object which 18836 is used to format the value. *Note Pretty Printing API::, for more 18837 information. 18838 18839 18840File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API 18841 1884223.2.2.14 Objfiles In Python 18843............................ 18844 18845GDB loads symbols for an inferior from various symbol-containing files 18846(*note Files::). These include the primary executable file, any shared 18847libraries used by the inferior, and any separate debug info files 18848(*note Separate Debug Files::). GDB calls these symbol-containing 18849files "objfiles". 18850 18851 The following objfile-related functions are available in the `gdb' 18852module: 18853 18854 -- Function: current_objfile 18855 When auto-loading a Python script (*note Auto-loading::), GDB sets 18856 the "current objfile" to the corresponding objfile. This function 18857 returns the current objfile. If there is no current objfile, this 18858 function returns `None'. 18859 18860 -- Function: objfiles 18861 Return a sequence of all the objfiles current known to GDB. *Note 18862 Objfiles In Python::. 18863 18864 Each objfile is represented by an instance of the `gdb.Objfile' 18865class. 18866 18867 -- Instance Variable of Objfile: filename 18868 The file name of the objfile as a string. 18869 18870 -- Instance Variable of Objfile: pretty_printers 18871 The `pretty_printers' attribute is a list of functions. It is 18872 used to look up pretty-printers. A `Value' is passed to each 18873 function in order; if the function returns `None', then the search 18874 continues. Otherwise, the return value should be an object which 18875 is used to format the value. *Note Pretty Printing API::, for more 18876 information. 18877 18878 18879File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API 18880 1888123.2.2.15 Accessing inferior stack frames from Python. 18882...................................................... 18883 18884When the debugged program stops, GDB is able to analyze its call stack 18885(*note Stack frames: Frames.). The `gdb.Frame' class represents a 18886frame in the stack. A `gdb.Frame' object is only valid while its 18887corresponding frame exists in the inferior's stack. If you try to use 18888an invalid frame object, GDB will throw a `RuntimeError' exception. 18889 18890 Two `gdb.Frame' objects can be compared for equality with the `==' 18891operator, like: 18892 18893 (gdb) python print gdb.newest_frame() == gdb.selected_frame () 18894 True 18895 18896 The following frame-related functions are available in the `gdb' 18897module: 18898 18899 -- Function: selected_frame 18900 Return the selected frame object. (*note Selecting a Frame: 18901 Selection.). 18902 18903 -- Function: frame_stop_reason_string reason 18904 Return a string explaining the reason why GDB stopped unwinding 18905 frames, as expressed by the given REASON code (an integer, see the 18906 `unwind_stop_reason' method further down in this section). 18907 18908 A `gdb.Frame' object has the following methods: 18909 18910 -- Method on Frame: is_valid 18911 Returns true if the `gdb.Frame' object is valid, false if not. 18912 A frame object can become invalid if the frame it refers to 18913 doesn't exist anymore in the inferior. All `gdb.Frame' 18914 methods will throw an exception if it is invalid at the time 18915 the method is called. 18916 18917 -- Method on Frame: name 18918 Returns the function name of the frame, or `None' if it can't 18919 be obtained. 18920 18921 -- Method on Frame: type 18922 Returns the type of the frame. The value can be one of 18923 `gdb.NORMAL_FRAME', `gdb.DUMMY_FRAME', `gdb.SIGTRAMP_FRAME' 18924 or `gdb.SENTINEL_FRAME'. 18925 18926 -- Method on Frame: unwind_stop_reason 18927 Return an integer representing the reason why it's not 18928 possible to find more frames toward the outermost frame. Use 18929 `gdb.frame_stop_reason_string' to convert the value returned 18930 by this function to a string. 18931 18932 -- Method on Frame: pc 18933 Returns the frame's resume address. 18934 18935 -- Method on Frame: block 18936 Return the frame's code block. *Note Blocks In Python::. 18937 18938 -- Method on Frame: function 18939 Return the symbol for the function corresponding to this 18940 frame. *Note Symbols In Python::. 18941 18942 -- Method on Frame: older 18943 Return the frame that called this frame. 18944 18945 -- Method on Frame: newer 18946 Return the frame called by this frame. 18947 18948 -- Method on Frame: find_sal 18949 Return the frame's symtab and line object. *Note Symbol 18950 Tables In Python::. 18951 18952 -- Method on Frame: read_var variable [block] 18953 Return the value of VARIABLE in this frame. If the optional 18954 argument BLOCK is provided, search for the variable from that 18955 block; otherwise start at the frame's current block (which is 18956 determined by the frame's current program counter). VARIABLE 18957 must be a string or a `gdb.Symbol' object. BLOCK must be a 18958 `gdb.Block' object. 18959 18960 -- Method on Frame: select 18961 Set this frame to be the selected frame. *Note Examining the 18962 Stack: Stack. 18963 18964 18965File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API 18966 1896723.2.2.16 Accessing frame blocks from Python. 18968............................................. 18969 18970Within each frame, GDB maintains information on each block stored in 18971that frame. These blocks are organized hierarchically, and are 18972represented individually in Python as a `gdb.Block'. Please see *note 18973Frames In Python::, for a more in-depth discussion on frames. 18974Furthermore, see *note Examining the Stack: Stack, for more detailed 18975technical information on GDB's book-keeping of the stack. 18976 18977 The following block-related functions are available in the `gdb' 18978module: 18979 18980 -- Function: block_for_pc pc 18981 Return the `gdb.Block' containing the given PC value. If the 18982 block cannot be found for the PC value specified, the function 18983 will return `None'. 18984 18985 A `gdb.Block' object has the following attributes: 18986 18987 -- Instance Variable of Block: start 18988 The start address of the block. This attribute is not 18989 writable. 18990 18991 -- Instance Variable of Block: end 18992 The end address of the block. This attribute is not writable. 18993 18994 -- Instance Variable of Block: function 18995 The name of the block represented as a `gdb.Symbol'. If the 18996 block is not named, then this attribute holds `None'. This 18997 attribute is not writable. 18998 18999 -- Instance Variable of Block: superblock 19000 The block containing this block. If this parent block does 19001 not exist, this attribute holds `None'. This attribute is 19002 not writable. 19003 19004 19005File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API 19006 1900723.2.2.17 Python representation of Symbols. 19008........................................... 19009 19010GDB represents every variable, function and type as an entry in a 19011symbol table. *Note Examining the Symbol Table: Symbols. Similarly, 19012Python represents these symbols in GDB with the `gdb.Symbol' object. 19013 19014 The following symbol-related functions are available in the `gdb' 19015module: 19016 19017 -- Function: lookup_symbol name [block] [domain] 19018 This function searches for a symbol by name. The search scope can 19019 be restricted to the parameters defined in the optional domain and 19020 block arguments. 19021 19022 NAME is the name of the symbol. It must be a string. The 19023 optional BLOCK argument restricts the search to symbols visible in 19024 that BLOCK. The BLOCK argument must be a `gdb.Block' object. The 19025 optional DOMAIN argument restricts the search to the domain type. 19026 The DOMAIN argument must be a domain constant defined in the `gdb' 19027 module and described later in this chapter. 19028 19029 A `gdb.Symbol' object has the following attributes: 19030 19031 -- Instance Variable of Symbol: symtab 19032 The symbol table in which the symbol appears. This attribute 19033 is represented as a `gdb.Symtab' object. *Note Symbol Tables 19034 In Python::. This attribute is not writable. 19035 19036 -- Instance Variable of Symbol: name 19037 The name of the symbol as a string. This attribute is not 19038 writable. 19039 19040 -- Instance Variable of Symbol: linkage_name 19041 The name of the symbol, as used by the linker (i.e., may be 19042 mangled). This attribute is not writable. 19043 19044 -- Instance Variable of Symbol: print_name 19045 The name of the symbol in a form suitable for output. This 19046 is either `name' or `linkage_name', depending on whether the 19047 user asked GDB to display demangled or mangled names. 19048 19049 -- Instance Variable of Symbol: addr_class 19050 The address class of the symbol. This classifies how to find 19051 the value of a symbol. Each address class is a constant 19052 defined in the `gdb' module and described later in this 19053 chapter. 19054 19055 -- Instance Variable of Symbol: is_argument 19056 `True' if the symbol is an argument of a function. 19057 19058 -- Instance Variable of Symbol: is_constant 19059 `True' if the symbol is a constant. 19060 19061 -- Instance Variable of Symbol: is_function 19062 `True' if the symbol is a function or a method. 19063 19064 -- Instance Variable of Symbol: is_variable 19065 `True' if the symbol is a variable. 19066 19067 The available domain categories in `gdb.Symbol' are represented as 19068constants in the `gdb' module: 19069 19070`SYMBOL_UNDEF_DOMAIN' 19071 This is used when a domain has not been discovered or none of the 19072 following domains apply. This usually indicates an error either 19073 in the symbol information or in GDB's handling of symbols. 19074 19075`SYMBOL_VAR_DOMAIN' 19076 This domain contains variables, function names, typedef names and 19077 enum type values. 19078 19079`SYMBOL_STRUCT_DOMAIN' 19080 This domain holds struct, union and enum type names. 19081 19082`SYMBOL_LABEL_DOMAIN' 19083 This domain contains names of labels (for gotos). 19084 19085`SYMBOL_VARIABLES_DOMAIN' 19086 This domain holds a subset of the `SYMBOLS_VAR_DOMAIN'; it 19087 contains everything minus functions and types. 19088 19089`SYMBOL_FUNCTION_DOMAIN' 19090 This domain contains all functions. 19091 19092`SYMBOL_TYPES_DOMAIN' 19093 This domain contains all types. 19094 19095 The available address class categories in `gdb.Symbol' are 19096represented as constants in the `gdb' module: 19097 19098`SYMBOL_LOC_UNDEF' 19099 If this is returned by address class, it indicates an error either 19100 in the symbol information or in GDB's handling of symbols. 19101 19102`SYMBOL_LOC_CONST' 19103 Value is constant int. 19104 19105`SYMBOL_LOC_STATIC' 19106 Value is at a fixed address. 19107 19108`SYMBOL_LOC_REGISTER' 19109 Value is in a register. 19110 19111`SYMBOL_LOC_ARG' 19112 Value is an argument. This value is at the offset stored within 19113 the symbol inside the frame's argument list. 19114 19115`SYMBOL_LOC_REF_ARG' 19116 Value address is stored in the frame's argument list. Just like 19117 `LOC_ARG' except that the value's address is stored at the offset, 19118 not the value itself. 19119 19120`SYMBOL_LOC_REGPARM_ADDR' 19121 Value is a specified register. Just like `LOC_REGISTER' except 19122 the register holds the address of the argument instead of the 19123 argument itself. 19124 19125`SYMBOL_LOC_LOCAL' 19126 Value is a local variable. 19127 19128`SYMBOL_LOC_TYPEDEF' 19129 Value not used. Symbols in the domain `SYMBOL_STRUCT_DOMAIN' all 19130 have this class. 19131 19132`SYMBOL_LOC_BLOCK' 19133 Value is a block. 19134 19135`SYMBOL_LOC_CONST_BYTES' 19136 Value is a byte-sequence. 19137 19138`SYMBOL_LOC_UNRESOLVED' 19139 Value is at a fixed address, but the address of the variable has 19140 to be determined from the minimal symbol table whenever the 19141 variable is referenced. 19142 19143`SYMBOL_LOC_OPTIMIZED_OUT' 19144 The value does not actually exist in the program. 19145 19146`SYMBOL_LOC_COMPUTED' 19147 The value's address is a computed location. 19148 19149 19150File: gdb.info, Node: Symbol Tables In Python, Next: Lazy Strings In Python, Prev: Symbols In Python, Up: Python API 19151 1915223.2.2.18 Symbol table representation in Python. 19153................................................ 19154 19155Access to symbol table data maintained by GDB on the inferior is 19156exposed to Python via two objects: `gdb.Symtab_and_line' and 19157`gdb.Symtab'. Symbol table and line data for a frame is returned from 19158the `find_sal' method in `gdb.Frame' object. *Note Frames In Python::. 19159 19160 For more information on GDB's symbol table management, see *note 19161Examining the Symbol Table: Symbols, for more information. 19162 19163 A `gdb.Symtab_and_line' object has the following attributes: 19164 19165 -- Instance Variable of Symtab_and_line: symtab 19166 The symbol table object (`gdb.Symtab') for this frame. This 19167 attribute is not writable. 19168 19169 -- Instance Variable of Symtab_and_line: pc 19170 Indicates the current program counter address. This 19171 attribute is not writable. 19172 19173 -- Instance Variable of Symtab_and_line: line 19174 Indicates the current line number for this object. This 19175 attribute is not writable. 19176 19177 A `gdb.Symtab' object has the following attributes: 19178 19179 -- Instance Variable of Symtab: filename 19180 The symbol table's source filename. This attribute is not 19181 writable. 19182 19183 -- Instance Variable of Symtab: objfile 19184 The symbol table's backing object file. *Note Objfiles In 19185 Python::. This attribute is not writable. 19186 19187 The following methods are provided: 19188 19189 -- Method on Symtab: fullname 19190 Return the symbol table's source absolute file name. 19191 19192 19193File: gdb.info, Node: Breakpoints In Python, Prev: Lazy Strings In Python, Up: Python API 19194 1919523.2.2.19 Manipulating breakpoints using Python 19196............................................... 19197 19198Python code can manipulate breakpoints via the `gdb.Breakpoint' class. 19199 19200 -- Method on Breakpoint: __init__ spec [type] [wp_class] 19201 Create a new breakpoint. SPEC is a string naming the location of 19202 the breakpoint, or an expression that defines a watchpoint. The 19203 contents can be any location recognized by the `break' command, or 19204 in the case of a watchpoint, by the `watch' command. The optional 19205 TYPE denotes the breakpoint to create from the types defined later 19206 in this chapter. This argument can be either: `BP_BREAKPOINT' or 19207 `BP_WATCHPOINT'. TYPE defaults to `BP_BREAKPOINT'. The optional 19208 WP_CLASS argument defines the class of watchpoint to create, if 19209 TYPE is defined as `BP_WATCHPOINT'. If a watchpoint class is not 19210 provided, it is assumed to be a WP_WRITE class. 19211 19212 The available watchpoint types represented by constants are defined 19213in the `gdb' module: 19214 19215`WP_READ' 19216 Read only watchpoint. 19217 19218`WP_WRITE' 19219 Write only watchpoint. 19220 19221`WP_ACCESS' 19222 Read/Write watchpoint. 19223 19224 -- Method on Breakpoint: is_valid 19225 Return `True' if this `Breakpoint' object is valid, `False' 19226 otherwise. A `Breakpoint' object can become invalid if the user 19227 deletes the breakpoint. In this case, the object still exists, 19228 but the underlying breakpoint does not. In the cases of 19229 watchpoint scope, the watchpoint remains valid even if execution 19230 of the inferior leaves the scope of that watchpoint. 19231 19232 -- Instance Variable of Breakpoint: enabled 19233 This attribute is `True' if the breakpoint is enabled, and `False' 19234 otherwise. This attribute is writable. 19235 19236 -- Instance Variable of Breakpoint: silent 19237 This attribute is `True' if the breakpoint is silent, and `False' 19238 otherwise. This attribute is writable. 19239 19240 Note that a breakpoint can also be silent if it has commands and 19241 the first command is `silent'. This is not reported by the 19242 `silent' attribute. 19243 19244 -- Instance Variable of Breakpoint: thread 19245 If the breakpoint is thread-specific, this attribute holds the 19246 thread id. If the breakpoint is not thread-specific, this 19247 attribute is `None'. This attribute is writable. 19248 19249 -- Instance Variable of Breakpoint: task 19250 If the breakpoint is Ada task-specific, this attribute holds the 19251 Ada task id. If the breakpoint is not task-specific (or the 19252 underlying language is not Ada), this attribute is `None'. This 19253 attribute is writable. 19254 19255 -- Instance Variable of Breakpoint: ignore_count 19256 This attribute holds the ignore count for the breakpoint, an 19257 integer. This attribute is writable. 19258 19259 -- Instance Variable of Breakpoint: number 19260 This attribute holds the breakpoint's number -- the identifier 19261 used by the user to manipulate the breakpoint. This attribute is 19262 not writable. 19263 19264 -- Instance Variable of Breakpoint: type 19265 This attribute holds the breakpoint's type -- the identifier used 19266 to determine the actual breakpoint type or use-case. This 19267 attribute is not writable. 19268 19269 The available types are represented by constants defined in the `gdb' 19270module: 19271 19272`BP_BREAKPOINT' 19273 Normal code breakpoint. 19274 19275`BP_WATCHPOINT' 19276 Watchpoint breakpoint. 19277 19278`BP_HARDWARE_WATCHPOINT' 19279 Hardware assisted watchpoint. 19280 19281`BP_READ_WATCHPOINT' 19282 Hardware assisted read watchpoint. 19283 19284`BP_ACCESS_WATCHPOINT' 19285 Hardware assisted access watchpoint. 19286 19287 -- Instance Variable of Breakpoint: hit_count 19288 This attribute holds the hit count for the breakpoint, an integer. 19289 This attribute is writable, but currently it can only be set to 19290 zero. 19291 19292 -- Instance Variable of Breakpoint: location 19293 This attribute holds the location of the breakpoint, as specified 19294 by the user. It is a string. If the breakpoint does not have a 19295 location (that is, it is a watchpoint) the attribute's value is 19296 `None'. This attribute is not writable. 19297 19298 -- Instance Variable of Breakpoint: expression 19299 This attribute holds a breakpoint expression, as specified by the 19300 user. It is a string. If the breakpoint does not have an 19301 expression (the breakpoint is not a watchpoint) the attribute's 19302 value is `None'. This attribute is not writable. 19303 19304 -- Instance Variable of Breakpoint: condition 19305 This attribute holds the condition of the breakpoint, as specified 19306 by the user. It is a string. If there is no condition, this 19307 attribute's value is `None'. This attribute is writable. 19308 19309 -- Instance Variable of Breakpoint: commands 19310 This attribute holds the commands attached to the breakpoint. If 19311 there are commands, this attribute's value is a string holding all 19312 the commands, separated by newlines. If there are no commands, 19313 this attribute is `None'. This attribute is not writable. 19314 19315 19316File: gdb.info, Node: Lazy Strings In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API 19317 1931823.2.2.20 Python representation of lazy strings. 19319................................................ 19320 19321A "lazy string" is a string whose contents is not retrieved or encoded 19322until it is needed. 19323 19324 A `gdb.LazyString' is represented in GDB as an `address' that points 19325to a region of memory, an `encoding' that will be used to encode that 19326region of memory, and a `length' to delimit the region of memory that 19327represents the string. The difference between a `gdb.LazyString' and a 19328string wrapped within a `gdb.Value' is that a `gdb.LazyString' will be 19329treated differently by GDB when printing. A `gdb.LazyString' is 19330retrieved and encoded during printing, while a `gdb.Value' wrapping a 19331string is immediately retrieved and encoded on creation. 19332 19333 A `gdb.LazyString' object has the following functions: 19334 19335 -- Method on LazyString: value 19336 Convert the `gdb.LazyString' to a `gdb.Value'. This value will 19337 point to the string in memory, but will lose all the delayed 19338 retrieval, encoding and handling that GDB applies to a 19339 `gdb.LazyString'. 19340 19341 -- Instance Variable of LazyString: address 19342 This attribute holds the address of the string. This attribute is 19343 not writable. 19344 19345 -- Instance Variable of LazyString: length 19346 This attribute holds the length of the string in characters. If 19347 the length is -1, then the string will be fetched and encoded up 19348 to the first null of appropriate width. This attribute is not 19349 writable. 19350 19351 -- Instance Variable of LazyString: encoding 19352 This attribute holds the encoding that will be applied to the 19353 string when the string is printed by GDB. If the encoding is not 19354 set, or contains an empty string, then GDB will select the most 19355 appropriate encoding when the string is printed. This attribute 19356 is not writable. 19357 19358 -- Instance Variable of LazyString: type 19359 This attribute holds the type that is represented by the lazy 19360 string's type. For a lazy string this will always be a pointer 19361 type. To resolve this to the lazy string's character type, use 19362 the type's `target' method. *Note Types In Python::. This 19363 attribute is not writable. 19364 19365 19366File: gdb.info, Node: Auto-loading, Prev: Python API, Up: Python 19367 1936823.2.3 Auto-loading 19369------------------- 19370 19371When a new object file is read (for example, due to the `file' command, 19372or because the inferior has loaded a shared library), GDB will look for 19373Python support scripts in several ways: `OBJFILE-gdb.py' and 19374`.debug_gdb_scripts' section. 19375 19376* Menu: 19377 19378* objfile-gdb.py file:: The `OBJFILE-gdb.py' file 19379* .debug_gdb_scripts section:: The `.debug_gdb_scripts' section 19380* Which flavor to choose?:: 19381 19382 The auto-loading feature is useful for supplying application-specific 19383debugging commands and scripts. 19384 19385 Auto-loading can be enabled or disabled. 19386 19387`maint set python auto-load [yes|no]' 19388 Enable or disable the Python auto-loading feature. 19389 19390`maint show python auto-load' 19391 Show whether Python auto-loading is enabled or disabled. 19392 19393 When reading an auto-loaded file, GDB sets the "current objfile". 19394This is available via the `gdb.current_objfile' function (*note 19395Objfiles In Python::). This can be useful for registering 19396objfile-specific pretty-printers. 19397 19398 19399File: gdb.info, Node: objfile-gdb.py file, Next: .debug_gdb_scripts section, Up: Auto-loading 19400 1940123.2.3.1 The `OBJFILE-gdb.py' file 19402.................................. 19403 19404When a new object file is read, GDB looks for a file named 19405`OBJFILE-gdb.py', where OBJFILE is the object file's real name, formed 19406by ensuring that the file name is absolute, following all symlinks, and 19407resolving `.' and `..' components. If this file exists and is 19408readable, GDB will evaluate it as a Python script. 19409 19410 If this file does not exist, and if the parameter 19411`debug-file-directory' is set (*note Separate Debug Files::), then GDB 19412will look for REAL-NAME in all of the directories mentioned in the 19413value of `debug-file-directory'. 19414 19415 Finally, if this file does not exist, then GDB will look for a file 19416named `DATA-DIRECTORY/python/auto-load/REAL-NAME', where DATA-DIRECTORY 19417is GDB's data directory (available via `show data-directory', *note 19418Data Files::), and REAL-NAME is the object file's real name, as 19419described above. 19420 19421 GDB does not track which files it has already auto-loaded this way. 19422GDB will load the associated script every time the corresponding 19423OBJFILE is opened. So your `-gdb.py' file should be careful to avoid 19424errors if it is evaluated more than once. 19425 19426 19427File: gdb.info, Node: .debug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdb.py file, Up: Auto-loading 19428 1942923.2.3.2 The `.debug_gdb_scripts' section 19430......................................... 19431 19432For systems using file formats like ELF and COFF, when GDB loads a new 19433object file it will look for a special section named 19434`.debug_gdb_scripts'. If this section exists, its contents is a list 19435of names of scripts to load. 19436 19437 GDB will look for each specified script file first in the current 19438directory and then along the source search path (*note Specifying 19439Source Directories: Source Path.), except that `$cdir' is not searched, 19440since the compilation directory is not relevant to scripts. 19441 19442 Entries can be placed in section `.debug_gdb_scripts' with, for 19443example, this GCC macro: 19444 19445 /* Note: The "MS" section flags are to remove duplicates. */ 19446 #define DEFINE_GDB_SCRIPT(script_name) \ 19447 asm("\ 19448 .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ 19449 .byte 1\n\ 19450 .asciz \"" script_name "\"\n\ 19451 .popsection \n\ 19452 "); 19453 19454Then one can reference the macro in a header or source file like this: 19455 19456 DEFINE_GDB_SCRIPT ("my-app-scripts.py") 19457 19458 The script name may include directories if desired. 19459 19460 If the macro is put in a header, any application or library using 19461this header will get a reference to the specified script. 19462 19463 19464File: gdb.info, Node: Which flavor to choose?, Prev: .debug_gdb_scripts section, Up: Auto-loading 19465 1946623.2.3.3 Which flavor to choose? 19467................................ 19468 19469Given the multiple ways of auto-loading Python scripts, it might not 19470always be clear which one to choose. This section provides some 19471guidance. 19472 19473 Benefits of the `-gdb.py' way: 19474 19475 * Can be used with file formats that don't support multiple sections. 19476 19477 * Ease of finding scripts for public libraries. 19478 19479 Scripts specified in the `.debug_gdb_scripts' section are searched 19480 for in the source search path. For publicly installed libraries, 19481 e.g., `libstdc++', there typically isn't a source directory in 19482 which to find the script. 19483 19484 * Doesn't require source code additions. 19485 19486 Benefits of the `.debug_gdb_scripts' way: 19487 19488 * Works with static linking. 19489 19490 Scripts for libraries done the `-gdb.py' way require an objfile to 19491 trigger their loading. When an application is statically linked 19492 the only objfile available is the executable, and it is cumbersome 19493 to attach all the scripts from all the input libraries to the 19494 executable's `-gdb.py' script. 19495 19496 * Works with classes that are entirely inlined. 19497 19498 Some classes can be entirely inlined, and thus there may not be an 19499 associated shared library to attach a `-gdb.py' script to. 19500 19501 * Scripts needn't be copied out of the source tree. 19502 19503 In some circumstances, apps can be built out of large collections 19504 of internal libraries, and the build infrastructure necessary to 19505 install the `-gdb.py' scripts in a place where GDB can find them is 19506 cumbersome. It may be easier to specify the scripts in the 19507 `.debug_gdb_scripts' section as relative paths, and add a path to 19508 the top of the source tree to the source search path. 19509 19510 19511File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top 19512 1951324 Command Interpreters 19514*********************** 19515 19516GDB supports multiple command interpreters, and some command 19517infrastructure to allow users or user interface writers to switch 19518between interpreters or run commands in other interpreters. 19519 19520 GDB currently supports two command interpreters, the console 19521interpreter (sometimes called the command-line interpreter or CLI) and 19522the machine interface interpreter (or GDB/MI). This manual describes 19523both of these interfaces in great detail. 19524 19525 By default, GDB will start with the console interpreter. However, 19526the user may choose to start GDB with another interpreter by specifying 19527the `-i' or `--interpreter' startup options. Defined interpreters 19528include: 19529 19530`console' 19531 The traditional console or command-line interpreter. This is the 19532 most often used interpreter with GDB. With no interpreter 19533 specified at runtime, GDB will use this interpreter. 19534 19535`mi' 19536 The newest GDB/MI interface (currently `mi2'). Used primarily by 19537 programs wishing to use GDB as a backend for a debugger GUI or an 19538 IDE. For more information, see *note The GDB/MI Interface: GDB/MI. 19539 19540`mi2' 19541 The current GDB/MI interface. 19542 19543`mi1' 19544 The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. 19545 19546 19547 The interpreter being used by GDB may not be dynamically switched at 19548runtime. Although possible, this could lead to a very precarious 19549situation. Consider an IDE using GDB/MI. If a user enters the command 19550"interpreter-set console" in a console view, GDB would switch to using 19551the console interpreter, rendering the IDE inoperable! 19552 19553 Although you may only choose a single interpreter at startup, you 19554may execute commands in any interpreter from the current interpreter 19555using the appropriate command. If you are running the console 19556interpreter, simply use the `interpreter-exec' command: 19557 19558 interpreter-exec mi "-data-list-register-names" 19559 19560 GDB/MI has a similar command, although it is only available in 19561versions of GDB which support GDB/MI version 2 (or greater). 19562 19563 19564File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top 19565 1956625 GDB Text User Interface 19567************************** 19568 19569* Menu: 19570 19571* TUI Overview:: TUI overview 19572* TUI Keys:: TUI key bindings 19573* TUI Single Key Mode:: TUI single key mode 19574* TUI Commands:: TUI-specific commands 19575* TUI Configuration:: TUI configuration variables 19576 19577 The GDB Text User Interface (TUI) is a terminal interface which uses 19578the `curses' library to show the source file, the assembly output, the 19579program registers and GDB commands in separate text windows. The TUI 19580mode is supported only on platforms where a suitable version of the 19581`curses' library is available. 19582 19583 The TUI mode is enabled by default when you invoke GDB as either 19584`gdbtui' or `gdb -tui'. You can also switch in and out of TUI mode 19585while GDB runs by using various TUI commands and key bindings, such as 19586`C-x C-a'. *Note TUI Key Bindings: TUI Keys. 19587 19588 19589File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI 19590 1959125.1 TUI Overview 19592================= 19593 19594In TUI mode, GDB can display several text windows: 19595 19596_command_ 19597 This window is the GDB command window with the GDB prompt and the 19598 GDB output. The GDB input is still managed using readline. 19599 19600_source_ 19601 The source window shows the source file of the program. The 19602 current line and active breakpoints are displayed in this window. 19603 19604_assembly_ 19605 The assembly window shows the disassembly output of the program. 19606 19607_register_ 19608 This window shows the processor registers. Registers are 19609 highlighted when their values change. 19610 19611 The source and assembly windows show the current program position by 19612highlighting the current line and marking it with a `>' marker. 19613Breakpoints are indicated with two markers. The first marker indicates 19614the breakpoint type: 19615 19616`B' 19617 Breakpoint which was hit at least once. 19618 19619`b' 19620 Breakpoint which was never hit. 19621 19622`H' 19623 Hardware breakpoint which was hit at least once. 19624 19625`h' 19626 Hardware breakpoint which was never hit. 19627 19628 The second marker indicates whether the breakpoint is enabled or not: 19629 19630`+' 19631 Breakpoint is enabled. 19632 19633`-' 19634 Breakpoint is disabled. 19635 19636 The source, assembly and register windows are updated when the 19637current thread changes, when the frame changes, or when the program 19638counter changes. 19639 19640 These windows are not all visible at the same time. The command 19641window is always visible. The others can be arranged in several 19642layouts: 19643 19644 * source only, 19645 19646 * assembly only, 19647 19648 * source and assembly, 19649 19650 * source and registers, or 19651 19652 * assembly and registers. 19653 19654 A status line above the command window shows the following 19655information: 19656 19657_target_ 19658 Indicates the current GDB target. (*note Specifying a Debugging 19659 Target: Targets.). 19660 19661_process_ 19662 Gives the current process or thread number. When no process is 19663 being debugged, this field is set to `No process'. 19664 19665_function_ 19666 Gives the current function name for the selected frame. The name 19667 is demangled if demangling is turned on (*note Print Settings::). 19668 When there is no symbol corresponding to the current program 19669 counter, the string `??' is displayed. 19670 19671_line_ 19672 Indicates the current line number for the selected frame. When 19673 the current line number is not known, the string `??' is displayed. 19674 19675_pc_ 19676 Indicates the current program counter address. 19677 19678 19679File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI 19680 1968125.2 TUI Key Bindings 19682===================== 19683 19684The TUI installs several key bindings in the readline keymaps (*note 19685Command Line Editing::). The following key bindings are installed for 19686both TUI mode and the GDB standard mode. 19687 19688`C-x C-a' 19689`C-x a' 19690`C-x A' 19691 Enter or leave the TUI mode. When leaving the TUI mode, the 19692 curses window management stops and GDB operates using its standard 19693 mode, writing on the terminal directly. When reentering the TUI 19694 mode, control is given back to the curses windows. The screen is 19695 then refreshed. 19696 19697`C-x 1' 19698 Use a TUI layout with only one window. The layout will either be 19699 `source' or `assembly'. When the TUI mode is not active, it will 19700 switch to the TUI mode. 19701 19702 Think of this key binding as the Emacs `C-x 1' binding. 19703 19704`C-x 2' 19705 Use a TUI layout with at least two windows. When the current 19706 layout already has two windows, the next layout with two windows 19707 is used. When a new layout is chosen, one window will always be 19708 common to the previous layout and the new one. 19709 19710 Think of it as the Emacs `C-x 2' binding. 19711 19712`C-x o' 19713 Change the active window. The TUI associates several key bindings 19714 (like scrolling and arrow keys) with the active window. This 19715 command gives the focus to the next TUI window. 19716 19717 Think of it as the Emacs `C-x o' binding. 19718 19719`C-x s' 19720 Switch in and out of the TUI SingleKey mode that binds single keys 19721 to GDB commands (*note TUI Single Key Mode::). 19722 19723 The following key bindings only work in the TUI mode: 19724 19725<PgUp> 19726 Scroll the active window one page up. 19727 19728<PgDn> 19729 Scroll the active window one page down. 19730 19731<Up> 19732 Scroll the active window one line up. 19733 19734<Down> 19735 Scroll the active window one line down. 19736 19737<Left> 19738 Scroll the active window one column left. 19739 19740<Right> 19741 Scroll the active window one column right. 19742 19743`C-L' 19744 Refresh the screen. 19745 19746 Because the arrow keys scroll the active window in the TUI mode, they 19747are not available for their normal use by readline unless the command 19748window has the focus. When another window is active, you must use 19749other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to 19750control the command window. 19751 19752 19753File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI 19754 1975525.3 TUI Single Key Mode 19756======================== 19757 19758The TUI also provides a "SingleKey" mode, which binds several 19759frequently used GDB commands to single keys. Type `C-x s' to switch 19760into this mode, where the following key bindings are used: 19761 19762`c' 19763 continue 19764 19765`d' 19766 down 19767 19768`f' 19769 finish 19770 19771`n' 19772 next 19773 19774`q' 19775 exit the SingleKey mode. 19776 19777`r' 19778 run 19779 19780`s' 19781 step 19782 19783`u' 19784 up 19785 19786`v' 19787 info locals 19788 19789`w' 19790 where 19791 19792 Other keys temporarily switch to the GDB command prompt. The key 19793that was pressed is inserted in the editing buffer so that it is 19794possible to type most GDB commands without interaction with the TUI 19795SingleKey mode. Once the command is entered the TUI SingleKey mode is 19796restored. The only way to permanently leave this mode is by typing `q' 19797or `C-x s'. 19798 19799 19800File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI 19801 1980225.4 TUI-specific Commands 19803========================== 19804 19805The TUI has specific commands to control the text windows. These 19806commands are always available, even when GDB is not in the TUI mode. 19807When GDB is in the standard mode, most of these commands will 19808automatically switch to the TUI mode. 19809 19810 Note that if GDB's `stdout' is not connected to a terminal, or GDB 19811has been started with the machine interface interpreter (*note The 19812GDB/MI Interface: GDB/MI.), most of these commands will fail with an 19813error, because it would not be possible or desirable to enable curses 19814window management. 19815 19816`info win' 19817 List and give the size of all displayed windows. 19818 19819`layout next' 19820 Display the next layout. 19821 19822`layout prev' 19823 Display the previous layout. 19824 19825`layout src' 19826 Display the source window only. 19827 19828`layout asm' 19829 Display the assembly window only. 19830 19831`layout split' 19832 Display the source and assembly window. 19833 19834`layout regs' 19835 Display the register window together with the source or assembly 19836 window. 19837 19838`focus next' 19839 Make the next window active for scrolling. 19840 19841`focus prev' 19842 Make the previous window active for scrolling. 19843 19844`focus src' 19845 Make the source window active for scrolling. 19846 19847`focus asm' 19848 Make the assembly window active for scrolling. 19849 19850`focus regs' 19851 Make the register window active for scrolling. 19852 19853`focus cmd' 19854 Make the command window active for scrolling. 19855 19856`refresh' 19857 Refresh the screen. This is similar to typing `C-L'. 19858 19859`tui reg float' 19860 Show the floating point registers in the register window. 19861 19862`tui reg general' 19863 Show the general registers in the register window. 19864 19865`tui reg next' 19866 Show the next register group. The list of register groups as well 19867 as their order is target specific. The predefined register groups 19868 are the following: `general', `float', `system', `vector', `all', 19869 `save', `restore'. 19870 19871`tui reg system' 19872 Show the system registers in the register window. 19873 19874`update' 19875 Update the source window and the current execution point. 19876 19877`winheight NAME +COUNT' 19878`winheight NAME -COUNT' 19879 Change the height of the window NAME by COUNT lines. Positive 19880 counts increase the height, while negative counts decrease it. 19881 19882`tabset NCHARS' 19883 Set the width of tab stops to be NCHARS characters. 19884 19885 19886File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI 19887 1988825.5 TUI Configuration Variables 19889================================ 19890 19891Several configuration variables control the appearance of TUI windows. 19892 19893`set tui border-kind KIND' 19894 Select the border appearance for the source, assembly and register 19895 windows. The possible values are the following: 19896 `space' 19897 Use a space character to draw the border. 19898 19899 `ascii' 19900 Use ASCII characters `+', `-' and `|' to draw the border. 19901 19902 `acs' 19903 Use the Alternate Character Set to draw the border. The 19904 border is drawn using character line graphics if the terminal 19905 supports them. 19906 19907`set tui border-mode MODE' 19908`set tui active-border-mode MODE' 19909 Select the display attributes for the borders of the inactive 19910 windows or the active window. The MODE can be one of the 19911 following: 19912 `normal' 19913 Use normal attributes to display the border. 19914 19915 `standout' 19916 Use standout mode. 19917 19918 `reverse' 19919 Use reverse video mode. 19920 19921 `half' 19922 Use half bright mode. 19923 19924 `half-standout' 19925 Use half bright and standout mode. 19926 19927 `bold' 19928 Use extra bright or bold mode. 19929 19930 `bold-standout' 19931 Use extra bright or bold and standout mode. 19932 19933 19934File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top 19935 1993626 Using GDB under GNU Emacs 19937**************************** 19938 19939A special interface allows you to use GNU Emacs to view (and edit) the 19940source files for the program you are debugging with GDB. 19941 19942 To use this interface, use the command `M-x gdb' in Emacs. Give the 19943executable file you want to debug as an argument. This command starts 19944GDB as a subprocess of Emacs, with input and output through a newly 19945created Emacs buffer. 19946 19947 Running GDB under Emacs can be just like running GDB normally except 19948for two things: 19949 19950 * All "terminal" input and output goes through an Emacs buffer, 19951 called the GUD buffer. 19952 19953 This applies both to GDB commands and their output, and to the 19954 input and output done by the program you are debugging. 19955 19956 This is useful because it means that you can copy the text of 19957 previous commands and input them again; you can even use parts of 19958 the output in this way. 19959 19960 All the facilities of Emacs' Shell mode are available for 19961 interacting with your program. In particular, you can send 19962 signals the usual way--for example, `C-c C-c' for an interrupt, 19963 `C-c C-z' for a stop. 19964 19965 * GDB displays source code through Emacs. 19966 19967 Each time GDB displays a stack frame, Emacs automatically finds the 19968 source file for that frame and puts an arrow (`=>') at the left 19969 margin of the current line. Emacs uses a separate buffer for 19970 source display, and splits the screen to show both your GDB session 19971 and the source. 19972 19973 Explicit GDB `list' or search commands still produce output as 19974 usual, but you probably have no reason to use them from Emacs. 19975 19976 We call this "text command mode". Emacs 22.1, and later, also uses 19977a graphical mode, enabled by default, which provides further buffers 19978that can control the execution and describe the state of your program. 19979*Note GDB Graphical Interface: (Emacs)GDB Graphical Interface. 19980 19981 If you specify an absolute file name when prompted for the `M-x gdb' 19982argument, then Emacs sets your current working directory to where your 19983program resides. If you only specify the file name, then Emacs sets 19984your current working directory to to the directory associated with the 19985previous buffer. In this case, GDB may find your program by searching 19986your environment's `PATH' variable, but on some operating systems it 19987might not find the source. So, although the GDB input and output 19988session proceeds normally, the auxiliary buffer does not display the 19989current source and line of execution. 19990 19991 The initial working directory of GDB is printed on the top line of 19992the GUD buffer and this serves as a default for the commands that 19993specify files for GDB to operate on. *Note Commands to Specify Files: 19994Files. 19995 19996 By default, `M-x gdb' calls the program called `gdb'. If you need 19997to call GDB by a different name (for example, if you keep several 19998configurations around, with different names) you can customize the 19999Emacs variable `gud-gdb-command-name' to run the one you want. 20000 20001 In the GUD buffer, you can use these special Emacs commands in 20002addition to the standard Shell mode commands: 20003 20004`C-h m' 20005 Describe the features of Emacs' GUD Mode. 20006 20007`C-c C-s' 20008 Execute to another source line, like the GDB `step' command; also 20009 update the display window to show the current file and location. 20010 20011`C-c C-n' 20012 Execute to next source line in this function, skipping all function 20013 calls, like the GDB `next' command. Then update the display window 20014 to show the current file and location. 20015 20016`C-c C-i' 20017 Execute one instruction, like the GDB `stepi' command; update 20018 display window accordingly. 20019 20020`C-c C-f' 20021 Execute until exit from the selected stack frame, like the GDB 20022 `finish' command. 20023 20024`C-c C-r' 20025 Continue execution of your program, like the GDB `continue' 20026 command. 20027 20028`C-c <' 20029 Go up the number of frames indicated by the numeric argument 20030 (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' 20031 command. 20032 20033`C-c >' 20034 Go down the number of frames indicated by the numeric argument, 20035 like the GDB `down' command. 20036 20037 In any source file, the Emacs command `C-x <SPC>' (`gud-break') 20038tells GDB to set a breakpoint on the source line point is on. 20039 20040 In text command mode, if you type `M-x speedbar', Emacs displays a 20041separate frame which shows a backtrace when the GUD buffer is current. 20042Move point to any frame in the stack and type <RET> to make it become 20043the current frame and display the associated source in the source 20044buffer. Alternatively, click `Mouse-2' to make the selected frame 20045become the current one. In graphical mode, the speedbar displays watch 20046expressions. 20047 20048 If you accidentally delete the source-display buffer, an easy way to 20049get it back is to type the command `f' in the GDB buffer, to request a 20050frame display; when you run under Emacs, this recreates the source 20051buffer if necessary to show you the context of the current frame. 20052 20053 The source files displayed in Emacs are in ordinary Emacs buffers 20054which are visiting the source files in the usual way. You can edit the 20055files with these buffers if you wish; but keep in mind that GDB 20056communicates with Emacs in terms of line numbers. If you add or delete 20057lines from the text, the line numbers that GDB knows cease to 20058correspond properly with the code. 20059 20060 A more detailed description of Emacs' interaction with GDB is given 20061in the Emacs manual (*note Debuggers: (Emacs)Debuggers.). 20062 20063 20064File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top 20065 2006627 The GDB/MI Interface 20067*********************** 20068 20069Function and Purpose 20070==================== 20071 20072GDB/MI is a line based machine oriented text interface to GDB and is 20073activated by specifying using the `--interpreter' command line option 20074(*note Mode Options::). It is specifically intended to support the 20075development of systems which use the debugger as just one small 20076component of a larger system. 20077 20078 This chapter is a specification of the GDB/MI interface. It is 20079written in the form of a reference manual. 20080 20081 Note that GDB/MI is still under construction, so some of the 20082features described below are incomplete and subject to change (*note 20083GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.). 20084 20085Notation and Terminology 20086======================== 20087 20088This chapter uses the following notation: 20089 20090 * `|' separates two alternatives. 20091 20092 * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or 20093 may not be given. 20094 20095 * `( GROUP )*' means that GROUP inside the parentheses may repeat 20096 zero or more times. 20097 20098 * `( GROUP )+' means that GROUP inside the parentheses may repeat 20099 one or more times. 20100 20101 * `"STRING"' means a literal STRING. 20102 20103* Menu: 20104 20105* GDB/MI General Design:: 20106* GDB/MI Command Syntax:: 20107* GDB/MI Compatibility with CLI:: 20108* GDB/MI Development and Front Ends:: 20109* GDB/MI Output Records:: 20110* GDB/MI Simple Examples:: 20111* GDB/MI Command Description Format:: 20112* GDB/MI Breakpoint Commands:: 20113* GDB/MI Program Context:: 20114* GDB/MI Thread Commands:: 20115* GDB/MI Program Execution:: 20116* GDB/MI Stack Manipulation:: 20117* GDB/MI Variable Objects:: 20118* GDB/MI Data Manipulation:: 20119* GDB/MI Tracepoint Commands:: 20120* GDB/MI Symbol Query:: 20121* GDB/MI File Commands:: 20122* GDB/MI Target Manipulation:: 20123* GDB/MI File Transfer Commands:: 20124* GDB/MI Miscellaneous Commands:: 20125 20126 20127File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI 20128 2012927.1 GDB/MI General Design 20130========================== 20131 20132Interaction of a GDB/MI frontend with GDB involves three 20133parts--commands sent to GDB, responses to those commands and 20134notifications. Each command results in exactly one response, 20135indicating either successful completion of the command, or an error. 20136For the commands that do not resume the target, the response contains 20137the requested information. For the commands that resume the target, the 20138response only indicates whether the target was successfully resumed. 20139Notifications is the mechanism for reporting changes in the state of the 20140target, or in GDB state, that cannot conveniently be associated with a 20141command and reported as part of that command response. 20142 20143 The important examples of notifications are: 20144 * Exec notifications. These are used to report changes in target 20145 state--when a target is resumed, or stopped. It would not be 20146 feasible to include this information in response of resuming 20147 commands, because one resume commands can result in multiple 20148 events in different threads. Also, quite some time may pass 20149 before any event happens in the target, while a frontend needs to 20150 know whether the resuming command itself was successfully executed. 20151 20152 * Console output, and status notifications. Console output 20153 notifications are used to report output of CLI commands, as well as 20154 diagnostics for other commands. Status notifications are used to 20155 report the progress of a long-running operation. Naturally, 20156 including this information in command response would mean no 20157 output is produced until the command is finished, which is 20158 undesirable. 20159 20160 * General notifications. Commands may have various side effects on 20161 the GDB or target state beyond their official purpose. For 20162 example, a command may change the selected thread. Although such 20163 changes can be included in command response, using notification 20164 allows for more orthogonal frontend design. 20165 20166 20167 There's no guarantee that whenever an MI command reports an error, 20168GDB or the target are in any specific state, and especially, the state 20169is not reverted to the state before the MI command was processed. 20170Therefore, whenever an MI command results in an error, we recommend 20171that the frontend refreshes all the information shown in the user 20172interface. 20173 20174* Menu: 20175 20176* Context management:: 20177* Asynchronous and non-stop modes:: 20178* Thread groups:: 20179 20180 20181File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design 20182 2018327.1.1 Context management 20184------------------------- 20185 20186In most cases when GDB accesses the target, this access is done in 20187context of a specific thread and frame (*note Frames::). Often, even 20188when accessing global data, the target requires that a thread be 20189specified. The CLI interface maintains the selected thread and frame, 20190and supplies them to target on each command. This is convenient, 20191because a command line user would not want to specify that information 20192explicitly on each command, and because user interacts with GDB via a 20193single terminal, so no confusion is possible as to what thread and 20194frame are the current ones. 20195 20196 In the case of MI, the concept of selected thread and frame is less 20197useful. First, a frontend can easily remember this information itself. 20198Second, a graphical frontend can have more than one window, each one 20199used for debugging a different thread, and the frontend might want to 20200access additional threads for internal purposes. This increases the 20201risk that by relying on implicitly selected thread, the frontend may be 20202operating on a wrong one. Therefore, each MI command should explicitly 20203specify which thread and frame to operate on. To make it possible, 20204each MI command accepts the `--thread' and `--frame' options, the value 20205to each is GDB identifier for thread and frame to operate on. 20206 20207 Usually, each top-level window in a frontend allows the user to 20208select a thread and a frame, and remembers the user selection for 20209further operations. However, in some cases GDB may suggest that the 20210current thread be changed. For example, when stopping on a breakpoint 20211it is reasonable to switch to the thread where breakpoint is hit. For 20212another example, if the user issues the CLI `thread' command via the 20213frontend, it is desirable to change the frontend's selected thread to 20214the one specified by user. GDB communicates the suggestion to change 20215current thread using the `=thread-selected' notification. No such 20216notification is available for the selected frame at the moment. 20217 20218 Note that historically, MI shares the selected thread with CLI, so 20219frontends used the `-thread-select' to execute commands in the right 20220context. However, getting this to work right is cumbersome. The 20221simplest way is for frontend to emit `-thread-select' command before 20222every command. This doubles the number of commands that need to be 20223sent. The alternative approach is to suppress `-thread-select' if the 20224selected thread in GDB is supposed to be identical to the thread the 20225frontend wants to operate on. However, getting this optimization right 20226can be tricky. In particular, if the frontend sends several commands 20227to GDB, and one of the commands changes the selected thread, then the 20228behaviour of subsequent commands will change. So, a frontend should 20229either wait for response from such problematic commands, or explicitly 20230add `-thread-select' for all subsequent commands. No frontend is known 20231to do this exactly right, so it is suggested to just always pass the 20232`--thread' and `--frame' options. 20233 20234 20235File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design 20236 2023727.1.2 Asynchronous command execution and non-stop mode 20238------------------------------------------------------- 20239 20240On some targets, GDB is capable of processing MI commands even while 20241the target is running. This is called "asynchronous command execution" 20242(*note Background Execution::). The frontend may specify a preferrence 20243for asynchronous execution using the `-gdb-set target-async 1' command, 20244which should be emitted before either running the executable or 20245attaching to the target. After the frontend has started the executable 20246or attached to the target, it can find if asynchronous execution is 20247enabled using the `-list-target-features' command. 20248 20249 Even if GDB can accept a command while target is running, many 20250commands that access the target do not work when the target is running. 20251Therefore, asynchronous command execution is most useful when combined 20252with non-stop mode (*note Non-Stop Mode::). Then, it is possible to 20253examine the state of one thread, while other threads are running. 20254 20255 When a given thread is running, MI commands that try to access the 20256target in the context of that thread may not work, or may work only on 20257some targets. In particular, commands that try to operate on thread's 20258stack will not work, on any target. Commands that read memory, or 20259modify breakpoints, may work or not work, depending on the target. Note 20260that even commands that operate on global state, such as `print', 20261`set', and breakpoint commands, still access the target in the context 20262of a specific thread, so frontend should try to find a stopped thread 20263and perform the operation on that thread (using the `--thread' option). 20264 20265 Which commands will work in the context of a running thread is 20266highly target dependent. However, the two commands `-exec-interrupt', 20267to stop a thread, and `-thread-info', to find the state of a thread, 20268will always work. 20269 20270 20271File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design 20272 2027327.1.3 Thread groups 20274-------------------- 20275 20276GDB may be used to debug several processes at the same time. On some 20277platfroms, GDB may support debugging of several hardware systems, each 20278one having several cores with several different processes running on 20279each core. This section describes the MI mechanism to support such 20280debugging scenarios. 20281 20282 The key observation is that regardless of the structure of the 20283target, MI can have a global list of threads, because most commands that 20284accept the `--thread' option do not need to know what process that 20285thread belongs to. Therefore, it is not necessary to introduce neither 20286additional `--process' option, nor an notion of the current process in 20287the MI interface. The only strictly new feature that is required is 20288the ability to find how the threads are grouped into processes. 20289 20290 To allow the user to discover such grouping, and to support arbitrary 20291hierarchy of machines/cores/processes, MI introduces the concept of a 20292"thread group". Thread group is a collection of threads and other 20293thread groups. A thread group always has a string identifier, a type, 20294and may have additional attributes specific to the type. A new 20295command, `-list-thread-groups', returns the list of top-level thread 20296groups, which correspond to processes that GDB is debugging at the 20297moment. By passing an identifier of a thread group to the 20298`-list-thread-groups' command, it is possible to obtain the members of 20299specific thread group. 20300 20301 To allow the user to easily discover processes, and other objects, he 20302wishes to debug, a concept of "available thread group" is introduced. 20303Available thread group is an thread group that GDB is not debugging, 20304but that can be attached to, using the `-target-attach' command. The 20305list of available top-level thread groups can be obtained using 20306`-list-thread-groups --available'. In general, the content of a thread 20307group may be only retrieved only after attaching to that thread group. 20308 20309 Thread groups are related to inferiors (*note Inferiors and 20310Programs::). Each inferior corresponds to a thread group of a special 20311type `process', and some additional operations are permitted on such 20312thread groups. 20313 20314 20315File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI 20316 2031727.2 GDB/MI Command Syntax 20318========================== 20319 20320* Menu: 20321 20322* GDB/MI Input Syntax:: 20323* GDB/MI Output Syntax:: 20324 20325 20326File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax 20327 2032827.2.1 GDB/MI Input Syntax 20329-------------------------- 20330 20331`COMMAND ==>' 20332 `CLI-COMMAND | MI-COMMAND' 20333 20334`CLI-COMMAND ==>' 20335 `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB 20336 CLI command. 20337 20338`MI-COMMAND ==>' 20339 `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " 20340 PARAMETER )* NL' 20341 20342`TOKEN ==>' 20343 "any sequence of digits" 20344 20345`OPTION ==>' 20346 `"-" PARAMETER [ " " PARAMETER ]' 20347 20348`PARAMETER ==>' 20349 `NON-BLANK-SEQUENCE | C-STRING' 20350 20351`OPERATION ==>' 20352 _any of the operations described in this chapter_ 20353 20354`NON-BLANK-SEQUENCE ==>' 20355 _anything, provided it doesn't contain special characters such as 20356 "-", NL, """ and of course " "_ 20357 20358`C-STRING ==>' 20359 `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' 20360 20361`NL ==>' 20362 `CR | CR-LF' 20363 20364Notes: 20365 20366 * The CLI commands are still handled by the MI interpreter; their 20367 output is described below. 20368 20369 * The `TOKEN', when present, is passed back when the command 20370 finishes. 20371 20372 * Some MI commands accept optional arguments as part of the parameter 20373 list. Each option is identified by a leading `-' (dash) and may be 20374 followed by an optional argument parameter. Options occur first 20375 in the parameter list and can be delimited from normal parameters 20376 using `--' (this is useful when some parameters begin with a dash). 20377 20378 Pragmatics: 20379 20380 * We want easy access to the existing CLI syntax (for debugging). 20381 20382 * We want it to be easy to spot a MI operation. 20383 20384 20385File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax 20386 2038727.2.2 GDB/MI Output Syntax 20388--------------------------- 20389 20390The output from GDB/MI consists of zero or more out-of-band records 20391followed, optionally, by a single result record. This result record is 20392for the most recent command. The sequence of output records is 20393terminated by `(gdb)'. 20394 20395 If an input command was prefixed with a `TOKEN' then the 20396corresponding output for that command will also be prefixed by that same 20397TOKEN. 20398 20399`OUTPUT ==>' 20400 `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' 20401 20402`RESULT-RECORD ==>' 20403 ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' 20404 20405`OUT-OF-BAND-RECORD ==>' 20406 `ASYNC-RECORD | STREAM-RECORD' 20407 20408`ASYNC-RECORD ==>' 20409 `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' 20410 20411`EXEC-ASYNC-OUTPUT ==>' 20412 `[ TOKEN ] "*" ASYNC-OUTPUT' 20413 20414`STATUS-ASYNC-OUTPUT ==>' 20415 `[ TOKEN ] "+" ASYNC-OUTPUT' 20416 20417`NOTIFY-ASYNC-OUTPUT ==>' 20418 `[ TOKEN ] "=" ASYNC-OUTPUT' 20419 20420`ASYNC-OUTPUT ==>' 20421 `ASYNC-CLASS ( "," RESULT )* NL' 20422 20423`RESULT-CLASS ==>' 20424 `"done" | "running" | "connected" | "error" | "exit"' 20425 20426`ASYNC-CLASS ==>' 20427 `"stopped" | OTHERS' (where OTHERS will be added depending on the 20428 needs--this is still in development). 20429 20430`RESULT ==>' 20431 ` VARIABLE "=" VALUE' 20432 20433`VARIABLE ==>' 20434 ` STRING ' 20435 20436`VALUE ==>' 20437 ` CONST | TUPLE | LIST ' 20438 20439`CONST ==>' 20440 `C-STRING' 20441 20442`TUPLE ==>' 20443 ` "{}" | "{" RESULT ( "," RESULT )* "}" ' 20444 20445`LIST ==>' 20446 ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* 20447 "]" ' 20448 20449`STREAM-RECORD ==>' 20450 `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' 20451 20452`CONSOLE-STREAM-OUTPUT ==>' 20453 `"~" C-STRING' 20454 20455`TARGET-STREAM-OUTPUT ==>' 20456 `"@" C-STRING' 20457 20458`LOG-STREAM-OUTPUT ==>' 20459 `"&" C-STRING' 20460 20461`NL ==>' 20462 `CR | CR-LF' 20463 20464`TOKEN ==>' 20465 _any sequence of digits_. 20466 20467Notes: 20468 20469 * All output sequences end in a single line containing a period. 20470 20471 * The `TOKEN' is from the corresponding request. Note that for all 20472 async output, while the token is allowed by the grammar and may be 20473 output by future versions of GDB for select async output messages, 20474 it is generally omitted. Frontends should treat all async output 20475 as reporting general changes in the state of the target and there 20476 should be no need to associate async output to any prior command. 20477 20478 * STATUS-ASYNC-OUTPUT contains on-going status information about the 20479 progress of a slow operation. It can be discarded. All status 20480 output is prefixed by `+'. 20481 20482 * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target 20483 (stopped, started, disappeared). All async output is prefixed by 20484 `*'. 20485 20486 * NOTIFY-ASYNC-OUTPUT contains supplementary information that the 20487 client should handle (e.g., a new breakpoint information). All 20488 notify output is prefixed by `='. 20489 20490 * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in 20491 the console. It is the textual response to a CLI command. All 20492 the console output is prefixed by `~'. 20493 20494 * TARGET-STREAM-OUTPUT is the output produced by the target program. 20495 All the target output is prefixed by `@'. 20496 20497 * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for 20498 instance messages that should be displayed as part of an error 20499 log. All the log output is prefixed by `&'. 20500 20501 * New GDB/MI commands should only output LISTS containing VALUES. 20502 20503 20504 *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details 20505about the various output records. 20506 20507 20508File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI 20509 2051027.3 GDB/MI Compatibility with CLI 20511================================== 20512 20513For the developers convenience CLI commands can be entered directly, 20514but there may be some unexpected behaviour. For example, commands that 20515query the user will behave as if the user replied yes, breakpoint 20516command lists are not executed and some CLI commands, such as `if', 20517`when' and `define', prompt for further input with `>', which is not 20518valid MI output. 20519 20520 This feature may be removed at some stage in the future and it is 20521recommended that front ends use the `-interpreter-exec' command (*note 20522-interpreter-exec::). 20523 20524 20525File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI 20526 2052727.4 GDB/MI Development and Front Ends 20528====================================== 20529 20530The application which takes the MI output and presents the state of the 20531program being debugged to the user is called a "front end". 20532 20533 Although GDB/MI is still incomplete, it is currently being used by a 20534variety of front ends to GDB. This makes it difficult to introduce new 20535functionality without breaking existing usage. This section tries to 20536minimize the problems by describing how the protocol might change. 20537 20538 Some changes in MI need not break a carefully designed front end, and 20539for these the MI version will remain unchanged. The following is a 20540list of changes that may occur within one level, so front ends should 20541parse MI output in a way that can handle them: 20542 20543 * New MI commands may be added. 20544 20545 * New fields may be added to the output of any MI command. 20546 20547 * The range of values for fields with specified values, e.g., 20548 `in_scope' (*note -var-update::) may be extended. 20549 20550 20551 If the changes are likely to break front ends, the MI version level 20552will be increased by one. This will allow the front end to parse the 20553output according to the MI version. Apart from mi0, new versions of 20554GDB will not support old versions of MI and it will be the 20555responsibility of the front end to work with the new one. 20556 20557 The best way to avoid unexpected changes in MI that might break your 20558front end is to make your project known to GDB developers and follow 20559development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>. 20560 20561 20562File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI 20563 2056427.5 GDB/MI Output Records 20565========================== 20566 20567* Menu: 20568 20569* GDB/MI Result Records:: 20570* GDB/MI Stream Records:: 20571* GDB/MI Async Records:: 20572* GDB/MI Frame Information:: 20573* GDB/MI Thread Information:: 20574 20575 20576File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records 20577 2057827.5.1 GDB/MI Result Records 20579---------------------------- 20580 20581In addition to a number of out-of-band notifications, the response to a 20582GDB/MI command includes one of the following result indications: 20583 20584`"^done" [ "," RESULTS ]' 20585 The synchronous operation was successful, `RESULTS' are the return 20586 values. 20587 20588`"^running"' 20589 This result record is equivalent to `^done'. Historically, it was 20590 output instead of `^done' if the command has resumed the target. 20591 This behaviour is maintained for backward compatibility, but all 20592 frontends should treat `^done' and `^running' identically and rely 20593 on the `*running' output record to determine which threads are 20594 resumed. 20595 20596`"^connected"' 20597 GDB has connected to a remote target. 20598 20599`"^error" "," C-STRING' 20600 The operation failed. The `C-STRING' contains the corresponding 20601 error message. 20602 20603`"^exit"' 20604 GDB has terminated. 20605 20606 20607 20608File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records 20609 2061027.5.2 GDB/MI Stream Records 20611---------------------------- 20612 20613GDB internally maintains a number of output streams: the console, the 20614target, and the log. The output intended for each of these streams is 20615funneled through the GDB/MI interface using "stream records". 20616 20617 Each stream record begins with a unique "prefix character" which 20618identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output 20619Syntax.). In addition to the prefix, each stream record contains a 20620`STRING-OUTPUT'. This is either raw text (with an implicit new line) 20621or a quoted C string (which does not contain an implicit newline). 20622 20623`"~" STRING-OUTPUT' 20624 The console output stream contains text that should be displayed 20625 in the CLI console window. It contains the textual responses to 20626 CLI commands. 20627 20628`"@" STRING-OUTPUT' 20629 The target output stream contains any textual output from the 20630 running target. This is only present when GDB's event loop is 20631 truly asynchronous, which is currently only the case for remote 20632 targets. 20633 20634`"&" STRING-OUTPUT' 20635 The log stream contains debugging messages being produced by GDB's 20636 internals. 20637 20638 20639File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Frame Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records 20640 2064127.5.3 GDB/MI Async Records 20642--------------------------- 20643 20644"Async" records are used to notify the GDB/MI client of additional 20645changes that have occurred. Those changes can either be a consequence 20646of GDB/MI commands (e.g., a breakpoint modified) or a result of target 20647activity (e.g., target stopped). 20648 20649 The following is the list of possible async records: 20650 20651`*running,thread-id="THREAD"' 20652 The target is now running. The THREAD field tells which specific 20653 thread is now running, and can be `all' if all threads are 20654 running. The frontend should assume that no interaction with a 20655 running thread is possible after this notification is produced. 20656 The frontend should not assume that this notification is output 20657 only once for any command. GDB may emit this notification several 20658 times, either for different threads, because it cannot resume all 20659 threads together, or even for a single thread, if the thread must 20660 be stepped though some code before letting it run freely. 20661 20662`*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"' 20663 The target has stopped. The REASON field can have one of the 20664 following values: 20665 20666 `breakpoint-hit' 20667 A breakpoint was reached. 20668 20669 `watchpoint-trigger' 20670 A watchpoint was triggered. 20671 20672 `read-watchpoint-trigger' 20673 A read watchpoint was triggered. 20674 20675 `access-watchpoint-trigger' 20676 An access watchpoint was triggered. 20677 20678 `function-finished' 20679 An -exec-finish or similar CLI command was accomplished. 20680 20681 `location-reached' 20682 An -exec-until or similar CLI command was accomplished. 20683 20684 `watchpoint-scope' 20685 A watchpoint has gone out of scope. 20686 20687 `end-stepping-range' 20688 An -exec-next, -exec-next-instruction, -exec-step, 20689 -exec-step-instruction or similar CLI command was 20690 accomplished. 20691 20692 `exited-signalled' 20693 The inferior exited because of a signal. 20694 20695 `exited' 20696 The inferior exited. 20697 20698 `exited-normally' 20699 The inferior exited normally. 20700 20701 `signal-received' 20702 A signal was received by the inferior. 20703 20704 The ID field identifies the thread that directly caused the stop - 20705 for example by hitting a breakpoint. Depending on whether all-stop 20706 mode is in effect (*note All-Stop Mode::), GDB may either stop all 20707 threads, or only the thread that directly triggered the stop. If 20708 all threads are stopped, the STOPPED field will have the value of 20709 `"all"'. Otherwise, the value of the STOPPED field will be a list 20710 of thread identifiers. Presently, this list will always include a 20711 single thread, but frontend should be prepared to see several 20712 threads in the list. The CORE field reports the processor core on 20713 which the stop event has happened. This field may be absent if 20714 such information is not available. 20715 20716`=thread-group-added,id="ID"' 20717`=thread-group-removed,id="ID"' 20718 A thread group was either added or removed. The ID field contains 20719 the GDB identifier of the thread group. When a thread group is 20720 added, it generally might not be associated with a running 20721 process. When a thread group is removed, its id becomes invalid 20722 and cannot be used in any way. 20723 20724`=thread-group-started,id="ID",pid="PID"' 20725 A thread group became associated with a running program, either 20726 because the program was just started or the thread group was 20727 attached to a program. The ID field contains the GDB identifier 20728 of the thread group. The PID field contains process identifier, 20729 specific to the operating system. 20730 20731`=thread-group-exited,id="ID"' 20732 A thread group is no longer associated with a running program, 20733 either because the program has exited, or because it was detached 20734 from. The ID field contains the GDB identifier of the thread 20735 group. 20736 20737`=thread-created,id="ID",group-id="GID"' 20738`=thread-exited,id="ID",group-id="GID"' 20739 A thread either was created, or has exited. The ID field contains 20740 the GDB identifier of the thread. The GID field identifies the 20741 thread group this thread belongs to. 20742 20743`=thread-selected,id="ID"' 20744 Informs that the selected thread was changed as result of the last 20745 command. This notification is not emitted as result of 20746 `-thread-select' command but is emitted whenever an MI command 20747 that is not documented to change the selected thread actually 20748 changes it. In particular, invoking, directly or indirectly (via 20749 user-defined command), the CLI `thread' command, will generate 20750 this notification. 20751 20752 We suggest that in response to this notification, front ends 20753 highlight the selected thread and cause subsequent commands to 20754 apply to that thread. 20755 20756`=library-loaded,...' 20757 Reports that a new library file was loaded by the program. This 20758 notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and 20759 SYMBOLS-LOADED. The ID field is an opaque identifier of the 20760 library. For remote debugging case, TARGET-NAME and HOST-NAME 20761 fields give the name of the library file on the target, and on the 20762 host respectively. For native debugging, both those fields have 20763 the same value. The SYMBOLS-LOADED field reports if the debug 20764 symbols for this library are loaded. The THREAD-GROUP field, if 20765 present, specifies the id of the thread group in whose context the 20766 library was loaded. If the field is absent, it means the library 20767 was loaded in the context of all present thread groups. 20768 20769`=library-unloaded,...' 20770 Reports that a library was unloaded by the program. This 20771 notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the 20772 same meaning as for the `=library-loaded' notification. The 20773 THREAD-GROUP field, if present, specifies the id of the thread 20774 group in whose context the library was unloaded. If the field is 20775 absent, it means the library was unloaded in the context of all 20776 present thread groups. 20777 20778 20779 20780File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records 20781 2078227.5.4 GDB/MI Frame Information 20783------------------------------- 20784 20785Response from many MI commands includes an information about stack 20786frame. This information is a tuple that may have the following fields: 20787 20788`level' 20789 The level of the stack frame. The innermost frame has the level of 20790 zero. This field is always present. 20791 20792`func' 20793 The name of the function corresponding to the frame. This field 20794 may be absent if GDB is unable to determine the function name. 20795 20796`addr' 20797 The code address for the frame. This field is always present. 20798 20799`file' 20800 The name of the source files that correspond to the frame's code 20801 address. This field may be absent. 20802 20803`line' 20804 The source line corresponding to the frames' code address. This 20805 field may be absent. 20806 20807`from' 20808 The name of the binary file (either executable or shared library) 20809 the corresponds to the frame's code address. This field may be 20810 absent. 20811 20812 20813 20814File: gdb.info, Node: GDB/MI Thread Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records 20815 2081627.5.5 GDB/MI Thread Information 20817-------------------------------- 20818 20819Whenever GDB has to report an information about a thread, it uses a 20820tuple with the following fields: 20821 20822`id' 20823 The numeric id assigned to the thread by GDB. This field is 20824 always present. 20825 20826`target-id' 20827 Target-specific string identifying the thread. This field is 20828 always present. 20829 20830`details' 20831 Additional information about the thread provided by the target. 20832 It is supposed to be human-readable and not interpreted by the 20833 frontend. This field is optional. 20834 20835`state' 20836 Either `stopped' or `running', depending on whether the thread is 20837 presently running. This field is always present. 20838 20839`core' 20840 The value of this field is an integer number of the processor core 20841 the thread was last seen on. This field is optional. 20842 20843 20844File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI 20845 2084627.6 Simple Examples of GDB/MI Interaction 20847========================================== 20848 20849This subsection presents several simple examples of interaction using 20850the GDB/MI interface. In these examples, `->' means that the following 20851line is passed to GDB/MI as input, while `<-' means the output received 20852from GDB/MI. 20853 20854 Note the line breaks shown in the examples are here only for 20855readability, they don't appear in the real output. 20856 20857Setting a Breakpoint 20858-------------------- 20859 20860Setting a breakpoint generates synchronous output which contains 20861detailed information of the breakpoint. 20862 20863 -> -break-insert main 20864 <- ^done,bkpt={number="1",type="breakpoint",disp="keep", 20865 enabled="y",addr="0x08048564",func="main",file="myprog.c", 20866 fullname="/home/nickrob/myprog.c",line="68",times="0"} 20867 <- (gdb) 20868 20869Program Execution 20870----------------- 20871 20872Program execution generates asynchronous records and MI gives the 20873reason that execution stopped. 20874 20875 -> -exec-run 20876 <- ^running 20877 <- (gdb) 20878 <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 20879 frame={addr="0x08048564",func="main", 20880 args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], 20881 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"} 20882 <- (gdb) 20883 -> -exec-continue 20884 <- ^running 20885 <- (gdb) 20886 <- *stopped,reason="exited-normally" 20887 <- (gdb) 20888 20889Quitting GDB 20890------------ 20891 20892Quitting GDB just prints the result class `^exit'. 20893 20894 -> (gdb) 20895 <- -gdb-exit 20896 <- ^exit 20897 20898 Please note that `^exit' is printed immediately, but it might take 20899some time for GDB to actually exit. During that time, GDB performs 20900necessary cleanups, including killing programs being debugged or 20901disconnecting from debug hardware, so the frontend should wait till GDB 20902exits and should only forcibly kill GDB if it fails to exit in 20903reasonable time. 20904 20905A Bad Command 20906------------- 20907 20908Here's what happens if you pass a non-existent command: 20909 20910 -> -rubbish 20911 <- ^error,msg="Undefined MI command: rubbish" 20912 <- (gdb) 20913 20914 20915File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI 20916 2091727.7 GDB/MI Command Description Format 20918====================================== 20919 20920The remaining sections describe blocks of commands. Each block of 20921commands is laid out in a fashion similar to this section. 20922 20923Motivation 20924---------- 20925 20926The motivation for this collection of commands. 20927 20928Introduction 20929------------ 20930 20931A brief introduction to this collection of commands as a whole. 20932 20933Commands 20934-------- 20935 20936For each command in the block, the following is described: 20937 20938Synopsis 20939........ 20940 20941 -command ARGS... 20942 20943Result 20944...... 20945 20946GDB Command 20947........... 20948 20949The corresponding GDB CLI command(s), if any. 20950 20951Example 20952....... 20953 20954Example(s) formatted for readability. Some of the described commands 20955have not been implemented yet and these are labeled N.A. (not 20956available). 20957 20958 20959File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI 20960 2096127.8 GDB/MI Breakpoint Commands 20962=============================== 20963 20964This section documents GDB/MI commands for manipulating breakpoints. 20965 20966The `-break-after' Command 20967-------------------------- 20968 20969Synopsis 20970........ 20971 20972 -break-after NUMBER COUNT 20973 20974 The breakpoint number NUMBER is not in effect until it has been hit 20975COUNT times. To see how this is reflected in the output of the 20976`-break-list' command, see the description of the `-break-list' command 20977below. 20978 20979GDB Command 20980........... 20981 20982The corresponding GDB command is `ignore'. 20983 20984Example 20985....... 20986 20987 (gdb) 20988 -break-insert main 20989 ^done,bkpt={number="1",type="breakpoint",disp="keep", 20990 enabled="y",addr="0x000100d0",func="main",file="hello.c", 20991 fullname="/home/foo/hello.c",line="5",times="0"} 20992 (gdb) 20993 -break-after 1 3 20994 ~ 20995 ^done 20996 (gdb) 20997 -break-list 20998 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 20999 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21000 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21001 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21002 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21003 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21004 {width="40",alignment="2",col_name="what",colhdr="What"}], 21005 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 21006 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 21007 line="5",times="0",ignore="3"}]} 21008 (gdb) 21009 21010The `-break-commands' Command 21011----------------------------- 21012 21013Synopsis 21014........ 21015 21016 -break-commands NUMBER [ COMMAND1 ... COMMANDN ] 21017 21018 Specifies the CLI commands that should be executed when breakpoint 21019NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands. 21020If no command is specified, any previously-set commands are cleared. 21021*Note Break Commands::. Typical use of this functionality is tracing a 21022program, that is, printing of values of some variables whenever 21023breakpoint is hit and then continuing. 21024 21025GDB Command 21026........... 21027 21028The corresponding GDB command is `commands'. 21029 21030Example 21031....... 21032 21033 (gdb) 21034 -break-insert main 21035 ^done,bkpt={number="1",type="breakpoint",disp="keep", 21036 enabled="y",addr="0x000100d0",func="main",file="hello.c", 21037 fullname="/home/foo/hello.c",line="5",times="0"} 21038 (gdb) 21039 -break-commands 1 "print v" "continue" 21040 ^done 21041 (gdb) 21042 21043The `-break-condition' Command 21044------------------------------ 21045 21046Synopsis 21047........ 21048 21049 -break-condition NUMBER EXPR 21050 21051 Breakpoint NUMBER will stop the program only if the condition in 21052EXPR is true. The condition becomes part of the `-break-list' output 21053(see the description of the `-break-list' command below). 21054 21055GDB Command 21056........... 21057 21058The corresponding GDB command is `condition'. 21059 21060Example 21061....... 21062 21063 (gdb) 21064 -break-condition 1 1 21065 ^done 21066 (gdb) 21067 -break-list 21068 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 21069 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21070 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21071 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21072 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21073 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21074 {width="40",alignment="2",col_name="what",colhdr="What"}], 21075 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 21076 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 21077 line="5",cond="1",times="0",ignore="3"}]} 21078 (gdb) 21079 21080The `-break-delete' Command 21081--------------------------- 21082 21083Synopsis 21084........ 21085 21086 -break-delete ( BREAKPOINT )+ 21087 21088 Delete the breakpoint(s) whose number(s) are specified in the 21089argument list. This is obviously reflected in the breakpoint list. 21090 21091GDB Command 21092........... 21093 21094The corresponding GDB command is `delete'. 21095 21096Example 21097....... 21098 21099 (gdb) 21100 -break-delete 1 21101 ^done 21102 (gdb) 21103 -break-list 21104 ^done,BreakpointTable={nr_rows="0",nr_cols="6", 21105 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21106 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21107 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21108 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21109 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21110 {width="40",alignment="2",col_name="what",colhdr="What"}], 21111 body=[]} 21112 (gdb) 21113 21114The `-break-disable' Command 21115---------------------------- 21116 21117Synopsis 21118........ 21119 21120 -break-disable ( BREAKPOINT )+ 21121 21122 Disable the named BREAKPOINT(s). The field `enabled' in the break 21123list is now set to `n' for the named BREAKPOINT(s). 21124 21125GDB Command 21126........... 21127 21128The corresponding GDB command is `disable'. 21129 21130Example 21131....... 21132 21133 (gdb) 21134 -break-disable 2 21135 ^done 21136 (gdb) 21137 -break-list 21138 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 21139 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21140 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21141 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21142 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21143 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21144 {width="40",alignment="2",col_name="what",colhdr="What"}], 21145 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", 21146 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 21147 line="5",times="0"}]} 21148 (gdb) 21149 21150The `-break-enable' Command 21151--------------------------- 21152 21153Synopsis 21154........ 21155 21156 -break-enable ( BREAKPOINT )+ 21157 21158 Enable (previously disabled) BREAKPOINT(s). 21159 21160GDB Command 21161........... 21162 21163The corresponding GDB command is `enable'. 21164 21165Example 21166....... 21167 21168 (gdb) 21169 -break-enable 2 21170 ^done 21171 (gdb) 21172 -break-list 21173 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 21174 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21175 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21176 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21177 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21178 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21179 {width="40",alignment="2",col_name="what",colhdr="What"}], 21180 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", 21181 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 21182 line="5",times="0"}]} 21183 (gdb) 21184 21185The `-break-info' Command 21186------------------------- 21187 21188Synopsis 21189........ 21190 21191 -break-info BREAKPOINT 21192 21193 Get information about a single breakpoint. 21194 21195GDB Command 21196........... 21197 21198The corresponding GDB command is `info break BREAKPOINT'. 21199 21200Example 21201....... 21202 21203N.A. 21204 21205The `-break-insert' Command 21206--------------------------- 21207 21208Synopsis 21209........ 21210 21211 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] 21212 [ -c CONDITION ] [ -i IGNORE-COUNT ] 21213 [ -p THREAD ] [ LOCATION ] 21214 21215If specified, LOCATION, can be one of: 21216 21217 * function 21218 21219 * filename:linenum 21220 21221 * filename:function 21222 21223 * *address 21224 21225 The possible optional parameters of this command are: 21226 21227`-t' 21228 Insert a temporary breakpoint. 21229 21230`-h' 21231 Insert a hardware breakpoint. 21232 21233`-c CONDITION' 21234 Make the breakpoint conditional on CONDITION. 21235 21236`-i IGNORE-COUNT' 21237 Initialize the IGNORE-COUNT. 21238 21239`-f' 21240 If LOCATION cannot be parsed (for example if it refers to unknown 21241 files or functions), create a pending breakpoint. Without this 21242 flag, GDB will report an error, and won't create a breakpoint, if 21243 LOCATION cannot be parsed. 21244 21245`-d' 21246 Create a disabled breakpoint. 21247 21248`-a' 21249 Create a tracepoint. *Note Tracepoints::. When this parameter is 21250 used together with `-h', a fast tracepoint is created. 21251 21252Result 21253...... 21254 21255The result is in the form: 21256 21257 ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep", 21258 enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME", 21259 fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,] 21260 times="TIMES"} 21261 21262where NUMBER is the GDB number for this breakpoint, FUNCNAME is the 21263name of the function where the breakpoint was inserted, FILENAME is the 21264name of the source file which contains this function, LINENO is the 21265source line number within that file and TIMES the number of times that 21266the breakpoint has been hit (always 0 for -break-insert but may be 21267greater for -break-info or -break-list which use the same output). 21268 21269 Note: this format is open to change. 21270 21271GDB Command 21272........... 21273 21274The corresponding GDB commands are `break', `tbreak', `hbreak', 21275`thbreak', and `rbreak'. 21276 21277Example 21278....... 21279 21280 (gdb) 21281 -break-insert main 21282 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", 21283 fullname="/home/foo/recursive2.c,line="4",times="0"} 21284 (gdb) 21285 -break-insert -t foo 21286 ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", 21287 fullname="/home/foo/recursive2.c,line="11",times="0"} 21288 (gdb) 21289 -break-list 21290 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 21291 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21292 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21293 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21294 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21295 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21296 {width="40",alignment="2",col_name="what",colhdr="What"}], 21297 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 21298 addr="0x0001072c", func="main",file="recursive2.c", 21299 fullname="/home/foo/recursive2.c,"line="4",times="0"}, 21300 bkpt={number="2",type="breakpoint",disp="del",enabled="y", 21301 addr="0x00010774",func="foo",file="recursive2.c", 21302 fullname="/home/foo/recursive2.c",line="11",times="0"}]} 21303 (gdb) 21304 -break-insert -r foo.* 21305 ~int foo(int, int); 21306 ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c, 21307 "fullname="/home/foo/recursive2.c",line="11",times="0"} 21308 (gdb) 21309 21310The `-break-list' Command 21311------------------------- 21312 21313Synopsis 21314........ 21315 21316 -break-list 21317 21318 Displays the list of inserted breakpoints, showing the following 21319fields: 21320 21321`Number' 21322 number of the breakpoint 21323 21324`Type' 21325 type of the breakpoint: `breakpoint' or `watchpoint' 21326 21327`Disposition' 21328 should the breakpoint be deleted or disabled when it is hit: `keep' 21329 or `nokeep' 21330 21331`Enabled' 21332 is the breakpoint enabled or no: `y' or `n' 21333 21334`Address' 21335 memory location at which the breakpoint is set 21336 21337`What' 21338 logical location of the breakpoint, expressed by function name, 21339 file name, line number 21340 21341`Times' 21342 number of times the breakpoint has been hit 21343 21344 If there are no breakpoints or watchpoints, the `BreakpointTable' 21345`body' field is an empty list. 21346 21347GDB Command 21348........... 21349 21350The corresponding GDB command is `info break'. 21351 21352Example 21353....... 21354 21355 (gdb) 21356 -break-list 21357 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 21358 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21359 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21360 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21361 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21362 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21363 {width="40",alignment="2",col_name="what",colhdr="What"}], 21364 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 21365 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}, 21366 bkpt={number="2",type="breakpoint",disp="keep",enabled="y", 21367 addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", 21368 line="13",times="0"}]} 21369 (gdb) 21370 21371 Here's an example of the result when there are no breakpoints: 21372 21373 (gdb) 21374 -break-list 21375 ^done,BreakpointTable={nr_rows="0",nr_cols="6", 21376 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21377 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21378 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21379 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21380 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21381 {width="40",alignment="2",col_name="what",colhdr="What"}], 21382 body=[]} 21383 (gdb) 21384 21385The `-break-passcount' Command 21386------------------------------ 21387 21388Synopsis 21389........ 21390 21391 -break-passcount TRACEPOINT-NUMBER PASSCOUNT 21392 21393 Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If 21394the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint, 21395error is emitted. This corresponds to CLI command `passcount'. 21396 21397The `-break-watch' Command 21398-------------------------- 21399 21400Synopsis 21401........ 21402 21403 -break-watch [ -a | -r ] 21404 21405 Create a watchpoint. With the `-a' option it will create an 21406"access" watchpoint, i.e., a watchpoint that triggers either on a read 21407from or on a write to the memory location. With the `-r' option, the 21408watchpoint created is a "read" watchpoint, i.e., it will trigger only 21409when the memory location is accessed for reading. Without either of 21410the options, the watchpoint created is a regular watchpoint, i.e., it 21411will trigger when the memory location is accessed for writing. *Note 21412Setting Watchpoints: Set Watchpoints. 21413 21414 Note that `-break-list' will report a single list of watchpoints and 21415breakpoints inserted. 21416 21417GDB Command 21418........... 21419 21420The corresponding GDB commands are `watch', `awatch', and `rwatch'. 21421 21422Example 21423....... 21424 21425Setting a watchpoint on a variable in the `main' function: 21426 21427 (gdb) 21428 -break-watch x 21429 ^done,wpt={number="2",exp="x"} 21430 (gdb) 21431 -exec-continue 21432 ^running 21433 (gdb) 21434 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, 21435 value={old="-268439212",new="55"}, 21436 frame={func="main",args=[],file="recursive2.c", 21437 fullname="/home/foo/bar/recursive2.c",line="5"} 21438 (gdb) 21439 21440 Setting a watchpoint on a variable local to a function. GDB will 21441stop the program execution twice: first for the variable changing 21442value, then for the watchpoint going out of scope. 21443 21444 (gdb) 21445 -break-watch C 21446 ^done,wpt={number="5",exp="C"} 21447 (gdb) 21448 -exec-continue 21449 ^running 21450 (gdb) 21451 *stopped,reason="watchpoint-trigger", 21452 wpt={number="5",exp="C"},value={old="-276895068",new="3"}, 21453 frame={func="callee4",args=[], 21454 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 21455 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} 21456 (gdb) 21457 -exec-continue 21458 ^running 21459 (gdb) 21460 *stopped,reason="watchpoint-scope",wpnum="5", 21461 frame={func="callee3",args=[{name="strarg", 21462 value="0x11940 \"A string argument.\""}], 21463 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 21464 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} 21465 (gdb) 21466 21467 Listing breakpoints and watchpoints, at different points in the 21468program execution. Note that once the watchpoint goes out of scope, it 21469is deleted. 21470 21471 (gdb) 21472 -break-watch C 21473 ^done,wpt={number="2",exp="C"} 21474 (gdb) 21475 -break-list 21476 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 21477 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21478 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21479 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21480 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21481 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21482 {width="40",alignment="2",col_name="what",colhdr="What"}], 21483 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 21484 addr="0x00010734",func="callee4", 21485 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 21486 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"}, 21487 bkpt={number="2",type="watchpoint",disp="keep", 21488 enabled="y",addr="",what="C",times="0"}]} 21489 (gdb) 21490 -exec-continue 21491 ^running 21492 (gdb) 21493 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, 21494 value={old="-276895068",new="3"}, 21495 frame={func="callee4",args=[], 21496 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 21497 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} 21498 (gdb) 21499 -break-list 21500 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 21501 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21502 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21503 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21504 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21505 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21506 {width="40",alignment="2",col_name="what",colhdr="What"}], 21507 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 21508 addr="0x00010734",func="callee4", 21509 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 21510 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, 21511 bkpt={number="2",type="watchpoint",disp="keep", 21512 enabled="y",addr="",what="C",times="-5"}]} 21513 (gdb) 21514 -exec-continue 21515 ^running 21516 ^done,reason="watchpoint-scope",wpnum="2", 21517 frame={func="callee3",args=[{name="strarg", 21518 value="0x11940 \"A string argument.\""}], 21519 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 21520 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} 21521 (gdb) 21522 -break-list 21523 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 21524 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 21525 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 21526 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 21527 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 21528 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 21529 {width="40",alignment="2",col_name="what",colhdr="What"}], 21530 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 21531 addr="0x00010734",func="callee4", 21532 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 21533 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 21534 times="1"}]} 21535 (gdb) 21536 21537 21538File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI 21539 2154027.9 GDB/MI Program Context 21541============================ 21542 21543The `-exec-arguments' Command 21544----------------------------- 21545 21546Synopsis 21547........ 21548 21549 -exec-arguments ARGS 21550 21551 Set the inferior program arguments, to be used in the next 21552`-exec-run'. 21553 21554GDB Command 21555........... 21556 21557The corresponding GDB command is `set args'. 21558 21559Example 21560....... 21561 21562 (gdb) 21563 -exec-arguments -v word 21564 ^done 21565 (gdb) 21566 21567The `-environment-cd' Command 21568----------------------------- 21569 21570Synopsis 21571........ 21572 21573 -environment-cd PATHDIR 21574 21575 Set GDB's working directory. 21576 21577GDB Command 21578........... 21579 21580The corresponding GDB command is `cd'. 21581 21582Example 21583....... 21584 21585 (gdb) 21586 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 21587 ^done 21588 (gdb) 21589 21590The `-environment-directory' Command 21591------------------------------------ 21592 21593Synopsis 21594........ 21595 21596 -environment-directory [ -r ] [ PATHDIR ]+ 21597 21598 Add directories PATHDIR to beginning of search path for source files. 21599If the `-r' option is used, the search path is reset to the default 21600search path. If directories PATHDIR are supplied in addition to the 21601`-r' option, the search path is first reset and then addition occurs as 21602normal. Multiple directories may be specified, separated by blanks. 21603Specifying multiple directories in a single command results in the 21604directories added to the beginning of the search path in the same order 21605they were presented in the command. If blanks are needed as part of a 21606directory name, double-quotes should be used around the name. In the 21607command output, the path will show up separated by the system 21608directory-separator character. The directory-separator character must 21609not be used in any directory name. If no directories are specified, 21610the current search path is displayed. 21611 21612GDB Command 21613........... 21614 21615The corresponding GDB command is `dir'. 21616 21617Example 21618....... 21619 21620 (gdb) 21621 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb 21622 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 21623 (gdb) 21624 -environment-directory "" 21625 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" 21626 (gdb) 21627 -environment-directory -r /home/jjohnstn/src/gdb /usr/src 21628 ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" 21629 (gdb) 21630 -environment-directory -r 21631 ^done,source-path="$cdir:$cwd" 21632 (gdb) 21633 21634The `-environment-path' Command 21635------------------------------- 21636 21637Synopsis 21638........ 21639 21640 -environment-path [ -r ] [ PATHDIR ]+ 21641 21642 Add directories PATHDIR to beginning of search path for object files. 21643If the `-r' option is used, the search path is reset to the original 21644search path that existed at gdb start-up. If directories PATHDIR are 21645supplied in addition to the `-r' option, the search path is first reset 21646and then addition occurs as normal. Multiple directories may be 21647specified, separated by blanks. Specifying multiple directories in a 21648single command results in the directories added to the beginning of the 21649search path in the same order they were presented in the command. If 21650blanks are needed as part of a directory name, double-quotes should be 21651used around the name. In the command output, the path will show up 21652separated by the system directory-separator character. The 21653directory-separator character must not be used in any directory name. 21654If no directories are specified, the current path is displayed. 21655 21656GDB Command 21657........... 21658 21659The corresponding GDB command is `path'. 21660 21661Example 21662....... 21663 21664 (gdb) 21665 -environment-path 21666 ^done,path="/usr/bin" 21667 (gdb) 21668 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin 21669 ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" 21670 (gdb) 21671 -environment-path -r /usr/local/bin 21672 ^done,path="/usr/local/bin:/usr/bin" 21673 (gdb) 21674 21675The `-environment-pwd' Command 21676------------------------------ 21677 21678Synopsis 21679........ 21680 21681 -environment-pwd 21682 21683 Show the current working directory. 21684 21685GDB Command 21686........... 21687 21688The corresponding GDB command is `pwd'. 21689 21690Example 21691....... 21692 21693 (gdb) 21694 -environment-pwd 21695 ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" 21696 (gdb) 21697 21698 21699File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Program Context, Up: GDB/MI 21700 2170127.10 GDB/MI Thread Commands 21702============================ 21703 21704The `-thread-info' Command 21705-------------------------- 21706 21707Synopsis 21708........ 21709 21710 -thread-info [ THREAD-ID ] 21711 21712 Reports information about either a specific thread, if the THREAD-ID 21713parameter is present, or about all threads. When printing information 21714about all threads, also reports the current thread. 21715 21716GDB Command 21717........... 21718 21719The `info thread' command prints the same information about all threads. 21720 21721Example 21722....... 21723 21724 -thread-info 21725 ^done,threads=[ 21726 {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 21727 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, 21728 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 21729 frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], 21730 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}], 21731 current-thread-id="1" 21732 (gdb) 21733 21734 The `state' field may have the following values: 21735 21736`stopped' 21737 The thread is stopped. Frame information is available for stopped 21738 threads. 21739 21740`running' 21741 The thread is running. There's no frame information for running 21742 threads. 21743 21744 21745The `-thread-list-ids' Command 21746------------------------------ 21747 21748Synopsis 21749........ 21750 21751 -thread-list-ids 21752 21753 Produces a list of the currently known GDB thread ids. At the end 21754of the list it also prints the total number of such threads. 21755 21756 This command is retained for historical reasons, the `-thread-info' 21757command should be used instead. 21758 21759GDB Command 21760........... 21761 21762Part of `info threads' supplies the same information. 21763 21764Example 21765....... 21766 21767 (gdb) 21768 -thread-list-ids 21769 ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, 21770 current-thread-id="1",number-of-threads="3" 21771 (gdb) 21772 21773The `-thread-select' Command 21774---------------------------- 21775 21776Synopsis 21777........ 21778 21779 -thread-select THREADNUM 21780 21781 Make THREADNUM the current thread. It prints the number of the new 21782current thread, and the topmost frame for that thread. 21783 21784 This command is deprecated in favor of explicitly using the 21785`--thread' option to each command. 21786 21787GDB Command 21788........... 21789 21790The corresponding GDB command is `thread'. 21791 21792Example 21793....... 21794 21795 (gdb) 21796 -exec-next 21797 ^running 21798 (gdb) 21799 *stopped,reason="end-stepping-range",thread-id="2",line="187", 21800 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" 21801 (gdb) 21802 -thread-list-ids 21803 ^done, 21804 thread-ids={thread-id="3",thread-id="2",thread-id="1"}, 21805 number-of-threads="3" 21806 (gdb) 21807 -thread-select 3 21808 ^done,new-thread-id="3", 21809 frame={level="0",func="vprintf", 21810 args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, 21811 {name="arg",value="0x2"}],file="vprintf.c",line="31"} 21812 (gdb) 21813 21814 21815File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Thread Commands, Up: GDB/MI 21816 2181727.11 GDB/MI Program Execution 21818============================== 21819 21820These are the asynchronous commands which generate the out-of-band 21821record `*stopped'. Currently GDB only really executes asynchronously 21822with remote targets and this interaction is mimicked in other cases. 21823 21824The `-exec-continue' Command 21825---------------------------- 21826 21827Synopsis 21828........ 21829 21830 -exec-continue [--reverse] [--all|--thread-group N] 21831 21832 Resumes the execution of the inferior program, which will continue 21833to execute until it reaches a debugger stop event. If the `--reverse' 21834option is specified, execution resumes in reverse until it reaches a 21835stop event. Stop events may include 21836 * breakpoints or watchpoints 21837 21838 * signals or exceptions 21839 21840 * the end of the process (or its beginning under `--reverse') 21841 21842 * the end or beginning of a replay log if one is being used. 21843 In all-stop mode (*note All-Stop Mode::), may resume only one 21844thread, or all threads, depending on the value of the 21845`scheduler-locking' variable. If `--all' is specified, all threads (in 21846all inferiors) will be resumed. The `--all' option is ignored in 21847all-stop mode. If the `--thread-group' options is specified, then all 21848threads in that thread group are resumed. 21849 21850GDB Command 21851........... 21852 21853The corresponding GDB corresponding is `continue'. 21854 21855Example 21856....... 21857 21858 -exec-continue 21859 ^running 21860 (gdb) 21861 @Hello world 21862 *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ 21863 func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", 21864 line="13"} 21865 (gdb) 21866 21867The `-exec-finish' Command 21868-------------------------- 21869 21870Synopsis 21871........ 21872 21873 -exec-finish [--reverse] 21874 21875 Resumes the execution of the inferior program until the current 21876function is exited. Displays the results returned by the function. If 21877the `--reverse' option is specified, resumes the reverse execution of 21878the inferior program until the point where current function was called. 21879 21880GDB Command 21881........... 21882 21883The corresponding GDB command is `finish'. 21884 21885Example 21886....... 21887 21888Function returning `void'. 21889 21890 -exec-finish 21891 ^running 21892 (gdb) 21893 @hello from foo 21894 *stopped,reason="function-finished",frame={func="main",args=[], 21895 file="hello.c",fullname="/home/foo/bar/hello.c",line="7"} 21896 (gdb) 21897 21898 Function returning other than `void'. The name of the internal GDB 21899variable storing the result is printed, together with the value itself. 21900 21901 -exec-finish 21902 ^running 21903 (gdb) 21904 *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", 21905 args=[{name="a",value="1"],{name="b",value="9"}}, 21906 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 21907 gdb-result-var="$1",return-value="0" 21908 (gdb) 21909 21910The `-exec-interrupt' Command 21911----------------------------- 21912 21913Synopsis 21914........ 21915 21916 -exec-interrupt [--all|--thread-group N] 21917 21918 Interrupts the background execution of the target. Note how the 21919token associated with the stop message is the one for the execution 21920command that has been interrupted. The token for the interrupt itself 21921only appears in the `^done' output. If the user is trying to interrupt 21922a non-running program, an error message will be printed. 21923 21924 Note that when asynchronous execution is enabled, this command is 21925asynchronous just like other execution commands. That is, first the 21926`^done' response will be printed, and the target stop will be reported 21927after that using the `*stopped' notification. 21928 21929 In non-stop mode, only the context thread is interrupted by default. 21930All threads (in all inferiors) will be interrupted if the `--all' 21931option is specified. If the `--thread-group' option is specified, all 21932threads in that group will be interrupted. 21933 21934GDB Command 21935........... 21936 21937The corresponding GDB command is `interrupt'. 21938 21939Example 21940....... 21941 21942 (gdb) 21943 111-exec-continue 21944 111^running 21945 21946 (gdb) 21947 222-exec-interrupt 21948 222^done 21949 (gdb) 21950 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", 21951 frame={addr="0x00010140",func="foo",args=[],file="try.c", 21952 fullname="/home/foo/bar/try.c",line="13"} 21953 (gdb) 21954 21955 (gdb) 21956 -exec-interrupt 21957 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." 21958 (gdb) 21959 21960The `-exec-jump' Command 21961------------------------ 21962 21963Synopsis 21964........ 21965 21966 -exec-jump LOCATION 21967 21968 Resumes execution of the inferior program at the location specified 21969by parameter. *Note Specify Location::, for a description of the 21970different forms of LOCATION. 21971 21972GDB Command 21973........... 21974 21975The corresponding GDB command is `jump'. 21976 21977Example 21978....... 21979 21980 -exec-jump foo.c:10 21981 *running,thread-id="all" 21982 ^running 21983 21984The `-exec-next' Command 21985------------------------ 21986 21987Synopsis 21988........ 21989 21990 -exec-next [--reverse] 21991 21992 Resumes execution of the inferior program, stopping when the 21993beginning of the next source line is reached. 21994 21995 If the `--reverse' option is specified, resumes reverse execution of 21996the inferior program, stopping at the beginning of the previous source 21997line. If you issue this command on the first line of a function, it 21998will take you back to the caller of that function, to the source line 21999where the function was called. 22000 22001GDB Command 22002........... 22003 22004The corresponding GDB command is `next'. 22005 22006Example 22007....... 22008 22009 -exec-next 22010 ^running 22011 (gdb) 22012 *stopped,reason="end-stepping-range",line="8",file="hello.c" 22013 (gdb) 22014 22015The `-exec-next-instruction' Command 22016------------------------------------ 22017 22018Synopsis 22019........ 22020 22021 -exec-next-instruction [--reverse] 22022 22023 Executes one machine instruction. If the instruction is a function 22024call, continues until the function returns. If the program stops at an 22025instruction in the middle of a source line, the address will be printed 22026as well. 22027 22028 If the `--reverse' option is specified, resumes reverse execution of 22029the inferior program, stopping at the previous instruction. If the 22030previously executed instruction was a return from another function, it 22031will continue to execute in reverse until the call to that function 22032(from the current stack frame) is reached. 22033 22034GDB Command 22035........... 22036 22037The corresponding GDB command is `nexti'. 22038 22039Example 22040....... 22041 22042 (gdb) 22043 -exec-next-instruction 22044 ^running 22045 22046 (gdb) 22047 *stopped,reason="end-stepping-range", 22048 addr="0x000100d4",line="5",file="hello.c" 22049 (gdb) 22050 22051The `-exec-return' Command 22052-------------------------- 22053 22054Synopsis 22055........ 22056 22057 -exec-return 22058 22059 Makes current function return immediately. Doesn't execute the 22060inferior. Displays the new current frame. 22061 22062GDB Command 22063........... 22064 22065The corresponding GDB command is `return'. 22066 22067Example 22068....... 22069 22070 (gdb) 22071 200-break-insert callee4 22072 200^done,bkpt={number="1",addr="0x00010734", 22073 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} 22074 (gdb) 22075 000-exec-run 22076 000^running 22077 (gdb) 22078 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 22079 frame={func="callee4",args=[], 22080 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 22081 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"} 22082 (gdb) 22083 205-break-delete 22084 205^done 22085 (gdb) 22086 111-exec-return 22087 111^done,frame={level="0",func="callee3", 22088 args=[{name="strarg", 22089 value="0x11940 \"A string argument.\""}], 22090 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 22091 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} 22092 (gdb) 22093 22094The `-exec-run' Command 22095----------------------- 22096 22097Synopsis 22098........ 22099 22100 -exec-run [--all | --thread-group N] 22101 22102 Starts execution of the inferior from the beginning. The inferior 22103executes until either a breakpoint is encountered or the program exits. 22104In the latter case the output will include an exit code, if the program 22105has exited exceptionally. 22106 22107 When no option is specified, the current inferior is started. If the 22108`--thread-group' option is specified, it should refer to a thread group 22109of type `process', and that thread group will be started. If the 22110`--all' option is specified, then all inferiors will be started. 22111 22112GDB Command 22113........... 22114 22115The corresponding GDB command is `run'. 22116 22117Examples 22118........ 22119 22120 (gdb) 22121 -break-insert main 22122 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} 22123 (gdb) 22124 -exec-run 22125 ^running 22126 (gdb) 22127 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 22128 frame={func="main",args=[],file="recursive2.c", 22129 fullname="/home/foo/bar/recursive2.c",line="4"} 22130 (gdb) 22131 22132Program exited normally: 22133 22134 (gdb) 22135 -exec-run 22136 ^running 22137 (gdb) 22138 x = 55 22139 *stopped,reason="exited-normally" 22140 (gdb) 22141 22142Program exited exceptionally: 22143 22144 (gdb) 22145 -exec-run 22146 ^running 22147 (gdb) 22148 x = 55 22149 *stopped,reason="exited",exit-code="01" 22150 (gdb) 22151 22152 Another way the program can terminate is if it receives a signal 22153such as `SIGINT'. In this case, GDB/MI displays this: 22154 22155 (gdb) 22156 *stopped,reason="exited-signalled",signal-name="SIGINT", 22157 signal-meaning="Interrupt" 22158 22159The `-exec-step' Command 22160------------------------ 22161 22162Synopsis 22163........ 22164 22165 -exec-step [--reverse] 22166 22167 Resumes execution of the inferior program, stopping when the 22168beginning of the next source line is reached, if the next source line 22169is not a function call. If it is, stop at the first instruction of the 22170called function. If the `--reverse' option is specified, resumes 22171reverse execution of the inferior program, stopping at the beginning of 22172the previously executed source line. 22173 22174GDB Command 22175........... 22176 22177The corresponding GDB command is `step'. 22178 22179Example 22180....... 22181 22182Stepping into a function: 22183 22184 -exec-step 22185 ^running 22186 (gdb) 22187 *stopped,reason="end-stepping-range", 22188 frame={func="foo",args=[{name="a",value="10"}, 22189 {name="b",value="0"}],file="recursive2.c", 22190 fullname="/home/foo/bar/recursive2.c",line="11"} 22191 (gdb) 22192 22193 Regular stepping: 22194 22195 -exec-step 22196 ^running 22197 (gdb) 22198 *stopped,reason="end-stepping-range",line="14",file="recursive2.c" 22199 (gdb) 22200 22201The `-exec-step-instruction' Command 22202------------------------------------ 22203 22204Synopsis 22205........ 22206 22207 -exec-step-instruction [--reverse] 22208 22209 Resumes the inferior which executes one machine instruction. If the 22210`--reverse' option is specified, resumes reverse execution of the 22211inferior program, stopping at the previously executed instruction. The 22212output, once GDB has stopped, will vary depending on whether we have 22213stopped in the middle of a source line or not. In the former case, the 22214address at which the program stopped will be printed as well. 22215 22216GDB Command 22217........... 22218 22219The corresponding GDB command is `stepi'. 22220 22221Example 22222....... 22223 22224 (gdb) 22225 -exec-step-instruction 22226 ^running 22227 22228 (gdb) 22229 *stopped,reason="end-stepping-range", 22230 frame={func="foo",args=[],file="try.c", 22231 fullname="/home/foo/bar/try.c",line="10"} 22232 (gdb) 22233 -exec-step-instruction 22234 ^running 22235 22236 (gdb) 22237 *stopped,reason="end-stepping-range", 22238 frame={addr="0x000100f4",func="foo",args=[],file="try.c", 22239 fullname="/home/foo/bar/try.c",line="10"} 22240 (gdb) 22241 22242The `-exec-until' Command 22243------------------------- 22244 22245Synopsis 22246........ 22247 22248 -exec-until [ LOCATION ] 22249 22250 Executes the inferior until the LOCATION specified in the argument 22251is reached. If there is no argument, the inferior executes until a 22252source line greater than the current one is reached. The reason for 22253stopping in this case will be `location-reached'. 22254 22255GDB Command 22256........... 22257 22258The corresponding GDB command is `until'. 22259 22260Example 22261....... 22262 22263 (gdb) 22264 -exec-until recursive2.c:6 22265 ^running 22266 (gdb) 22267 x = 55 22268 *stopped,reason="location-reached",frame={func="main",args=[], 22269 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"} 22270 (gdb) 22271 22272 22273File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI 22274 2227527.12 GDB/MI Stack Manipulation Commands 22276======================================== 22277 22278The `-stack-info-frame' Command 22279------------------------------- 22280 22281Synopsis 22282........ 22283 22284 -stack-info-frame 22285 22286 Get info on the selected frame. 22287 22288GDB Command 22289........... 22290 22291The corresponding GDB command is `info frame' or `frame' (without 22292arguments). 22293 22294Example 22295....... 22296 22297 (gdb) 22298 -stack-info-frame 22299 ^done,frame={level="1",addr="0x0001076c",func="callee3", 22300 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 22301 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"} 22302 (gdb) 22303 22304The `-stack-info-depth' Command 22305------------------------------- 22306 22307Synopsis 22308........ 22309 22310 -stack-info-depth [ MAX-DEPTH ] 22311 22312 Return the depth of the stack. If the integer argument MAX-DEPTH is 22313specified, do not count beyond MAX-DEPTH frames. 22314 22315GDB Command 22316........... 22317 22318There's no equivalent GDB command. 22319 22320Example 22321....... 22322 22323For a stack with frame levels 0 through 11: 22324 22325 (gdb) 22326 -stack-info-depth 22327 ^done,depth="12" 22328 (gdb) 22329 -stack-info-depth 4 22330 ^done,depth="4" 22331 (gdb) 22332 -stack-info-depth 12 22333 ^done,depth="12" 22334 (gdb) 22335 -stack-info-depth 11 22336 ^done,depth="11" 22337 (gdb) 22338 -stack-info-depth 13 22339 ^done,depth="12" 22340 (gdb) 22341 22342The `-stack-list-arguments' Command 22343----------------------------------- 22344 22345Synopsis 22346........ 22347 22348 -stack-list-arguments PRINT-VALUES 22349 [ LOW-FRAME HIGH-FRAME ] 22350 22351 Display a list of the arguments for the frames between LOW-FRAME and 22352HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, 22353list the arguments for the whole call stack. If the two arguments are 22354equal, show the single frame at the corresponding level. It is an 22355error if LOW-FRAME is larger than the actual number of frames. On the 22356other hand, HIGH-FRAME may be larger than the actual number of frames, 22357in which case only existing frames will be returned. 22358 22359 If PRINT-VALUES is 0 or `--no-values', print only the names of the 22360variables; if it is 1 or `--all-values', print also their values; and 22361if it is 2 or `--simple-values', print the name, type and value for 22362simple data types, and the name and type for arrays, structures and 22363unions. 22364 22365 Use of this command to obtain arguments in a single frame is 22366deprecated in favor of the `-stack-list-variables' command. 22367 22368GDB Command 22369........... 22370 22371GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args' 22372command which partially overlaps with the functionality of 22373`-stack-list-arguments'. 22374 22375Example 22376....... 22377 22378 (gdb) 22379 -stack-list-frames 22380 ^done, 22381 stack=[ 22382 frame={level="0",addr="0x00010734",func="callee4", 22383 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 22384 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, 22385 frame={level="1",addr="0x0001076c",func="callee3", 22386 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 22387 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, 22388 frame={level="2",addr="0x0001078c",func="callee2", 22389 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 22390 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, 22391 frame={level="3",addr="0x000107b4",func="callee1", 22392 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 22393 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, 22394 frame={level="4",addr="0x000107e0",func="main", 22395 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 22396 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] 22397 (gdb) 22398 -stack-list-arguments 0 22399 ^done, 22400 stack-args=[ 22401 frame={level="0",args=[]}, 22402 frame={level="1",args=[name="strarg"]}, 22403 frame={level="2",args=[name="intarg",name="strarg"]}, 22404 frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, 22405 frame={level="4",args=[]}] 22406 (gdb) 22407 -stack-list-arguments 1 22408 ^done, 22409 stack-args=[ 22410 frame={level="0",args=[]}, 22411 frame={level="1", 22412 args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, 22413 frame={level="2",args=[ 22414 {name="intarg",value="2"}, 22415 {name="strarg",value="0x11940 \"A string argument.\""}]}, 22416 {frame={level="3",args=[ 22417 {name="intarg",value="2"}, 22418 {name="strarg",value="0x11940 \"A string argument.\""}, 22419 {name="fltarg",value="3.5"}]}, 22420 frame={level="4",args=[]}] 22421 (gdb) 22422 -stack-list-arguments 0 2 2 22423 ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] 22424 (gdb) 22425 -stack-list-arguments 1 2 2 22426 ^done,stack-args=[frame={level="2", 22427 args=[{name="intarg",value="2"}, 22428 {name="strarg",value="0x11940 \"A string argument.\""}]}] 22429 (gdb) 22430 22431The `-stack-list-frames' Command 22432-------------------------------- 22433 22434Synopsis 22435........ 22436 22437 -stack-list-frames [ LOW-FRAME HIGH-FRAME ] 22438 22439 List the frames currently on the stack. For each frame it displays 22440the following info: 22441 22442`LEVEL' 22443 The frame number, 0 being the topmost frame, i.e., the innermost 22444 function. 22445 22446`ADDR' 22447 The `$pc' value for that frame. 22448 22449`FUNC' 22450 Function name. 22451 22452`FILE' 22453 File name of the source file where the function lives. 22454 22455`LINE' 22456 Line number corresponding to the `$pc'. 22457 22458 If invoked without arguments, this command prints a backtrace for the 22459whole stack. If given two integer arguments, it shows the frames whose 22460levels are between the two arguments (inclusive). If the two arguments 22461are equal, it shows the single frame at the corresponding level. It is 22462an error if LOW-FRAME is larger than the actual number of frames. On 22463the other hand, HIGH-FRAME may be larger than the actual number of 22464frames, in which case only existing frames will be returned. 22465 22466GDB Command 22467........... 22468 22469The corresponding GDB commands are `backtrace' and `where'. 22470 22471Example 22472....... 22473 22474Full stack backtrace: 22475 22476 (gdb) 22477 -stack-list-frames 22478 ^done,stack= 22479 [frame={level="0",addr="0x0001076c",func="foo", 22480 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"}, 22481 frame={level="1",addr="0x000107a4",func="foo", 22482 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22483 frame={level="2",addr="0x000107a4",func="foo", 22484 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22485 frame={level="3",addr="0x000107a4",func="foo", 22486 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22487 frame={level="4",addr="0x000107a4",func="foo", 22488 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22489 frame={level="5",addr="0x000107a4",func="foo", 22490 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22491 frame={level="6",addr="0x000107a4",func="foo", 22492 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22493 frame={level="7",addr="0x000107a4",func="foo", 22494 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22495 frame={level="8",addr="0x000107a4",func="foo", 22496 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22497 frame={level="9",addr="0x000107a4",func="foo", 22498 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22499 frame={level="10",addr="0x000107a4",func="foo", 22500 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22501 frame={level="11",addr="0x00010738",func="main", 22502 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}] 22503 (gdb) 22504 22505 Show frames between LOW_FRAME and HIGH_FRAME: 22506 22507 (gdb) 22508 -stack-list-frames 3 5 22509 ^done,stack= 22510 [frame={level="3",addr="0x000107a4",func="foo", 22511 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22512 frame={level="4",addr="0x000107a4",func="foo", 22513 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 22514 frame={level="5",addr="0x000107a4",func="foo", 22515 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] 22516 (gdb) 22517 22518 Show a single frame: 22519 22520 (gdb) 22521 -stack-list-frames 3 3 22522 ^done,stack= 22523 [frame={level="3",addr="0x000107a4",func="foo", 22524 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] 22525 (gdb) 22526 22527The `-stack-list-locals' Command 22528-------------------------------- 22529 22530Synopsis 22531........ 22532 22533 -stack-list-locals PRINT-VALUES 22534 22535 Display the local variable names for the selected frame. If 22536PRINT-VALUES is 0 or `--no-values', print only the names of the 22537variables; if it is 1 or `--all-values', print also their values; and 22538if it is 2 or `--simple-values', print the name, type and value for 22539simple data types, and the name and type for arrays, structures and 22540unions. In this last case, a frontend can immediately display the 22541value of simple data types and create variable objects for other data 22542types when the user wishes to explore their values in more detail. 22543 22544 This command is deprecated in favor of the `-stack-list-variables' 22545command. 22546 22547GDB Command 22548........... 22549 22550`info locals' in GDB, `gdb_get_locals' in `gdbtk'. 22551 22552Example 22553....... 22554 22555 (gdb) 22556 -stack-list-locals 0 22557 ^done,locals=[name="A",name="B",name="C"] 22558 (gdb) 22559 -stack-list-locals --all-values 22560 ^done,locals=[{name="A",value="1"},{name="B",value="2"}, 22561 {name="C",value="{1, 2, 3}"}] 22562 -stack-list-locals --simple-values 22563 ^done,locals=[{name="A",type="int",value="1"}, 22564 {name="B",type="int",value="2"},{name="C",type="int [3]"}] 22565 (gdb) 22566 22567The `-stack-list-variables' Command 22568----------------------------------- 22569 22570Synopsis 22571........ 22572 22573 -stack-list-variables PRINT-VALUES 22574 22575 Display the names of local variables and function arguments for the 22576selected frame. If PRINT-VALUES is 0 or `--no-values', print only the 22577names of the variables; if it is 1 or `--all-values', print also their 22578values; and if it is 2 or `--simple-values', print the name, type and 22579value for simple data types, and the name and type for arrays, 22580structures and unions. 22581 22582Example 22583....... 22584 22585 (gdb) 22586 -stack-list-variables --thread 1 --frame 0 --all-values 22587 ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] 22588 (gdb) 22589 22590The `-stack-select-frame' Command 22591--------------------------------- 22592 22593Synopsis 22594........ 22595 22596 -stack-select-frame FRAMENUM 22597 22598 Change the selected frame. Select a different frame FRAMENUM on the 22599stack. 22600 22601 This command in deprecated in favor of passing the `--frame' option 22602to every command. 22603 22604GDB Command 22605........... 22606 22607The corresponding GDB commands are `frame', `up', `down', 22608`select-frame', `up-silent', and `down-silent'. 22609 22610Example 22611....... 22612 22613 (gdb) 22614 -stack-select-frame 2 22615 ^done 22616 (gdb) 22617 22618 22619File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI 22620 2262127.13 GDB/MI Variable Objects 22622============================= 22623 22624Introduction to Variable Objects 22625-------------------------------- 22626 22627Variable objects are "object-oriented" MI interface for examining and 22628changing values of expressions. Unlike some other MI interfaces that 22629work with expressions, variable objects are specifically designed for 22630simple and efficient presentation in the frontend. A variable object 22631is identified by string name. When a variable object is created, the 22632frontend specifies the expression for that variable object. The 22633expression can be a simple variable, or it can be an arbitrary complex 22634expression, and can even involve CPU registers. After creating a 22635variable object, the frontend can invoke other variable object 22636operations--for example to obtain or change the value of a variable 22637object, or to change display format. 22638 22639 Variable objects have hierarchical tree structure. Any variable 22640object that corresponds to a composite type, such as structure in C, has 22641a number of child variable objects, for example corresponding to each 22642element of a structure. A child variable object can itself have 22643children, recursively. Recursion ends when we reach leaf variable 22644objects, which always have built-in types. Child variable objects are 22645created only by explicit request, so if a frontend is not interested in 22646the children of a particular variable object, no child will be created. 22647 22648 For a leaf variable object it is possible to obtain its value as a 22649string, or set the value from a string. String value can be also 22650obtained for a non-leaf variable object, but it's generally a string 22651that only indicates the type of the object, and does not list its 22652contents. Assignment to a non-leaf variable object is not allowed. 22653 22654 A frontend does not need to read the values of all variable objects 22655each time the program stops. Instead, MI provides an update command 22656that lists all variable objects whose values has changed since the last 22657update operation. This considerably reduces the amount of data that 22658must be transferred to the frontend. As noted above, children variable 22659objects are created on demand, and only leaf variable objects have a 22660real value. As result, gdb will read target memory only for leaf 22661variables that frontend has created. 22662 22663 The automatic update is not always desirable. For example, a 22664frontend might want to keep a value of some expression for future 22665reference, and never update it. For another example, fetching memory 22666is relatively slow for embedded targets, so a frontend might want to 22667disable automatic update for the variables that are either not visible 22668on the screen, or "closed". This is possible using so called "frozen 22669variable objects". Such variable objects are never implicitly updated. 22670 22671 Variable objects can be either "fixed" or "floating". For the fixed 22672variable object, the expression is parsed when the variable object is 22673created, including associating identifiers to specific variables. The 22674meaning of expression never changes. For a floating variable object 22675the values of variables whose names appear in the expressions are 22676re-evaluated every time in the context of the current frame. Consider 22677this example: 22678 22679 void do_work(...) 22680 { 22681 struct work_state state; 22682 22683 if (...) 22684 do_work(...); 22685 } 22686 22687 If a fixed variable object for the `state' variable is created in 22688this function, and we enter the recursive call, the the variable object 22689will report the value of `state' in the top-level `do_work' invocation. 22690On the other hand, a floating variable object will report the value of 22691`state' in the current frame. 22692 22693 If an expression specified when creating a fixed variable object 22694refers to a local variable, the variable object becomes bound to the 22695thread and frame in which the variable object is created. When such 22696variable object is updated, GDB makes sure that the thread/frame 22697combination the variable object is bound to still exists, and 22698re-evaluates the variable object in context of that thread/frame. 22699 22700 The following is the complete set of GDB/MI operations defined to 22701access this functionality: 22702 22703*Operation* *Description* 22704`-enable-pretty-printing' enable Python-based pretty-printing 22705`-var-create' create a variable object 22706`-var-delete' delete the variable object and/or its 22707 children 22708`-var-set-format' set the display format of this variable 22709`-var-show-format' show the display format of this variable 22710`-var-info-num-children' tells how many children this object has 22711`-var-list-children' return a list of the object's children 22712`-var-info-type' show the type of this variable object 22713`-var-info-expression' print parent-relative expression that this 22714 variable object represents 22715`-var-info-path-expression' print full expression that this variable 22716 object represents 22717`-var-show-attributes' is this variable editable? does it exist 22718 here? 22719`-var-evaluate-expression' get the value of this variable 22720`-var-assign' set the value of this variable 22721`-var-update' update the variable and its children 22722`-var-set-frozen' set frozeness attribute 22723`-var-set-update-range' set range of children to display on update 22724 22725 In the next subsection we describe each operation in detail and 22726suggest how it can be used. 22727 22728Description And Use of Operations on Variable Objects 22729----------------------------------------------------- 22730 22731The `-enable-pretty-printing' Command 22732------------------------------------- 22733 22734 -enable-pretty-printing 22735 22736 GDB allows Python-based visualizers to affect the output of the MI 22737variable object commands. However, because there was no way to 22738implement this in a fully backward-compatible way, a front end must 22739request that this functionality be enabled. 22740 22741 Once enabled, this feature cannot be disabled. 22742 22743 Note that if Python support has not been compiled into GDB, this 22744command will still succeed (and do nothing). 22745 22746 This feature is currently (as of GDB 7.0) experimental, and may work 22747differently in future versions of GDB. 22748 22749The `-var-create' Command 22750------------------------- 22751 22752Synopsis 22753........ 22754 22755 -var-create {NAME | "-"} 22756 {FRAME-ADDR | "*" | "@"} EXPRESSION 22757 22758 This operation creates a variable object, which allows the 22759monitoring of a variable, the result of an expression, a memory cell or 22760a CPU register. 22761 22762 The NAME parameter is the string by which the object can be 22763referenced. It must be unique. If `-' is specified, the varobj system 22764will generate a string "varNNNNNN" automatically. It will be unique 22765provided that one does not specify NAME of that format. The command 22766fails if a duplicate name is found. 22767 22768 The frame under which the expression should be evaluated can be 22769specified by FRAME-ADDR. A `*' indicates that the current frame should 22770be used. A `@' indicates that a floating variable object must be 22771created. 22772 22773 EXPRESSION is any expression valid on the current language set (must 22774not begin with a `*'), or one of the following: 22775 22776 * `*ADDR', where ADDR is the address of a memory cell 22777 22778 * `*ADDR-ADDR' -- a memory address range (TBD) 22779 22780 * `$REGNAME' -- a CPU register name 22781 22782 A varobj's contents may be provided by a Python-based 22783pretty-printer. In this case the varobj is known as a "dynamic 22784varobj". Dynamic varobjs have slightly different semantics in some 22785cases. If the `-enable-pretty-printing' command is not sent, then GDB 22786will never create a dynamic varobj. This ensures backward 22787compatibility for existing clients. 22788 22789Result 22790...... 22791 22792This operation returns attributes of the newly-created varobj. These 22793are: 22794 22795`name' 22796 The name of the varobj. 22797 22798`numchild' 22799 The number of children of the varobj. This number is not 22800 necessarily reliable for a dynamic varobj. Instead, you must 22801 examine the `has_more' attribute. 22802 22803`value' 22804 The varobj's scalar value. For a varobj whose type is some sort of 22805 aggregate (e.g., a `struct'), or for a dynamic varobj, this value 22806 will not be interesting. 22807 22808`type' 22809 The varobj's type. This is a string representation of the type, as 22810 would be printed by the GDB CLI. 22811 22812`thread-id' 22813 If a variable object is bound to a specific thread, then this is 22814 the thread's identifier. 22815 22816`has_more' 22817 For a dynamic varobj, this indicates whether there appear to be any 22818 children available. For a non-dynamic varobj, this will be 0. 22819 22820`dynamic' 22821 This attribute will be present and have the value `1' if the 22822 varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 22823 then this attribute will not be present. 22824 22825`displayhint' 22826 A dynamic varobj can supply a display hint to the front end. The 22827 value comes directly from the Python pretty-printer object's 22828 `display_hint' method. *Note Pretty Printing API::. 22829 22830`has-side-effects' 22831 If updating this varobj, or any of its children, is known to have 22832 a side effect on the target (such as modifying the state of a 22833 hardware device), this will be 1. Otherwise, it will be omitted. 22834 If it is this varobj (rather than just a child) which has side 22835 effects, then the varobj will be created frozen. Otherwise, the 22836 varobj may be safely updated but its frozen children will be 22837 skipped by default. Care should be taken passing this varobj's 22838 expression to e.g. `-data-evaluate-expression'. 22839 22840 Typical output will look like this: 22841 22842 name="NAME",numchild="N",type="TYPE",thread-id="M", 22843 has_more="HAS_MORE" 22844 22845The `-var-delete' Command 22846------------------------- 22847 22848Synopsis 22849........ 22850 22851 -var-delete [ -c ] NAME 22852 22853 Deletes a previously created variable object and all of its children. 22854With the `-c' option, just deletes the children. 22855 22856 Returns an error if the object NAME is not found. 22857 22858The `-var-set-format' Command 22859----------------------------- 22860 22861Synopsis 22862........ 22863 22864 -var-set-format NAME FORMAT-SPEC 22865 22866 Sets the output format for the value of the object NAME to be 22867FORMAT-SPEC. 22868 22869 The syntax for the FORMAT-SPEC is as follows: 22870 22871 FORMAT-SPEC ==> 22872 {binary | decimal | hexadecimal | octal | natural} 22873 22874 The natural format is the default format choosen automatically based 22875on the variable type (like decimal for an `int', hex for pointers, 22876etc.). 22877 22878 For a variable with children, the format is set only on the variable 22879itself, and the children are not affected. 22880 22881The `-var-show-format' Command 22882------------------------------ 22883 22884Synopsis 22885........ 22886 22887 -var-show-format NAME 22888 22889 Returns the format used to display the value of the object NAME. 22890 22891 FORMAT ==> 22892 FORMAT-SPEC 22893 22894The `-var-info-num-children' Command 22895------------------------------------ 22896 22897Synopsis 22898........ 22899 22900 -var-info-num-children NAME 22901 22902 Returns the number of children of a variable object NAME: 22903 22904 numchild=N 22905 22906 Note that this number is not completely reliable for a dynamic 22907varobj. It will return the current number of children, but more 22908children may be available. 22909 22910The `-var-list-children' Command 22911-------------------------------- 22912 22913Synopsis 22914........ 22915 22916 -var-list-children [PRINT-VALUES] NAME [FROM TO] 22917Return a list of the children of the specified variable object and 22918create variable objects for them, if they do not already exist. With a 22919single argument or if PRINT-VALUES has a value of 0 or `--no-values', 22920print only the names of the variables; if PRINT-VALUES is 1 or 22921`--all-values', also print their values; and if it is 2 or 22922`--simple-values' print the name and value for simple data types and 22923just the name for arrays, structures and unions. 22924 22925 FROM and TO, if specified, indicate the range of children to report. 22926If FROM or TO is less than zero, the range is reset and all children 22927will be reported. Otherwise, children starting at FROM (zero-based) 22928and up to and excluding TO will be reported. 22929 22930 If a child range is requested, it will only affect the current call 22931to `-var-list-children', but not future calls to `-var-update'. For 22932this, you must instead use `-var-set-update-range'. The intent of this 22933approach is to enable a front end to implement any update approach it 22934likes; for example, scrolling a view may cause the front end to request 22935more children with `-var-list-children', and then the front end could 22936call `-var-set-update-range' with a different range to ensure that 22937future updates are restricted to just the visible items. 22938 22939 For each child the following results are returned: 22940 22941NAME 22942 Name of the variable object created for this child. 22943 22944EXP 22945 The expression to be shown to the user by the front end to 22946 designate this child. For example this may be the name of a 22947 structure member. 22948 22949 For a dynamic varobj, this value cannot be used to form an 22950 expression. There is no way to do this at all with a dynamic 22951 varobj. 22952 22953 For C/C++ structures there are several pseudo children returned to 22954 designate access qualifiers. For these pseudo children EXP is 22955 `public', `private', or `protected'. In this case the type and 22956 value are not present. 22957 22958 A dynamic varobj will not report the access qualifying 22959 pseudo-children, regardless of the language. This information is 22960 not available at all with a dynamic varobj. 22961 22962NUMCHILD 22963 Number of children this child has. For a dynamic varobj, this 22964 will be 0. 22965 22966TYPE 22967 The type of the child. 22968 22969VALUE 22970 If values were requested, this is the value. 22971 22972THREAD-ID 22973 If this variable object is associated with a thread, this is the 22974 thread id. Otherwise this result is not present. 22975 22976FROZEN 22977 If the variable object is frozen, this variable will be present 22978 with a value of 1. 22979 22980 The result may have its own attributes: 22981 22982`displayhint' 22983 A dynamic varobj can supply a display hint to the front end. The 22984 value comes directly from the Python pretty-printer object's 22985 `display_hint' method. *Note Pretty Printing API::. 22986 22987`has_more' 22988 This is an integer attribute which is nonzero if there are children 22989 remaining after the end of the selected range. 22990 22991Example 22992....... 22993 22994 (gdb) 22995 -var-list-children n 22996 ^done,numchild=N,children=[child={name=NAME,exp=EXP, 22997 numchild=N,type=TYPE},(repeats N times)] 22998 (gdb) 22999 -var-list-children --all-values n 23000 ^done,numchild=N,children=[child={name=NAME,exp=EXP, 23001 numchild=N,value=VALUE,type=TYPE},(repeats N times)] 23002 23003The `-var-info-type' Command 23004---------------------------- 23005 23006Synopsis 23007........ 23008 23009 -var-info-type NAME 23010 23011 Returns the type of the specified variable NAME. The type is 23012returned as a string in the same format as it is output by the GDB CLI: 23013 23014 type=TYPENAME 23015 23016The `-var-info-expression' Command 23017---------------------------------- 23018 23019Synopsis 23020........ 23021 23022 -var-info-expression NAME 23023 23024 Returns a string that is suitable for presenting this variable 23025object in user interface. The string is generally not valid expression 23026in the current language, and cannot be evaluated. 23027 23028 For example, if `a' is an array, and variable object `A' was created 23029for `a', then we'll get this output: 23030 23031 (gdb) -var-info-expression A.1 23032 ^done,lang="C",exp="1" 23033 23034Here, the values of `lang' can be `{"C" | "C++" | "Java"}'. 23035 23036 Note that the output of the `-var-list-children' command also 23037includes those expressions, so the `-var-info-expression' command is of 23038limited use. 23039 23040The `-var-info-path-expression' Command 23041--------------------------------------- 23042 23043Synopsis 23044........ 23045 23046 -var-info-path-expression NAME 23047 23048 Returns an expression that can be evaluated in the current context 23049and will yield the same value that a variable object has. Compare this 23050with the `-var-info-expression' command, which result can be used only 23051for UI presentation. Typical use of the `-var-info-path-expression' 23052command is creating a watchpoint from a variable object. 23053 23054 This command is currently not valid for children of a dynamic varobj, 23055and will give an error when invoked on one. 23056 23057 For example, suppose `C' is a C++ class, derived from class `Base', 23058and that the `Base' class has a member called `m_size'. Assume a 23059variable `c' is has the type of `C' and a variable object `C' was 23060created for variable `c'. Then, we'll get this output: 23061 (gdb) -var-info-path-expression C.Base.public.m_size 23062 ^done,path_expr=((Base)c).m_size) 23063 23064The `-var-show-attributes' Command 23065---------------------------------- 23066 23067Synopsis 23068........ 23069 23070 -var-show-attributes NAME 23071 23072 List attributes of the specified variable object NAME: 23073 23074 status=ATTR [ ( ,ATTR )* ] 23075 23076where ATTR is `{ { editable | noneditable } | TBD }'. 23077 23078The `-var-evaluate-expression' Command 23079-------------------------------------- 23080 23081Synopsis 23082........ 23083 23084 -var-evaluate-expression [-f FORMAT-SPEC] NAME 23085 23086 Evaluates the expression that is represented by the specified 23087variable object and returns its value as a string. The format of the 23088string can be specified with the `-f' option. The possible values of 23089this option are the same as for `-var-set-format' (*note 23090-var-set-format::). If the `-f' option is not specified, the current 23091display format will be used. The current display format can be changed 23092using the `-var-set-format' command. 23093 23094 value=VALUE 23095 23096 Note that one must invoke `-var-list-children' for a variable before 23097the value of a child variable can be evaluated. 23098 23099The `-var-assign' Command 23100------------------------- 23101 23102Synopsis 23103........ 23104 23105 -var-assign NAME EXPRESSION 23106 23107 Assigns the value of EXPRESSION to the variable object specified by 23108NAME. The object must be `editable'. If the variable's value is 23109altered by the assign, the variable will show up in any subsequent 23110`-var-update' list. 23111 23112Example 23113....... 23114 23115 (gdb) 23116 -var-assign var1 3 23117 ^done,value="3" 23118 (gdb) 23119 -var-update * 23120 ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] 23121 (gdb) 23122 23123The `-var-update' Command 23124------------------------- 23125 23126Synopsis 23127........ 23128 23129 -var-update [PRINT-VALUES] {NAME | "*"} 23130 23131 Reevaluate the expressions corresponding to the variable object NAME 23132and all its direct and indirect children, and return the list of 23133variable objects whose values have changed; NAME must be a root 23134variable object. Here, "changed" means that the result of 23135`-var-evaluate-expression' before and after the `-var-update' is 23136different. If `*' is used as the variable object names, all existing 23137variable objects are updated, except for frozen ones (*note 23138-var-set-frozen::). The option PRINT-VALUES determines whether both 23139names and values, or just names are printed. The possible values of 23140this option are the same as for `-var-list-children' (*note 23141-var-list-children::). It is recommended to use the `--all-values' 23142option, to reduce the number of MI commands needed on each program stop. 23143 23144 With the `*' parameter, if a variable object is bound to a currently 23145running thread, it will not be updated, without any diagnostic. 23146 23147 If `-var-set-update-range' was previously used on a varobj, then 23148only the selected range of children will be reported. 23149 23150 `-var-update' reports all the changed varobjs in a tuple named 23151`changelist'. 23152 23153 Each item in the change list is itself a tuple holding: 23154 23155`name' 23156 The name of the varobj. 23157 23158`value' 23159 If values were requested for this update, then this field will be 23160 present and will hold the value of the varobj. 23161 23162`in_scope' 23163 This field is a string which may take one of three values: 23164 23165 `"true"' 23166 The variable object's current value is valid. 23167 23168 `"false"' 23169 The variable object does not currently hold a valid value but 23170 it may hold one in the future if its associated expression 23171 comes back into scope. 23172 23173 `"invalid"' 23174 The variable object no longer holds a valid value. This can 23175 occur when the executable file being debugged has changed, 23176 either through recompilation or by using the GDB `file' 23177 command. The front end should normally choose to delete 23178 these variable objects. 23179 23180 In the future new values may be added to this list so the front 23181 should be prepared for this possibility. *Note GDB/MI Development 23182 and Front Ends: GDB/MI Development and Front Ends. 23183 23184`type_changed' 23185 This is only present if the varobj is still valid. If the type 23186 changed, then this will be the string `true'; otherwise it will be 23187 `false'. 23188 23189`new_type' 23190 If the varobj's type changed, then this field will be present and 23191 will hold the new type. 23192 23193`new_num_children' 23194 For a dynamic varobj, if the number of children changed, or if the 23195 type changed, this will be the new number of children. 23196 23197 The `numchild' field in other varobj responses is generally not 23198 valid for a dynamic varobj - it will show the number of children 23199 that GDB knows about, but because dynamic varobjs lazily 23200 instantiate their children, this will not reflect the number of 23201 children which may be available. 23202 23203 The `new_num_children' attribute only reports changes to the 23204 number of children known by GDB. This is the only way to detect 23205 whether an update has removed children (which necessarily can only 23206 happen at the end of the update range). 23207 23208`displayhint' 23209 The display hint, if any. 23210 23211`has_more' 23212 This is an integer value, which will be 1 if there are more 23213 children available outside the varobj's update range. 23214 23215`dynamic' 23216 This attribute will be present and have the value `1' if the 23217 varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 23218 then this attribute will not be present. 23219 23220`new_children' 23221 If new children were added to a dynamic varobj within the selected 23222 update range (as set by `-var-set-update-range'), then they will 23223 be listed in this attribute. 23224 23225Example 23226....... 23227 23228 (gdb) 23229 -var-assign var1 3 23230 ^done,value="3" 23231 (gdb) 23232 -var-update --all-values var1 23233 ^done,changelist=[{name="var1",value="3",in_scope="true", 23234 type_changed="false"}] 23235 (gdb) 23236 23237The `-var-set-frozen' Command 23238----------------------------- 23239 23240Synopsis 23241........ 23242 23243 -var-set-frozen NAME FLAG 23244 23245 Set the frozenness flag on the variable object NAME. The FLAG 23246parameter should be either `1' to make the variable frozen or `0' to 23247make it unfrozen. If a variable object is frozen, then neither itself, 23248nor any of its children, are implicitly updated by `-var-update' of a 23249parent variable or by `-var-update *'. Only `-var-update' of the 23250variable itself will update its value and values of its children. 23251After a variable object is unfrozen, it is implicitly updated by all 23252subsequent `-var-update' operations. Unfreezing a variable does not 23253update it, only subsequent `-var-update' does. 23254 23255Example 23256....... 23257 23258 (gdb) 23259 -var-set-frozen V 1 23260 ^done 23261 (gdb) 23262 23263The `-var-set-update-range' command 23264----------------------------------- 23265 23266Synopsis 23267........ 23268 23269 -var-set-update-range NAME FROM TO 23270 23271 Set the range of children to be returned by future invocations of 23272`-var-update'. 23273 23274 FROM and TO indicate the range of children to report. If FROM or TO 23275is less than zero, the range is reset and all children will be 23276reported. Otherwise, children starting at FROM (zero-based) and up to 23277and excluding TO will be reported. 23278 23279Example 23280....... 23281 23282 (gdb) 23283 -var-set-update-range V 1 2 23284 ^done 23285 23286The `-var-set-visualizer' command 23287--------------------------------- 23288 23289Synopsis 23290........ 23291 23292 -var-set-visualizer NAME VISUALIZER 23293 23294 Set a visualizer for the variable object NAME. 23295 23296 VISUALIZER is the visualizer to use. The special value `None' means 23297to disable any visualizer in use. 23298 23299 If not `None', VISUALIZER must be a Python expression. This 23300expression must evaluate to a callable object which accepts a single 23301argument. GDB will call this object with the value of the varobj NAME 23302as an argument (this is done so that the same Python pretty-printing 23303code can be used for both the CLI and MI). When called, this object 23304must return an object which conforms to the pretty-printing interface 23305(*note Pretty Printing API::). 23306 23307 The pre-defined function `gdb.default_visualizer' may be used to 23308select a visualizer by following the built-in process (*note Selecting 23309Pretty-Printers::). This is done automatically when a varobj is 23310created, and so ordinarily is not needed. 23311 23312 This feature is only available if Python support is enabled. The MI 23313command `-list-features' (*note GDB/MI Miscellaneous Commands::) can be 23314used to check this. 23315 23316Example 23317....... 23318 23319Resetting the visualizer: 23320 23321 (gdb) 23322 -var-set-visualizer V None 23323 ^done 23324 23325 Reselecting the default (type-based) visualizer: 23326 23327 (gdb) 23328 -var-set-visualizer V gdb.default_visualizer 23329 ^done 23330 23331 Suppose `SomeClass' is a visualizer class. A lambda expression can 23332be used to instantiate this class for a varobj: 23333 23334 (gdb) 23335 -var-set-visualizer V "lambda val: SomeClass()" 23336 ^done 23337 23338 23339File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI 23340 2334127.14 GDB/MI Data Manipulation 23342============================== 23343 23344This section describes the GDB/MI commands that manipulate data: 23345examine memory and registers, evaluate expressions, etc. 23346 23347The `-data-disassemble' Command 23348------------------------------- 23349 23350Synopsis 23351........ 23352 23353 -data-disassemble 23354 [ -s START-ADDR -e END-ADDR ] 23355 | [ -f FILENAME -l LINENUM [ -n LINES ] ] 23356 -- MODE 23357 23358Where: 23359 23360`START-ADDR' 23361 is the beginning address (or `$pc') 23362 23363`END-ADDR' 23364 is the end address 23365 23366`FILENAME' 23367 is the name of the file to disassemble 23368 23369`LINENUM' 23370 is the line number to disassemble around 23371 23372`LINES' 23373 is the number of disassembly lines to be produced. If it is -1, 23374 the whole function will be disassembled, in case no END-ADDR is 23375 specified. If END-ADDR is specified as a non-zero value, and 23376 LINES is lower than the number of disassembly lines between 23377 START-ADDR and END-ADDR, only LINES lines are displayed; if LINES 23378 is higher than the number of lines between START-ADDR and 23379 END-ADDR, only the lines up to END-ADDR are displayed. 23380 23381`MODE' 23382 is either 0 (meaning only disassembly) or 1 (meaning mixed source 23383 and disassembly). 23384 23385Result 23386...... 23387 23388The output for each instruction is composed of four fields: 23389 23390 * Address 23391 23392 * Func-name 23393 23394 * Offset 23395 23396 * Instruction 23397 23398 Note that whatever included in the instruction field, is not 23399manipulated directly by GDB/MI, i.e., it is not possible to adjust its 23400format. 23401 23402GDB Command 23403........... 23404 23405There's no direct mapping from this command to the CLI. 23406 23407Example 23408....... 23409 23410Disassemble from the current value of `$pc' to `$pc + 20': 23411 23412 (gdb) 23413 -data-disassemble -s $pc -e "$pc + 20" -- 0 23414 ^done, 23415 asm_insns=[ 23416 {address="0x000107c0",func-name="main",offset="4", 23417 inst="mov 2, %o0"}, 23418 {address="0x000107c4",func-name="main",offset="8", 23419 inst="sethi %hi(0x11800), %o2"}, 23420 {address="0x000107c8",func-name="main",offset="12", 23421 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, 23422 {address="0x000107cc",func-name="main",offset="16", 23423 inst="sethi %hi(0x11800), %o2"}, 23424 {address="0x000107d0",func-name="main",offset="20", 23425 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] 23426 (gdb) 23427 23428 Disassemble the whole `main' function. Line 32 is part of `main'. 23429 23430 -data-disassemble -f basics.c -l 32 -- 0 23431 ^done,asm_insns=[ 23432 {address="0x000107bc",func-name="main",offset="0", 23433 inst="save %sp, -112, %sp"}, 23434 {address="0x000107c0",func-name="main",offset="4", 23435 inst="mov 2, %o0"}, 23436 {address="0x000107c4",func-name="main",offset="8", 23437 inst="sethi %hi(0x11800), %o2"}, 23438 [...] 23439 {address="0x0001081c",func-name="main",offset="96",inst="ret "}, 23440 {address="0x00010820",func-name="main",offset="100",inst="restore "}] 23441 (gdb) 23442 23443 Disassemble 3 instructions from the start of `main': 23444 23445 (gdb) 23446 -data-disassemble -f basics.c -l 32 -n 3 -- 0 23447 ^done,asm_insns=[ 23448 {address="0x000107bc",func-name="main",offset="0", 23449 inst="save %sp, -112, %sp"}, 23450 {address="0x000107c0",func-name="main",offset="4", 23451 inst="mov 2, %o0"}, 23452 {address="0x000107c4",func-name="main",offset="8", 23453 inst="sethi %hi(0x11800), %o2"}] 23454 (gdb) 23455 23456 Disassemble 3 instructions from the start of `main' in mixed mode: 23457 23458 (gdb) 23459 -data-disassemble -f basics.c -l 32 -n 3 -- 1 23460 ^done,asm_insns=[ 23461 src_and_asm_line={line="31", 23462 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 23463 testsuite/gdb.mi/basics.c",line_asm_insn=[ 23464 {address="0x000107bc",func-name="main",offset="0", 23465 inst="save %sp, -112, %sp"}]}, 23466 src_and_asm_line={line="32", 23467 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 23468 testsuite/gdb.mi/basics.c",line_asm_insn=[ 23469 {address="0x000107c0",func-name="main",offset="4", 23470 inst="mov 2, %o0"}, 23471 {address="0x000107c4",func-name="main",offset="8", 23472 inst="sethi %hi(0x11800), %o2"}]}] 23473 (gdb) 23474 23475The `-data-evaluate-expression' Command 23476--------------------------------------- 23477 23478Synopsis 23479........ 23480 23481 -data-evaluate-expression EXPR 23482 23483 Evaluate EXPR as an expression. The expression could contain an 23484inferior function call. The function call will execute synchronously. 23485If the expression contains spaces, it must be enclosed in double quotes. 23486 23487GDB Command 23488........... 23489 23490The corresponding GDB commands are `print', `output', and `call'. In 23491`gdbtk' only, there's a corresponding `gdb_eval' command. 23492 23493Example 23494....... 23495 23496In the following example, the numbers that precede the commands are the 23497"tokens" described in *note GDB/MI Command Syntax: GDB/MI Command 23498Syntax. Notice how GDB/MI returns the same tokens in its output. 23499 23500 211-data-evaluate-expression A 23501 211^done,value="1" 23502 (gdb) 23503 311-data-evaluate-expression &A 23504 311^done,value="0xefffeb7c" 23505 (gdb) 23506 411-data-evaluate-expression A+3 23507 411^done,value="4" 23508 (gdb) 23509 511-data-evaluate-expression "A + 3" 23510 511^done,value="4" 23511 (gdb) 23512 23513The `-data-list-changed-registers' Command 23514------------------------------------------ 23515 23516Synopsis 23517........ 23518 23519 -data-list-changed-registers 23520 23521 Display a list of the registers that have changed. 23522 23523GDB Command 23524........... 23525 23526GDB doesn't have a direct analog for this command; `gdbtk' has the 23527corresponding command `gdb_changed_register_list'. 23528 23529Example 23530....... 23531 23532On a PPC MBX board: 23533 23534 (gdb) 23535 -exec-continue 23536 ^running 23537 23538 (gdb) 23539 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={ 23540 func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", 23541 line="5"} 23542 (gdb) 23543 -data-list-changed-registers 23544 ^done,changed-registers=["0","1","2","4","5","6","7","8","9", 23545 "10","11","13","14","15","16","17","18","19","20","21","22","23", 23546 "24","25","26","27","28","30","31","64","65","66","67","69"] 23547 (gdb) 23548 23549The `-data-list-register-names' Command 23550--------------------------------------- 23551 23552Synopsis 23553........ 23554 23555 -data-list-register-names [ ( REGNO )+ ] 23556 23557 Show a list of register names for the current target. If no 23558arguments are given, it shows a list of the names of all the registers. 23559If integer numbers are given as arguments, it will print a list of the 23560names of the registers corresponding to the arguments. To ensure 23561consistency between a register name and its number, the output list may 23562include empty register names. 23563 23564GDB Command 23565........... 23566 23567GDB does not have a command which corresponds to 23568`-data-list-register-names'. In `gdbtk' there is a corresponding 23569command `gdb_regnames'. 23570 23571Example 23572....... 23573 23574For the PPC MBX board: 23575 (gdb) 23576 -data-list-register-names 23577 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", 23578 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", 23579 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", 23580 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", 23581 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", 23582 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", 23583 "", "pc","ps","cr","lr","ctr","xer"] 23584 (gdb) 23585 -data-list-register-names 1 2 3 23586 ^done,register-names=["r1","r2","r3"] 23587 (gdb) 23588 23589The `-data-list-register-values' Command 23590---------------------------------------- 23591 23592Synopsis 23593........ 23594 23595 -data-list-register-values FMT [ ( REGNO )*] 23596 23597 Display the registers' contents. FMT is the format according to 23598which the registers' contents are to be returned, followed by an 23599optional list of numbers specifying the registers to display. A 23600missing list of numbers indicates that the contents of all the 23601registers must be returned. 23602 23603 Allowed formats for FMT are: 23604 23605`x' 23606 Hexadecimal 23607 23608`o' 23609 Octal 23610 23611`t' 23612 Binary 23613 23614`d' 23615 Decimal 23616 23617`r' 23618 Raw 23619 23620`N' 23621 Natural 23622 23623GDB Command 23624........... 23625 23626The corresponding GDB commands are `info reg', `info all-reg', and (in 23627`gdbtk') `gdb_fetch_registers'. 23628 23629Example 23630....... 23631 23632For a PPC MBX board (note: line breaks are for readability only, they 23633don't appear in the actual output): 23634 23635 (gdb) 23636 -data-list-register-values r 64 65 23637 ^done,register-values=[{number="64",value="0xfe00a300"}, 23638 {number="65",value="0x00029002"}] 23639 (gdb) 23640 -data-list-register-values x 23641 ^done,register-values=[{number="0",value="0xfe0043c8"}, 23642 {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, 23643 {number="3",value="0x0"},{number="4",value="0xa"}, 23644 {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, 23645 {number="7",value="0xfe011e98"},{number="8",value="0x2"}, 23646 {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, 23647 {number="11",value="0x1"},{number="12",value="0x0"}, 23648 {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, 23649 {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, 23650 {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, 23651 {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, 23652 {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, 23653 {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, 23654 {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, 23655 {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, 23656 {number="29",value="0x0"},{number="30",value="0xfe010000"}, 23657 {number="31",value="0x0"},{number="32",value="0x0"}, 23658 {number="33",value="0x0"},{number="34",value="0x0"}, 23659 {number="35",value="0x0"},{number="36",value="0x0"}, 23660 {number="37",value="0x0"},{number="38",value="0x0"}, 23661 {number="39",value="0x0"},{number="40",value="0x0"}, 23662 {number="41",value="0x0"},{number="42",value="0x0"}, 23663 {number="43",value="0x0"},{number="44",value="0x0"}, 23664 {number="45",value="0x0"},{number="46",value="0x0"}, 23665 {number="47",value="0x0"},{number="48",value="0x0"}, 23666 {number="49",value="0x0"},{number="50",value="0x0"}, 23667 {number="51",value="0x0"},{number="52",value="0x0"}, 23668 {number="53",value="0x0"},{number="54",value="0x0"}, 23669 {number="55",value="0x0"},{number="56",value="0x0"}, 23670 {number="57",value="0x0"},{number="58",value="0x0"}, 23671 {number="59",value="0x0"},{number="60",value="0x0"}, 23672 {number="61",value="0x0"},{number="62",value="0x0"}, 23673 {number="63",value="0x0"},{number="64",value="0xfe00a300"}, 23674 {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, 23675 {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, 23676 {number="69",value="0x20002b03"}] 23677 (gdb) 23678 23679The `-data-read-memory' Command 23680------------------------------- 23681 23682This command is deprecated, use `-data-read-memory-bytes' instead. 23683 23684Synopsis 23685........ 23686 23687 -data-read-memory [ -o BYTE-OFFSET ] 23688 ADDRESS WORD-FORMAT WORD-SIZE 23689 NR-ROWS NR-COLS [ ASCHAR ] 23690 23691where: 23692 23693`ADDRESS' 23694 An expression specifying the address of the first memory word to be 23695 read. Complex expressions containing embedded white space should 23696 be quoted using the C convention. 23697 23698`WORD-FORMAT' 23699 The format to be used to print the memory words. The notation is 23700 the same as for GDB's `print' command (*note Output Formats: 23701 Output Formats.). 23702 23703`WORD-SIZE' 23704 The size of each memory word in bytes. 23705 23706`NR-ROWS' 23707 The number of rows in the output table. 23708 23709`NR-COLS' 23710 The number of columns in the output table. 23711 23712`ASCHAR' 23713 If present, indicates that each row should include an ASCII dump. 23714 The value of ASCHAR is used as a padding character when a byte is 23715 not a member of the printable ASCII character set (printable ASCII 23716 characters are those whose code is between 32 and 126, 23717 inclusively). 23718 23719`BYTE-OFFSET' 23720 An offset to add to the ADDRESS before fetching memory. 23721 23722 This command displays memory contents as a table of NR-ROWS by 23723NR-COLS words, each word being WORD-SIZE bytes. In total, `NR-ROWS * 23724NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes'). 23725Should less than the requested number of bytes be returned by the 23726target, the missing words are identified using `N/A'. The number of 23727bytes read from the target is returned in `nr-bytes' and the starting 23728address used to read memory in `addr'. 23729 23730 The address of the next/previous row or page is available in 23731`next-row' and `prev-row', `next-page' and `prev-page'. 23732 23733GDB Command 23734........... 23735 23736The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory 23737read command. 23738 23739Example 23740....... 23741 23742Read six bytes of memory starting at `bytes+6' but then offset by `-6' 23743bytes. Format as three rows of two columns. One byte per word. 23744Display each word in hex. 23745 23746 (gdb) 23747 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 23748 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", 23749 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", 23750 prev-page="0x0000138a",memory=[ 23751 {addr="0x00001390",data=["0x00","0x01"]}, 23752 {addr="0x00001392",data=["0x02","0x03"]}, 23753 {addr="0x00001394",data=["0x04","0x05"]}] 23754 (gdb) 23755 23756 Read two bytes of memory starting at address `shorts + 64' and 23757display as a single word formatted in decimal. 23758 23759 (gdb) 23760 5-data-read-memory shorts+64 d 2 1 1 23761 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", 23762 next-row="0x00001512",prev-row="0x0000150e", 23763 next-page="0x00001512",prev-page="0x0000150e",memory=[ 23764 {addr="0x00001510",data=["128"]}] 23765 (gdb) 23766 23767 Read thirty two bytes of memory starting at `bytes+16' and format as 23768eight rows of four columns. Include a string encoding with `x' used as 23769the non-printable character. 23770 23771 (gdb) 23772 4-data-read-memory bytes+16 x 1 8 4 x 23773 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", 23774 next-row="0x000013c0",prev-row="0x0000139c", 23775 next-page="0x000013c0",prev-page="0x00001380",memory=[ 23776 {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, 23777 {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, 23778 {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, 23779 {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, 23780 {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, 23781 {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, 23782 {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, 23783 {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] 23784 (gdb) 23785 23786The `-data-read-memory-bytes' Command 23787------------------------------------- 23788 23789Synopsis 23790........ 23791 23792 -data-read-memory-bytes [ -o BYTE-OFFSET ] 23793 ADDRESS COUNT 23794 23795where: 23796 23797`ADDRESS' 23798 An expression specifying the address of the first memory word to be 23799 read. Complex expressions containing embedded white space should 23800 be quoted using the C convention. 23801 23802`COUNT' 23803 The number of bytes to read. This should be an integer literal. 23804 23805`BYTE-OFFSET' 23806 The offsets in bytes relative to ADDRESS at which to start 23807 reading. This should be an integer literal. This option is 23808 provided so that a frontend is not required to first evaluate 23809 address and then perform address arithmetics itself. 23810 23811 23812 This command attempts to read all accessible memory regions in the 23813specified range. First, all regions marked as unreadable in the memory 23814map (if one is defined) will be skipped. *Note Memory Region 23815Attributes::. Second, GDB will attempt to read the remaining regions. 23816For each one, if reading full region results in an errors, GDB will try 23817to read a subset of the region. 23818 23819 In general, every single byte in the region may be readable or not, 23820and the only way to read every readable byte is to try a read at every 23821address, which is not practical. Therefore, GDB will attempt to read 23822all accessible bytes at either beginning or the end of the region, 23823using a binary division scheme. This heuristic works well for reading 23824accross a memory map boundary. Note that if a region has a readable 23825range that is neither at the beginning or the end, GDB will not read it. 23826 23827 The result record (*note GDB/MI Result Records::) that is output of 23828the command includes a field named `memory' whose content is a list of 23829tuples. Each tuple represent a successfully read memory block and has 23830the following fields: 23831 23832`begin' 23833 The start address of the memory block, as hexadecimal literal. 23834 23835`end' 23836 The end address of the memory block, as hexadecimal literal. 23837 23838`offset' 23839 The offset of the memory block, as hexadecimal literal, relative to 23840 the start address passed to `-data-read-memory-bytes'. 23841 23842`contents' 23843 The contents of the memory block, in hex. 23844 23845 23846GDB Command 23847........... 23848 23849The corresponding GDB command is `x'. 23850 23851Example 23852....... 23853 23854 (gdb) 23855 -data-read-memory-bytes &a 10 23856 ^done,memory=[{begin="0xbffff154",offset="0x00000000", 23857 end="0xbffff15e", 23858 contents="01000000020000000300"}] 23859 (gdb) 23860 23861The `-data-write-memory-bytes' Command 23862-------------------------------------- 23863 23864Synopsis 23865........ 23866 23867 -data-write-memory-bytes ADDRESS CONTENTS 23868 23869where: 23870 23871`ADDRESS' 23872 An expression specifying the address of the first memory word to be 23873 read. Complex expressions containing embedded white space should 23874 be quoted using the C convention. 23875 23876`CONTENTS' 23877 The hex-encoded bytes to write. 23878 23879 23880GDB Command 23881........... 23882 23883There's no corresponding GDB command. 23884 23885Example 23886....... 23887 23888 (gdb) 23889 -data-write-memory-bytes &a "aabbccdd" 23890 ^done 23891 (gdb) 23892 23893 23894File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI 23895 2389627.15 GDB/MI Tracepoint Commands 23897================================ 23898 23899The commands defined in this section implement MI support for 23900tracepoints. For detailed introduction, see *note Tracepoints::. 23901 23902The `-trace-find' Command 23903------------------------- 23904 23905Synopsis 23906........ 23907 23908 -trace-find MODE [PARAMETERS...] 23909 23910 Find a trace frame using criteria defined by MODE and PARAMETERS. 23911The following table lists permissible modes and their parameters. For 23912details of operation, see *note tfind::. 23913 23914`none' 23915 No parameters are required. Stops examining trace frames. 23916 23917`frame-number' 23918 An integer is required as parameter. Selects tracepoint frame with 23919 that index. 23920 23921`tracepoint-number' 23922 An integer is required as parameter. Finds next trace frame that 23923 corresponds to tracepoint with the specified number. 23924 23925`pc' 23926 An address is required as parameter. Finds next trace frame that 23927 corresponds to any tracepoint at the specified address. 23928 23929`pc-inside-range' 23930 Two addresses are required as parameters. Finds next trace frame 23931 that corresponds to a tracepoint at an address inside the 23932 specified range. Both bounds are considered to be inside the 23933 range. 23934 23935`pc-outside-range' 23936 Two addresses are required as parameters. Finds next trace frame 23937 that corresponds to a tracepoint at an address outside the 23938 specified range. Both bounds are considered to be inside the 23939 range. 23940 23941`line' 23942 Line specification is required as parameter. *Note Specify 23943 Location::. Finds next trace frame that corresponds to a 23944 tracepoint at the specified location. 23945 23946 23947 If `none' was passed as MODE, the response does not have fields. 23948Otherwise, the response may have the following fields: 23949 23950`found' 23951 This field has either `0' or `1' as the value, depending on 23952 whether a matching tracepoint was found. 23953 23954`traceframe' 23955 The index of the found traceframe. This field is present iff the 23956 `found' field has value of `1'. 23957 23958`tracepoint' 23959 The index of the found tracepoint. This field is present iff the 23960 `found' field has value of `1'. 23961 23962`frame' 23963 The information about the frame corresponding to the found trace 23964 frame. This field is present only if a trace frame was found. 23965 *Note GDB/MI Frame Information::, for description of this field. 23966 23967 23968GDB Command 23969........... 23970 23971The corresponding GDB command is `tfind'. 23972 23973-trace-define-variable 23974---------------------- 23975 23976Synopsis 23977........ 23978 23979 -trace-define-variable NAME [ VALUE ] 23980 23981 Create trace variable NAME if it does not exist. If VALUE is 23982specified, sets the initial value of the specified trace variable to 23983that value. Note that the NAME should start with the `$' character. 23984 23985GDB Command 23986........... 23987 23988The corresponding GDB command is `tvariable'. 23989 23990-trace-list-variables 23991--------------------- 23992 23993Synopsis 23994........ 23995 23996 -trace-list-variables 23997 23998 Return a table of all defined trace variables. Each element of the 23999table has the following fields: 24000 24001`name' 24002 The name of the trace variable. This field is always present. 24003 24004`initial' 24005 The initial value. This is a 64-bit signed integer. This field 24006 is always present. 24007 24008`current' 24009 The value the trace variable has at the moment. This is a 64-bit 24010 signed integer. This field is absent iff current value is not 24011 defined, for example if the trace was never run, or is presently 24012 running. 24013 24014 24015GDB Command 24016........... 24017 24018The corresponding GDB command is `tvariables'. 24019 24020Example 24021....... 24022 24023 (gdb) 24024 -trace-list-variables 24025 ^done,trace-variables={nr_rows="1",nr_cols="3", 24026 hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"}, 24027 {width="11",alignment="-1",col_name="initial",colhdr="Initial"}, 24028 {width="11",alignment="-1",col_name="current",colhdr="Current"}], 24029 body=[variable={name="$trace_timestamp",initial="0"} 24030 variable={name="$foo",initial="10",current="15"}]} 24031 (gdb) 24032 24033-trace-save 24034----------- 24035 24036Synopsis 24037........ 24038 24039 -trace-save [-r ] FILENAME 24040 24041 Saves the collected trace data to FILENAME. Without the `-r' 24042option, the data is downloaded from the target and saved in a local 24043file. With the `-r' option the target is asked to perform the save. 24044 24045GDB Command 24046........... 24047 24048The corresponding GDB command is `tsave'. 24049 24050-trace-start 24051------------ 24052 24053Synopsis 24054........ 24055 24056 -trace-start 24057 24058 Starts a tracing experiments. The result of this command does not 24059have any fields. 24060 24061GDB Command 24062........... 24063 24064The corresponding GDB command is `tstart'. 24065 24066-trace-status 24067------------- 24068 24069Synopsis 24070........ 24071 24072 -trace-status 24073 24074 Obtains the status of a tracing experiment. The result may include 24075the following fields: 24076 24077`supported' 24078 May have a value of either `0', when no tracing operations are 24079 supported, `1', when all tracing operations are supported, or 24080 `file' when examining trace file. In the latter case, examining 24081 of trace frame is possible but new tracing experiement cannot be 24082 started. This field is always present. 24083 24084`running' 24085 May have a value of either `0' or `1' depending on whether tracing 24086 experiement is in progress on target. This field is present if 24087 `supported' field is not `0'. 24088 24089`stop-reason' 24090 Report the reason why the tracing was stopped last time. This 24091 field may be absent iff tracing was never stopped on target yet. 24092 The value of `request' means the tracing was stopped as result of 24093 the `-trace-stop' command. The value of `overflow' means the 24094 tracing buffer is full. The value of `disconnection' means 24095 tracing was automatically stopped when GDB has disconnected. The 24096 value of `passcount' means tracing was stopped when a tracepoint 24097 was passed a maximal number of times for that tracepoint. This 24098 field is present if `supported' field is not `0'. 24099 24100`stopping-tracepoint' 24101 The number of tracepoint whose passcount as exceeded. This field 24102 is present iff the `stop-reason' field has the value of 24103 `passcount'. 24104 24105`frames' 24106`frames-created' 24107 The `frames' field is a count of the total number of trace frames 24108 in the trace buffer, while `frames-created' is the total created 24109 during the run, including ones that were discarded, such as when a 24110 circular trace buffer filled up. Both fields are optional. 24111 24112`buffer-size' 24113`buffer-free' 24114 These fields tell the current size of the tracing buffer and the 24115 remaining space. These fields are optional. 24116 24117`circular' 24118 The value of the circular trace buffer flag. `1' means that the 24119 trace buffer is circular and old trace frames will be discarded if 24120 necessary to make room, `0' means that the trace buffer is linear 24121 and may fill up. 24122 24123`disconnected' 24124 The value of the disconnected tracing flag. `1' means that 24125 tracing will continue after GDB disconnects, `0' means that the 24126 trace run will stop. 24127 24128 24129GDB Command 24130........... 24131 24132The corresponding GDB command is `tstatus'. 24133 24134-trace-stop 24135----------- 24136 24137Synopsis 24138........ 24139 24140 -trace-stop 24141 24142 Stops a tracing experiment. The result of this command has the same 24143fields as `-trace-status', except that the `supported' and `running' 24144fields are not output. 24145 24146GDB Command 24147........... 24148 24149The corresponding GDB command is `tstop'. 24150 24151 24152File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI 24153 2415427.16 GDB/MI Symbol Query Commands 24155================================== 24156 24157The `-symbol-list-lines' Command 24158-------------------------------- 24159 24160Synopsis 24161........ 24162 24163 -symbol-list-lines FILENAME 24164 24165 Print the list of lines that contain code and their associated 24166program addresses for the given source filename. The entries are 24167sorted in ascending PC order. 24168 24169GDB Command 24170........... 24171 24172There is no corresponding GDB command. 24173 24174Example 24175....... 24176 24177 (gdb) 24178 -symbol-list-lines basics.c 24179 ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] 24180 (gdb) 24181 24182 24183File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI 24184 2418527.17 GDB/MI File Commands 24186========================== 24187 24188This section describes the GDB/MI commands to specify executable file 24189names and to read in and obtain symbol table information. 24190 24191The `-file-exec-and-symbols' Command 24192------------------------------------ 24193 24194Synopsis 24195........ 24196 24197 -file-exec-and-symbols FILE 24198 24199 Specify the executable file to be debugged. This file is the one 24200from which the symbol table is also read. If no file is specified, the 24201command clears the executable and symbol information. If breakpoints 24202are set when using this command with no arguments, GDB will produce 24203error messages. Otherwise, no output is produced, except a completion 24204notification. 24205 24206GDB Command 24207........... 24208 24209The corresponding GDB command is `file'. 24210 24211Example 24212....... 24213 24214 (gdb) 24215 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 24216 ^done 24217 (gdb) 24218 24219The `-file-exec-file' Command 24220----------------------------- 24221 24222Synopsis 24223........ 24224 24225 -file-exec-file FILE 24226 24227 Specify the executable file to be debugged. Unlike 24228`-file-exec-and-symbols', the symbol table is _not_ read from this 24229file. If used without argument, GDB clears the information about the 24230executable file. No output is produced, except a completion 24231notification. 24232 24233GDB Command 24234........... 24235 24236The corresponding GDB command is `exec-file'. 24237 24238Example 24239....... 24240 24241 (gdb) 24242 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 24243 ^done 24244 (gdb) 24245 24246The `-file-list-exec-source-file' Command 24247----------------------------------------- 24248 24249Synopsis 24250........ 24251 24252 -file-list-exec-source-file 24253 24254 List the line number, the current source file, and the absolute path 24255to the current source file for the current executable. The macro 24256information field has a value of `1' or `0' depending on whether or not 24257the file includes preprocessor macro information. 24258 24259GDB Command 24260........... 24261 24262The GDB equivalent is `info source' 24263 24264Example 24265....... 24266 24267 (gdb) 24268 123-file-list-exec-source-file 24269 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" 24270 (gdb) 24271 24272The `-file-list-exec-source-files' Command 24273------------------------------------------ 24274 24275Synopsis 24276........ 24277 24278 -file-list-exec-source-files 24279 24280 List the source files for the current executable. 24281 24282 It will always output the filename, but only when GDB can find the 24283absolute file name of a source file, will it output the fullname. 24284 24285GDB Command 24286........... 24287 24288The GDB equivalent is `info sources'. `gdbtk' has an analogous command 24289`gdb_listfiles'. 24290 24291Example 24292....... 24293 24294 (gdb) 24295 -file-list-exec-source-files 24296 ^done,files=[ 24297 {file=foo.c,fullname=/home/foo.c}, 24298 {file=/home/bar.c,fullname=/home/bar.c}, 24299 {file=gdb_could_not_find_fullpath.c}] 24300 (gdb) 24301 24302The `-file-symbol-file' Command 24303------------------------------- 24304 24305Synopsis 24306........ 24307 24308 -file-symbol-file FILE 24309 24310 Read symbol table info from the specified FILE argument. When used 24311without arguments, clears GDB's symbol table info. No output is 24312produced, except for a completion notification. 24313 24314GDB Command 24315........... 24316 24317The corresponding GDB command is `symbol-file'. 24318 24319Example 24320....... 24321 24322 (gdb) 24323 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 24324 ^done 24325 (gdb) 24326 24327 24328File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI 24329 2433027.18 GDB/MI Target Manipulation Commands 24331========================================= 24332 24333The `-target-attach' Command 24334---------------------------- 24335 24336Synopsis 24337........ 24338 24339 -target-attach PID | GID | FILE 24340 24341 Attach to a process PID or a file FILE outside of GDB, or a thread 24342group GID. If attaching to a thread group, the id previously returned 24343by `-list-thread-groups --available' must be used. 24344 24345GDB Command 24346........... 24347 24348The corresponding GDB command is `attach'. 24349 24350Example 24351....... 24352 24353 (gdb) 24354 -target-attach 34 24355 =thread-created,id="1" 24356 *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]} 24357 ^done 24358 (gdb) 24359 24360The `-target-detach' Command 24361---------------------------- 24362 24363Synopsis 24364........ 24365 24366 -target-detach [ PID | GID ] 24367 24368 Detach from the remote target which normally resumes its execution. 24369If either PID or GID is specified, detaches from either the specified 24370process, or specified thread group. There's no output. 24371 24372GDB Command 24373........... 24374 24375The corresponding GDB command is `detach'. 24376 24377Example 24378....... 24379 24380 (gdb) 24381 -target-detach 24382 ^done 24383 (gdb) 24384 24385The `-target-disconnect' Command 24386-------------------------------- 24387 24388Synopsis 24389........ 24390 24391 -target-disconnect 24392 24393 Disconnect from the remote target. There's no output and the target 24394is generally not resumed. 24395 24396GDB Command 24397........... 24398 24399The corresponding GDB command is `disconnect'. 24400 24401Example 24402....... 24403 24404 (gdb) 24405 -target-disconnect 24406 ^done 24407 (gdb) 24408 24409The `-target-download' Command 24410------------------------------ 24411 24412Synopsis 24413........ 24414 24415 -target-download 24416 24417 Loads the executable onto the remote target. It prints out an 24418update message every half second, which includes the fields: 24419 24420`section' 24421 The name of the section. 24422 24423`section-sent' 24424 The size of what has been sent so far for that section. 24425 24426`section-size' 24427 The size of the section. 24428 24429`total-sent' 24430 The total size of what was sent so far (the current and the 24431 previous sections). 24432 24433`total-size' 24434 The size of the overall executable to download. 24435 24436Each message is sent as status record (*note GDB/MI Output Syntax: 24437GDB/MI Output Syntax.). 24438 24439 In addition, it prints the name and size of the sections, as they are 24440downloaded. These messages include the following fields: 24441 24442`section' 24443 The name of the section. 24444 24445`section-size' 24446 The size of the section. 24447 24448`total-size' 24449 The size of the overall executable to download. 24450 24451At the end, a summary is printed. 24452 24453GDB Command 24454........... 24455 24456The corresponding GDB command is `load'. 24457 24458Example 24459....... 24460 24461Note: each status message appears on a single line. Here the messages 24462have been broken down so that they can fit onto a page. 24463 24464 (gdb) 24465 -target-download 24466 +download,{section=".text",section-size="6668",total-size="9880"} 24467 +download,{section=".text",section-sent="512",section-size="6668", 24468 total-sent="512",total-size="9880"} 24469 +download,{section=".text",section-sent="1024",section-size="6668", 24470 total-sent="1024",total-size="9880"} 24471 +download,{section=".text",section-sent="1536",section-size="6668", 24472 total-sent="1536",total-size="9880"} 24473 +download,{section=".text",section-sent="2048",section-size="6668", 24474 total-sent="2048",total-size="9880"} 24475 +download,{section=".text",section-sent="2560",section-size="6668", 24476 total-sent="2560",total-size="9880"} 24477 +download,{section=".text",section-sent="3072",section-size="6668", 24478 total-sent="3072",total-size="9880"} 24479 +download,{section=".text",section-sent="3584",section-size="6668", 24480 total-sent="3584",total-size="9880"} 24481 +download,{section=".text",section-sent="4096",section-size="6668", 24482 total-sent="4096",total-size="9880"} 24483 +download,{section=".text",section-sent="4608",section-size="6668", 24484 total-sent="4608",total-size="9880"} 24485 +download,{section=".text",section-sent="5120",section-size="6668", 24486 total-sent="5120",total-size="9880"} 24487 +download,{section=".text",section-sent="5632",section-size="6668", 24488 total-sent="5632",total-size="9880"} 24489 +download,{section=".text",section-sent="6144",section-size="6668", 24490 total-sent="6144",total-size="9880"} 24491 +download,{section=".text",section-sent="6656",section-size="6668", 24492 total-sent="6656",total-size="9880"} 24493 +download,{section=".init",section-size="28",total-size="9880"} 24494 +download,{section=".fini",section-size="28",total-size="9880"} 24495 +download,{section=".data",section-size="3156",total-size="9880"} 24496 +download,{section=".data",section-sent="512",section-size="3156", 24497 total-sent="7236",total-size="9880"} 24498 +download,{section=".data",section-sent="1024",section-size="3156", 24499 total-sent="7748",total-size="9880"} 24500 +download,{section=".data",section-sent="1536",section-size="3156", 24501 total-sent="8260",total-size="9880"} 24502 +download,{section=".data",section-sent="2048",section-size="3156", 24503 total-sent="8772",total-size="9880"} 24504 +download,{section=".data",section-sent="2560",section-size="3156", 24505 total-sent="9284",total-size="9880"} 24506 +download,{section=".data",section-sent="3072",section-size="3156", 24507 total-sent="9796",total-size="9880"} 24508 ^done,address="0x10004",load-size="9880",transfer-rate="6586", 24509 write-rate="429" 24510 (gdb) 24511 24512GDB Command 24513........... 24514 24515No equivalent. 24516 24517Example 24518....... 24519 24520N.A. 24521 24522The `-target-select' Command 24523---------------------------- 24524 24525Synopsis 24526........ 24527 24528 -target-select TYPE PARAMETERS ... 24529 24530 Connect GDB to the remote target. This command takes two args: 24531 24532`TYPE' 24533 The type of target, for instance `remote', etc. 24534 24535`PARAMETERS' 24536 Device names, host names and the like. *Note Commands for 24537 Managing Targets: Target Commands, for more details. 24538 24539 The output is a connection notification, followed by the address at 24540which the target program is, in the following form: 24541 24542 ^connected,addr="ADDRESS",func="FUNCTION NAME", 24543 args=[ARG LIST] 24544 24545GDB Command 24546........... 24547 24548The corresponding GDB command is `target'. 24549 24550Example 24551....... 24552 24553 (gdb) 24554 -target-select remote /dev/ttya 24555 ^connected,addr="0xfe00a300",func="??",args=[] 24556 (gdb) 24557 24558 24559File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI 24560 2456127.19 GDB/MI File Transfer Commands 24562=================================== 24563 24564The `-target-file-put' Command 24565------------------------------ 24566 24567Synopsis 24568........ 24569 24570 -target-file-put HOSTFILE TARGETFILE 24571 24572 Copy file HOSTFILE from the host system (the machine running GDB) to 24573TARGETFILE on the target system. 24574 24575GDB Command 24576........... 24577 24578The corresponding GDB command is `remote put'. 24579 24580Example 24581....... 24582 24583 (gdb) 24584 -target-file-put localfile remotefile 24585 ^done 24586 (gdb) 24587 24588The `-target-file-get' Command 24589------------------------------ 24590 24591Synopsis 24592........ 24593 24594 -target-file-get TARGETFILE HOSTFILE 24595 24596 Copy file TARGETFILE from the target system to HOSTFILE on the host 24597system. 24598 24599GDB Command 24600........... 24601 24602The corresponding GDB command is `remote get'. 24603 24604Example 24605....... 24606 24607 (gdb) 24608 -target-file-get remotefile localfile 24609 ^done 24610 (gdb) 24611 24612The `-target-file-delete' Command 24613--------------------------------- 24614 24615Synopsis 24616........ 24617 24618 -target-file-delete TARGETFILE 24619 24620 Delete TARGETFILE from the target system. 24621 24622GDB Command 24623........... 24624 24625The corresponding GDB command is `remote delete'. 24626 24627Example 24628....... 24629 24630 (gdb) 24631 -target-file-delete remotefile 24632 ^done 24633 (gdb) 24634 24635 24636File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI 24637 2463827.20 Miscellaneous GDB/MI Commands 24639=================================== 24640 24641The `-gdb-exit' Command 24642----------------------- 24643 24644Synopsis 24645........ 24646 24647 -gdb-exit 24648 24649 Exit GDB immediately. 24650 24651GDB Command 24652........... 24653 24654Approximately corresponds to `quit'. 24655 24656Example 24657....... 24658 24659 (gdb) 24660 -gdb-exit 24661 ^exit 24662 24663The `-gdb-set' Command 24664---------------------- 24665 24666Synopsis 24667........ 24668 24669 -gdb-set 24670 24671 Set an internal GDB variable. 24672 24673GDB Command 24674........... 24675 24676The corresponding GDB command is `set'. 24677 24678Example 24679....... 24680 24681 (gdb) 24682 -gdb-set $foo=3 24683 ^done 24684 (gdb) 24685 24686The `-gdb-show' Command 24687----------------------- 24688 24689Synopsis 24690........ 24691 24692 -gdb-show 24693 24694 Show the current value of a GDB variable. 24695 24696GDB Command 24697........... 24698 24699The corresponding GDB command is `show'. 24700 24701Example 24702....... 24703 24704 (gdb) 24705 -gdb-show annotate 24706 ^done,value="0" 24707 (gdb) 24708 24709The `-gdb-version' Command 24710-------------------------- 24711 24712Synopsis 24713........ 24714 24715 -gdb-version 24716 24717 Show version information for GDB. Used mostly in testing. 24718 24719GDB Command 24720........... 24721 24722The GDB equivalent is `show version'. GDB by default shows this 24723information when you start an interactive session. 24724 24725Example 24726....... 24727 24728 (gdb) 24729 -gdb-version 24730 ~GNU gdb 5.2.1 24731 ~Copyright 2000 Free Software Foundation, Inc. 24732 ~GDB is free software, covered by the GNU General Public License, and 24733 ~you are welcome to change it and/or distribute copies of it under 24734 ~ certain conditions. 24735 ~Type "show copying" to see the conditions. 24736 ~There is absolutely no warranty for GDB. Type "show warranty" for 24737 ~ details. 24738 ~This GDB was configured as 24739 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". 24740 ^done 24741 (gdb) 24742 24743The `-list-features' Command 24744---------------------------- 24745 24746Returns a list of particular features of the MI protocol that this 24747version of gdb implements. A feature can be a command, or a new field 24748in an output of some command, or even an important bugfix. While a 24749frontend can sometimes detect presence of a feature at runtime, it is 24750easier to perform detection at debugger startup. 24751 24752 The command returns a list of strings, with each string naming an 24753available feature. Each returned string is just a name, it does not 24754have any internal structure. The list of possible feature names is 24755given below. 24756 24757 Example output: 24758 24759 (gdb) -list-features 24760 ^done,result=["feature1","feature2"] 24761 24762 The current list of features is: 24763 24764`frozen-varobjs' 24765 Indicates presence of the `-var-set-frozen' command, as well as 24766 possible presense of the `frozen' field in the output of 24767 `-varobj-create'. 24768 24769`pending-breakpoints' 24770 Indicates presence of the `-f' option to the `-break-insert' 24771 command. 24772 24773`python' 24774 Indicates presence of Python scripting support, Python-based 24775 pretty-printing commands, and possible presence of the 24776 `display_hint' field in the output of `-var-list-children' 24777 24778`thread-info' 24779 Indicates presence of the `-thread-info' command. 24780 24781`data-read-memory-bytes' 24782 Indicates presense of the `-data-read-memory-bytes' and the 24783 `-data-write-memory-bytes' commands. 24784 24785 24786The `-list-target-features' Command 24787----------------------------------- 24788 24789Returns a list of particular features that are supported by the target. 24790Those features affect the permitted MI commands, but unlike the 24791features reported by the `-list-features' command, the features depend 24792on which target GDB is using at the moment. Whenever a target can 24793change, due to commands such as `-target-select', `-target-attach' or 24794`-exec-run', the list of target features may change, and the frontend 24795should obtain it again. Example output: 24796 24797 (gdb) -list-features 24798 ^done,result=["async"] 24799 24800 The current list of features is: 24801 24802`async' 24803 Indicates that the target is capable of asynchronous command 24804 execution, which means that GDB will accept further commands while 24805 the target is running. 24806 24807`reverse' 24808 Indicates that the target is capable of reverse execution. *Note 24809 Reverse Execution::, for more information. 24810 24811 24812The `-list-thread-groups' Command 24813--------------------------------- 24814 24815Synopsis 24816-------- 24817 24818 -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ] 24819 24820 Lists thread groups (*note Thread groups::). When a single thread 24821group is passed as the argument, lists the children of that group. 24822When several thread group are passed, lists information about those 24823thread groups. Without any parameters, lists information about all 24824top-level thread groups. 24825 24826 Normally, thread groups that are being debugged are reported. With 24827the `--available' option, GDB reports thread groups available on the 24828target. 24829 24830 The output of this command may have either a `threads' result or a 24831`groups' result. The `thread' result has a list of tuples as value, 24832with each tuple describing a thread (*note GDB/MI Thread 24833Information::). The `groups' result has a list of tuples as value, 24834each tuple describing a thread group. If top-level groups are 24835requested (that is, no parameter is passed), or when several groups are 24836passed, the output always has a `groups' result. The format of the 24837`group' result is described below. 24838 24839 To reduce the number of roundtrips it's possible to list thread 24840groups together with their children, by passing the `--recurse' option 24841and the recursion depth. Presently, only recursion depth of 1 is 24842permitted. If this option is present, then every reported thread group 24843will also include its children, either as `group' or `threads' field. 24844 24845 In general, any combination of option and parameters is permitted, 24846with the following caveats: 24847 24848 * When a single thread group is passed, the output will typically be 24849 the `threads' result. Because threads may not contain anything, 24850 the `recurse' option will be ignored. 24851 24852 * When the `--available' option is passed, limited information may 24853 be available. In particular, the list of threads of a process 24854 might be inaccessible. Further, specifying specific thread groups 24855 might not give any performance advantage over listing all thread 24856 groups. The frontend should assume that `-list-thread-groups 24857 --available' is always an expensive operation and cache the 24858 results. 24859 24860 24861 The `groups' result is a list of tuples, where each tuple may have 24862the following fields: 24863 24864`id' 24865 Identifier of the thread group. This field is always present. 24866 The identifier is an opaque string; frontends should not try to 24867 convert it to an integer, even though it might look like one. 24868 24869`type' 24870 The type of the thread group. At present, only `process' is a 24871 valid type. 24872 24873`pid' 24874 The target-specific process identifier. This field is only present 24875 for thread groups of type `process' and only if the process exists. 24876 24877`num_children' 24878 The number of children this thread group has. This field may be 24879 absent for an available thread group. 24880 24881`threads' 24882 This field has a list of tuples as value, each tuple describing a 24883 thread. It may be present if the `--recurse' option is specified, 24884 and it's actually possible to obtain the threads. 24885 24886`cores' 24887 This field is a list of integers, each identifying a core that one 24888 thread of the group is running on. This field may be absent if 24889 such information is not available. 24890 24891`executable' 24892 The name of the executable file that corresponds to this thread 24893 group. The field is only present for thread groups of type 24894 `process', and only if there is a corresponding executable file. 24895 24896 24897Example 24898------- 24899 24900 gdb 24901 -list-thread-groups 24902 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}] 24903 -list-thread-groups 17 24904 ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 24905 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, 24906 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 24907 frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], 24908 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]] 24909 -list-thread-groups --available 24910 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}] 24911 -list-thread-groups --available --recurse 1 24912 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 24913 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, 24914 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..] 24915 -list-thread-groups --available --recurse 1 17 18 24916 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 24917 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, 24918 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...] 24919 24920The `-add-inferior' Command 24921--------------------------- 24922 24923Synopsis 24924-------- 24925 24926 -add-inferior 24927 24928 Creates a new inferior (*note Inferiors and Programs::). The created 24929inferior is not associated with any executable. Such association may 24930be established with the `-file-exec-and-symbols' command (*note GDB/MI 24931File Commands::). The command response has a single field, 24932`thread-group', whose value is the identifier of the thread group 24933corresponding to the new inferior. 24934 24935Example 24936------- 24937 24938 gdb 24939 -add-inferior 24940 ^done,thread-group="i3" 24941 24942The `-interpreter-exec' Command 24943------------------------------- 24944 24945Synopsis 24946-------- 24947 24948 -interpreter-exec INTERPRETER COMMAND 24949Execute the specified COMMAND in the given INTERPRETER. 24950 24951GDB Command 24952----------- 24953 24954The corresponding GDB command is `interpreter-exec'. 24955 24956Example 24957------- 24958 24959 (gdb) 24960 -interpreter-exec console "break main" 24961 &"During symbol reading, couldn't parse type; debugger out of date?.\n" 24962 &"During symbol reading, bad structure-type format.\n" 24963 ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" 24964 ^done 24965 (gdb) 24966 24967The `-inferior-tty-set' Command 24968------------------------------- 24969 24970Synopsis 24971-------- 24972 24973 -inferior-tty-set /dev/pts/1 24974 24975 Set terminal for future runs of the program being debugged. 24976 24977GDB Command 24978----------- 24979 24980The corresponding GDB command is `set inferior-tty' /dev/pts/1. 24981 24982Example 24983------- 24984 24985 (gdb) 24986 -inferior-tty-set /dev/pts/1 24987 ^done 24988 (gdb) 24989 24990The `-inferior-tty-show' Command 24991-------------------------------- 24992 24993Synopsis 24994-------- 24995 24996 -inferior-tty-show 24997 24998 Show terminal for future runs of program being debugged. 24999 25000GDB Command 25001----------- 25002 25003The corresponding GDB command is `show inferior-tty'. 25004 25005Example 25006------- 25007 25008 (gdb) 25009 -inferior-tty-set /dev/pts/1 25010 ^done 25011 (gdb) 25012 -inferior-tty-show 25013 ^done,inferior_tty_terminal="/dev/pts/1" 25014 (gdb) 25015 25016The `-enable-timings' Command 25017----------------------------- 25018 25019Synopsis 25020-------- 25021 25022 -enable-timings [yes | no] 25023 25024 Toggle the printing of the wallclock, user and system times for an MI 25025command as a field in its output. This command is to help frontend 25026developers optimize the performance of their code. No argument is 25027equivalent to `yes'. 25028 25029GDB Command 25030----------- 25031 25032No equivalent. 25033 25034Example 25035------- 25036 25037 (gdb) 25038 -enable-timings 25039 ^done 25040 (gdb) 25041 -break-insert main 25042 ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 25043 addr="0x080484ed",func="main",file="myprog.c", 25044 fullname="/home/nickrob/myprog.c",line="73",times="0"}, 25045 time={wallclock="0.05185",user="0.00800",system="0.00000"} 25046 (gdb) 25047 -enable-timings no 25048 ^done 25049 (gdb) 25050 -exec-run 25051 ^running 25052 (gdb) 25053 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 25054 frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"}, 25055 {name="argv",value="0xbfb60364"}],file="myprog.c", 25056 fullname="/home/nickrob/myprog.c",line="73"} 25057 (gdb) 25058 25059 25060File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top 25061 2506228 GDB Annotations 25063****************** 25064 25065This chapter describes annotations in GDB. Annotations were designed 25066to interface GDB to graphical user interfaces or other similar programs 25067which want to interact with GDB at a relatively high level. 25068 25069 The annotation mechanism has largely been superseded by GDB/MI 25070(*note GDB/MI::). 25071 25072* Menu: 25073 25074* Annotations Overview:: What annotations are; the general syntax. 25075* Server Prefix:: Issuing a command without affecting user state. 25076* Prompting:: Annotations marking GDB's need for input. 25077* Errors:: Annotations for error messages. 25078* Invalidation:: Some annotations describe things now invalid. 25079* Annotations for Running:: 25080 Whether the program is running, how it stopped, etc. 25081* Source Annotations:: Annotations describing source code. 25082 25083 25084File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations 25085 2508628.1 What is an Annotation? 25087=========================== 25088 25089Annotations start with a newline character, two `control-z' characters, 25090and the name of the annotation. If there is no additional information 25091associated with this annotation, the name of the annotation is followed 25092immediately by a newline. If there is additional information, the name 25093of the annotation is followed by a space, the additional information, 25094and a newline. The additional information cannot contain newline 25095characters. 25096 25097 Any output not beginning with a newline and two `control-z' 25098characters denotes literal output from GDB. Currently there is no need 25099for GDB to output a newline followed by two `control-z' characters, but 25100if there was such a need, the annotations could be extended with an 25101`escape' annotation which means those three characters as output. 25102 25103 The annotation LEVEL, which is specified using the `--annotate' 25104command line option (*note Mode Options::), controls how much 25105information GDB prints together with its prompt, values of expressions, 25106source lines, and other types of output. Level 0 is for no 25107annotations, level 1 is for use when GDB is run as a subprocess of GNU 25108Emacs, level 3 is the maximum annotation suitable for programs that 25109control GDB, and level 2 annotations have been made obsolete (*note 25110Limitations of the Annotation Interface: (annotate)Limitations.). 25111 25112`set annotate LEVEL' 25113 The GDB command `set annotate' sets the level of annotations to 25114 the specified LEVEL. 25115 25116`show annotate' 25117 Show the current annotation level. 25118 25119 This chapter describes level 3 annotations. 25120 25121 A simple example of starting up GDB with annotations is: 25122 25123 $ gdb --annotate=3 25124 GNU gdb 6.0 25125 Copyright 2003 Free Software Foundation, Inc. 25126 GDB is free software, covered by the GNU General Public License, 25127 and you are welcome to change it and/or distribute copies of it 25128 under certain conditions. 25129 Type "show copying" to see the conditions. 25130 There is absolutely no warranty for GDB. Type "show warranty" 25131 for details. 25132 This GDB was configured as "i386-pc-linux-gnu" 25133 25134 ^Z^Zpre-prompt 25135 (gdb) 25136 ^Z^Zprompt 25137 quit 25138 25139 ^Z^Zpost-prompt 25140 $ 25141 25142 Here `quit' is input to GDB; the rest is output from GDB. The three 25143lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are 25144annotations; the rest is output from GDB. 25145 25146 25147File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations 25148 2514928.2 The Server Prefix 25150====================== 25151 25152If you prefix a command with `server ' then it will not affect the 25153command history, nor will it affect GDB's notion of which command to 25154repeat if <RET> is pressed on a line by itself. This means that 25155commands can be run behind a user's back by a front-end in a 25156transparent manner. 25157 25158 The `server ' prefix does not affect the recording of values into 25159the value history; to print a value without recording it into the value 25160history, use the `output' command instead of the `print' command. 25161 25162 Using this prefix also disables confirmation requests (*note 25163confirmation requests::). 25164 25165 25166File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations 25167 2516828.3 Annotation for GDB Input 25169============================= 25170 25171When GDB prompts for input, it annotates this fact so it is possible to 25172know when to send output, when the output from a given command is over, 25173etc. 25174 25175 Different kinds of input each have a different "input type". Each 25176input type has three annotations: a `pre-' annotation, which denotes 25177the beginning of any prompt which is being output, a plain annotation, 25178which denotes the end of the prompt, and then a `post-' annotation 25179which denotes the end of any echo which may (or may not) be associated 25180with the input. For example, the `prompt' input type features the 25181following annotations: 25182 25183 ^Z^Zpre-prompt 25184 ^Z^Zprompt 25185 ^Z^Zpost-prompt 25186 25187 The input types are 25188 25189`prompt' 25190 When GDB is prompting for a command (the main GDB prompt). 25191 25192`commands' 25193 When GDB prompts for a set of commands, like in the `commands' 25194 command. The annotations are repeated for each command which is 25195 input. 25196 25197`overload-choice' 25198 When GDB wants the user to select between various overloaded 25199 functions. 25200 25201`query' 25202 When GDB wants the user to confirm a potentially dangerous 25203 operation. 25204 25205`prompt-for-continue' 25206 When GDB is asking the user to press return to continue. Note: 25207 Don't expect this to work well; instead use `set height 0' to 25208 disable prompting. This is because the counting of lines is buggy 25209 in the presence of annotations. 25210 25211 25212File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations 25213 2521428.4 Errors 25215=========== 25216 25217 ^Z^Zquit 25218 25219 This annotation occurs right before GDB responds to an interrupt. 25220 25221 ^Z^Zerror 25222 25223 This annotation occurs right before GDB responds to an error. 25224 25225 Quit and error annotations indicate that any annotations which GDB 25226was in the middle of may end abruptly. For example, if a 25227`value-history-begin' annotation is followed by a `error', one cannot 25228expect to receive the matching `value-history-end'. One cannot expect 25229not to receive it either, however; an error annotation does not 25230necessarily mean that GDB is immediately returning all the way to the 25231top level. 25232 25233 A quit or error annotation may be preceded by 25234 25235 ^Z^Zerror-begin 25236 25237 Any output between that and the quit or error annotation is the error 25238message. 25239 25240 Warning messages are not yet annotated. 25241 25242 25243File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations 25244 2524528.5 Invalidation Notices 25246========================= 25247 25248The following annotations say that certain pieces of state may have 25249changed. 25250 25251`^Z^Zframes-invalid' 25252 The frames (for example, output from the `backtrace' command) may 25253 have changed. 25254 25255`^Z^Zbreakpoints-invalid' 25256 The breakpoints may have changed. For example, the user just 25257 added or deleted a breakpoint. 25258 25259 25260File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations 25261 2526228.6 Running the Program 25263======================== 25264 25265When the program starts executing due to a GDB command such as `step' 25266or `continue', 25267 25268 ^Z^Zstarting 25269 25270 is output. When the program stops, 25271 25272 ^Z^Zstopped 25273 25274 is output. Before the `stopped' annotation, a variety of 25275annotations describe how the program stopped. 25276 25277`^Z^Zexited EXIT-STATUS' 25278 The program exited, and EXIT-STATUS is the exit status (zero for 25279 successful exit, otherwise nonzero). 25280 25281`^Z^Zsignalled' 25282 The program exited with a signal. After the `^Z^Zsignalled', the 25283 annotation continues: 25284 25285 INTRO-TEXT 25286 ^Z^Zsignal-name 25287 NAME 25288 ^Z^Zsignal-name-end 25289 MIDDLE-TEXT 25290 ^Z^Zsignal-string 25291 STRING 25292 ^Z^Zsignal-string-end 25293 END-TEXT 25294 25295 where NAME is the name of the signal, such as `SIGILL' or 25296 `SIGSEGV', and STRING is the explanation of the signal, such as 25297 `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT, 25298 MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no 25299 particular format. 25300 25301`^Z^Zsignal' 25302 The syntax of this annotation is just like `signalled', but GDB is 25303 just saying that the program received the signal, not that it was 25304 terminated with it. 25305 25306`^Z^Zbreakpoint NUMBER' 25307 The program hit breakpoint number NUMBER. 25308 25309`^Z^Zwatchpoint NUMBER' 25310 The program hit watchpoint number NUMBER. 25311 25312 25313File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations 25314 2531528.7 Displaying Source 25316====================== 25317 25318The following annotation is used instead of displaying source code: 25319 25320 ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR 25321 25322 where FILENAME is an absolute file name indicating which source 25323file, LINE is the line number within that file (where 1 is the first 25324line in the file), CHARACTER is the character position within the file 25325(where 0 is the first character in the file) (for most debug formats 25326this will necessarily point to the beginning of a line), MIDDLE is 25327`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at 25328the beginning of the line, and ADDR is the address in the target 25329program associated with the source which is being displayed. ADDR is 25330in the form `0x' followed by one or more lowercase hex digits (note 25331that this does not depend on the language). 25332 25333 25334File: gdb.info, Node: JIT Interface, Next: GDB Bugs, Prev: Annotations, Up: Top 25335 2533629 JIT Compilation Interface 25337**************************** 25338 25339This chapter documents GDB's "just-in-time" (JIT) compilation 25340interface. A JIT compiler is a program or library that generates native 25341executable code at runtime and executes it, usually in order to achieve 25342good performance while maintaining platform independence. 25343 25344 Programs that use JIT compilation are normally difficult to debug 25345because portions of their code are generated at runtime, instead of 25346being loaded from object files, which is where GDB normally finds the 25347program's symbols and debug information. In order to debug programs 25348that use JIT compilation, GDB has an interface that allows the program 25349to register in-memory symbol files with GDB at runtime. 25350 25351 If you are using GDB to debug a program that uses this interface, 25352then it should work transparently so long as you have not stripped the 25353binary. If you are developing a JIT compiler, then the interface is 25354documented in the rest of this chapter. At this time, the only known 25355client of this interface is the LLVM JIT. 25356 25357 Broadly speaking, the JIT interface mirrors the dynamic loader 25358interface. The JIT compiler communicates with GDB by writing data into 25359a global variable and calling a fuction at a well-known symbol. When 25360GDB attaches, it reads a linked list of symbol files from the global 25361variable to find existing code, and puts a breakpoint in the function 25362so that it can find out about additional code. 25363 25364* Menu: 25365 25366* Declarations:: Relevant C struct declarations 25367* Registering Code:: Steps to register code 25368* Unregistering Code:: Steps to unregister code 25369 25370 25371File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface 25372 2537329.1 JIT Declarations 25374===================== 25375 25376These are the relevant struct declarations that a C program should 25377include to implement the interface: 25378 25379 typedef enum 25380 { 25381 JIT_NOACTION = 0, 25382 JIT_REGISTER_FN, 25383 JIT_UNREGISTER_FN 25384 } jit_actions_t; 25385 25386 struct jit_code_entry 25387 { 25388 struct jit_code_entry *next_entry; 25389 struct jit_code_entry *prev_entry; 25390 const char *symfile_addr; 25391 uint64_t symfile_size; 25392 }; 25393 25394 struct jit_descriptor 25395 { 25396 uint32_t version; 25397 /* This type should be jit_actions_t, but we use uint32_t 25398 to be explicit about the bitwidth. */ 25399 uint32_t action_flag; 25400 struct jit_code_entry *relevant_entry; 25401 struct jit_code_entry *first_entry; 25402 }; 25403 25404 /* GDB puts a breakpoint in this function. */ 25405 void __attribute__((noinline)) __jit_debug_register_code() { }; 25406 25407 /* Make sure to specify the version statically, because the 25408 debugger may check the version before we can set it. */ 25409 struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 }; 25410 25411 If the JIT is multi-threaded, then it is important that the JIT 25412synchronize any modifications to this global data properly, which can 25413easily be done by putting a global mutex around modifications to these 25414structures. 25415 25416 25417File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface 25418 2541929.2 Registering Code 25420===================== 25421 25422To register code with GDB, the JIT should follow this protocol: 25423 25424 * Generate an object file in memory with symbols and other desired 25425 debug information. The file must include the virtual addresses of 25426 the sections. 25427 25428 * Create a code entry for the file, which gives the start and size 25429 of the symbol file. 25430 25431 * Add it to the linked list in the JIT descriptor. 25432 25433 * Point the relevant_entry field of the descriptor at the entry. 25434 25435 * Set `action_flag' to `JIT_REGISTER' and call 25436 `__jit_debug_register_code'. 25437 25438 When GDB is attached and the breakpoint fires, GDB uses the 25439`relevant_entry' pointer so it doesn't have to walk the list looking for 25440new code. However, the linked list must still be maintained in order 25441to allow GDB to attach to a running process and still find the symbol 25442files. 25443 25444 25445File: gdb.info, Node: Unregistering Code, Prev: Registering Code, Up: JIT Interface 25446 2544729.3 Unregistering Code 25448======================= 25449 25450If code is freed, then the JIT should use the following protocol: 25451 25452 * Remove the code entry corresponding to the code from the linked 25453 list. 25454 25455 * Point the `relevant_entry' field of the descriptor at the code 25456 entry. 25457 25458 * Set `action_flag' to `JIT_UNREGISTER' and call 25459 `__jit_debug_register_code'. 25460 25461 If the JIT frees or recompiles code without unregistering it, then 25462GDB and the JIT will leak the memory used for the associated symbol 25463files. 25464 25465 25466File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: JIT Interface, Up: Top 25467 2546830 Reporting Bugs in GDB 25469************************ 25470 25471Your bug reports play an essential role in making GDB reliable. 25472 25473 Reporting a bug may help you by bringing a solution to your problem, 25474or it may not. But in any case the principal function of a bug report 25475is to help the entire community by making the next version of GDB work 25476better. Bug reports are your contribution to the maintenance of GDB. 25477 25478 In order for a bug report to serve its purpose, you must include the 25479information that enables us to fix the bug. 25480 25481* Menu: 25482 25483* Bug Criteria:: Have you found a bug? 25484* Bug Reporting:: How to report bugs 25485 25486 25487File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs 25488 2548930.1 Have You Found a Bug? 25490========================== 25491 25492If you are not sure whether you have found a bug, here are some 25493guidelines: 25494 25495 * If the debugger gets a fatal signal, for any input whatever, that 25496 is a GDB bug. Reliable debuggers never crash. 25497 25498 * If GDB produces an error message for valid input, that is a bug. 25499 (Note that if you're cross debugging, the problem may also be 25500 somewhere in the connection to the target.) 25501 25502 * If GDB does not produce an error message for invalid input, that 25503 is a bug. However, you should note that your idea of "invalid 25504 input" might be our idea of "an extension" or "support for 25505 traditional practice". 25506 25507 * If you are an experienced user of debugging tools, your suggestions 25508 for improvement of GDB are welcome in any case. 25509 25510 25511File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs 25512 2551330.2 How to Report Bugs 25514======================= 25515 25516A number of companies and individuals offer support for GNU products. 25517If you obtained GDB from a support organization, we recommend you 25518contact that organization first. 25519 25520 You can find contact information for many support companies and 25521individuals in the file `etc/SERVICE' in the GNU Emacs distribution. 25522 25523 In any event, we also recommend that you submit bug reports for GDB 25524to `https://support.codesourcery.com/GNUToolchain/'. 25525 25526 The fundamental principle of reporting bugs usefully is this: 25527*report all the facts*. If you are not sure whether to state a fact or 25528leave it out, state it! 25529 25530 Often people omit facts because they think they know what causes the 25531problem and assume that some details do not matter. Thus, you might 25532assume that the name of the variable you use in an example does not 25533matter. Well, probably it does not, but one cannot be sure. Perhaps 25534the bug is a stray memory reference which happens to fetch from the 25535location where that name is stored in memory; perhaps, if the name were 25536different, the contents of that location would fool the debugger into 25537doing the right thing despite the bug. Play it safe and give a 25538specific, complete example. That is the easiest thing for you to do, 25539and the most helpful. 25540 25541 Keep in mind that the purpose of a bug report is to enable us to fix 25542the bug. It may be that the bug has been reported previously, but 25543neither you nor we can know that unless your bug report is complete and 25544self-contained. 25545 25546 Sometimes people give a few sketchy facts and ask, "Does this ring a 25547bell?" Those bug reports are useless, and we urge everyone to _refuse 25548to respond to them_ except to chide the sender to report bugs properly. 25549 25550 To enable us to fix the bug, you should include all these things: 25551 25552 * The version of GDB. GDB announces it if you start with no 25553 arguments; you can also print it at any time using `show version'. 25554 25555 Without this, we will not know whether there is any point in 25556 looking for the bug in the current version of GDB. 25557 25558 * The type of machine you are using, and the operating system name 25559 and version number. 25560 25561 * What compiler (and its version) was used to compile GDB--e.g. 25562 "gcc-2.8.1". 25563 25564 * What compiler (and its version) was used to compile the program 25565 you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP 25566 C Compiler". For GCC, you can say `gcc --version' to get this 25567 information; for other compilers, see the documentation for those 25568 compilers. 25569 25570 * The command arguments you gave the compiler to compile your 25571 example and observe the bug. For example, did you use `-O'? To 25572 guarantee you will not omit something important, list them all. A 25573 copy of the Makefile (or the output from make) is sufficient. 25574 25575 If we were to try to guess the arguments, we would probably guess 25576 wrong and then we might not encounter the bug. 25577 25578 * A complete input script, and all necessary source files, that will 25579 reproduce the bug. 25580 25581 * A description of what behavior you observe that you believe is 25582 incorrect. For example, "It gets a fatal signal." 25583 25584 Of course, if the bug is that GDB gets a fatal signal, then we 25585 will certainly notice it. But if the bug is incorrect output, we 25586 might not notice unless it is glaringly wrong. You might as well 25587 not give us a chance to make a mistake. 25588 25589 Even if the problem you experience is a fatal signal, you should 25590 still say so explicitly. Suppose something strange is going on, 25591 such as, your copy of GDB is out of synch, or you have encountered 25592 a bug in the C library on your system. (This has happened!) Your 25593 copy might crash and ours would not. If you told us to expect a 25594 crash, then when ours fails to crash, we would know that the bug 25595 was not happening for us. If you had not told us to expect a 25596 crash, then we would not be able to draw any conclusion from our 25597 observations. 25598 25599 To collect all this information, you can use a session recording 25600 program such as `script', which is available on many Unix systems. 25601 Just run your GDB session inside `script' and then include the 25602 `typescript' file with your bug report. 25603 25604 Another way to record a GDB session is to run GDB inside Emacs and 25605 then save the entire buffer to a file. 25606 25607 * If you wish to suggest changes to the GDB source, send us context 25608 diffs. If you even discuss something in the GDB source, refer to 25609 it by context, not by line number. 25610 25611 The line numbers in our development sources will not match those 25612 in your sources. Your line numbers would convey no useful 25613 information to us. 25614 25615 25616 Here are some things that are not necessary: 25617 25618 * A description of the envelope of the bug. 25619 25620 Often people who encounter a bug spend a lot of time investigating 25621 which changes to the input file will make the bug go away and which 25622 changes will not affect it. 25623 25624 This is often time consuming and not very useful, because the way 25625 we will find the bug is by running a single example under the 25626 debugger with breakpoints, not by pure deduction from a series of 25627 examples. We recommend that you save your time for something else. 25628 25629 Of course, if you can find a simpler example to report _instead_ 25630 of the original one, that is a convenience for us. Errors in the 25631 output will be easier to spot, running under the debugger will take 25632 less time, and so on. 25633 25634 However, simplification is not vital; if you do not want to do 25635 this, report the bug anyway and send us the entire test case you 25636 used. 25637 25638 * A patch for the bug. 25639 25640 A patch for the bug does help us if it is a good one. But do not 25641 omit the necessary information, such as the test case, on the 25642 assumption that a patch is all we need. We might see problems 25643 with your patch and decide to fix the problem another way, or we 25644 might not understand it at all. 25645 25646 Sometimes with a program as complicated as GDB it is very hard to 25647 construct an example that will make the program follow a certain 25648 path through the code. If you do not send us the example, we will 25649 not be able to construct one, so we will not be able to verify 25650 that the bug is fixed. 25651 25652 And if we cannot understand what bug you are trying to fix, or why 25653 your patch should be an improvement, we will not install it. A 25654 test case will help us to understand. 25655 25656 * A guess about what the bug is or what it depends on. 25657 25658 Such guesses are usually wrong. Even we cannot guess right about 25659 such things without first using the debugger to find the facts. 25660 25661 25662File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top 25663 2566431 Command Line Editing 25665*********************** 25666 25667This chapter describes the basic features of the GNU command line 25668editing interface. 25669 25670* Menu: 25671 25672* Introduction and Notation:: Notation used in this text. 25673* Readline Interaction:: The minimum set of commands for editing a line. 25674* Readline Init File:: Customizing Readline from a user's view. 25675* Bindable Readline Commands:: A description of most of the Readline commands 25676 available for binding 25677* Readline vi Mode:: A short description of how to make Readline 25678 behave like the vi editor. 25679 25680 25681File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing 25682 2568331.1 Introduction to Line Editing 25684================================= 25685 25686The following paragraphs describe the notation used to represent 25687keystrokes. 25688 25689 The text `C-k' is read as `Control-K' and describes the character 25690produced when the <k> key is pressed while the Control key is depressed. 25691 25692 The text `M-k' is read as `Meta-K' and describes the character 25693produced when the Meta key (if you have one) is depressed, and the <k> 25694key is pressed. The Meta key is labeled <ALT> on many keyboards. On 25695keyboards with two keys labeled <ALT> (usually to either side of the 25696space bar), the <ALT> on the left side is generally set to work as a 25697Meta key. The <ALT> key on the right may also be configured to work as 25698a Meta key or may be configured as some other modifier, such as a 25699Compose key for typing accented characters. 25700 25701 If you do not have a Meta or <ALT> key, or another key working as a 25702Meta key, the identical keystroke can be generated by typing <ESC> 25703_first_, and then typing <k>. Either process is known as "metafying" 25704the <k> key. 25705 25706 The text `M-C-k' is read as `Meta-Control-k' and describes the 25707character produced by "metafying" `C-k'. 25708 25709 In addition, several keys have their own names. Specifically, 25710<DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves 25711when seen in this text, or in an init file (*note Readline Init File::). 25712If your keyboard lacks a <LFD> key, typing <C-j> will produce the 25713desired character. The <RET> key may be labeled <Return> or <Enter> on 25714some keyboards. 25715 25716 25717File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing 25718 2571931.2 Readline Interaction 25720========================= 25721 25722Often during an interactive session you type in a long line of text, 25723only to notice that the first word on the line is misspelled. The 25724Readline library gives you a set of commands for manipulating the text 25725as you type it in, allowing you to just fix your typo, and not forcing 25726you to retype the majority of the line. Using these editing commands, 25727you move the cursor to the place that needs correction, and delete or 25728insert the text of the corrections. Then, when you are satisfied with 25729the line, you simply press <RET>. You do not have to be at the end of 25730the line to press <RET>; the entire line is accepted regardless of the 25731location of the cursor within the line. 25732 25733* Menu: 25734 25735* Readline Bare Essentials:: The least you need to know about Readline. 25736* Readline Movement Commands:: Moving about the input line. 25737* Readline Killing Commands:: How to delete text, and how to get it back! 25738* Readline Arguments:: Giving numeric arguments to commands. 25739* Searching:: Searching through previous lines. 25740 25741 25742File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction 25743 2574431.2.1 Readline Bare Essentials 25745------------------------------- 25746 25747In order to enter characters into the line, simply type them. The typed 25748character appears where the cursor was, and then the cursor moves one 25749space to the right. If you mistype a character, you can use your erase 25750character to back up and delete the mistyped character. 25751 25752 Sometimes you may mistype a character, and not notice the error 25753until you have typed several other characters. In that case, you can 25754type `C-b' to move the cursor to the left, and then correct your 25755mistake. Afterwards, you can move the cursor to the right with `C-f'. 25756 25757 When you add text in the middle of a line, you will notice that 25758characters to the right of the cursor are `pushed over' to make room 25759for the text that you have inserted. Likewise, when you delete text 25760behind the cursor, characters to the right of the cursor are `pulled 25761back' to fill in the blank space created by the removal of the text. A 25762list of the bare essentials for editing the text of an input line 25763follows. 25764 25765`C-b' 25766 Move back one character. 25767 25768`C-f' 25769 Move forward one character. 25770 25771<DEL> or <Backspace> 25772 Delete the character to the left of the cursor. 25773 25774`C-d' 25775 Delete the character underneath the cursor. 25776 25777Printing characters 25778 Insert the character into the line at the cursor. 25779 25780`C-_' or `C-x C-u' 25781 Undo the last editing command. You can undo all the way back to an 25782 empty line. 25783 25784(Depending on your configuration, the <Backspace> key be set to delete 25785the character to the left of the cursor and the <DEL> key set to delete 25786the character underneath the cursor, like `C-d', rather than the 25787character to the left of the cursor.) 25788 25789 25790File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction 25791 2579231.2.2 Readline Movement Commands 25793--------------------------------- 25794 25795The above table describes the most basic keystrokes that you need in 25796order to do editing of the input line. For your convenience, many 25797other commands have been added in addition to `C-b', `C-f', `C-d', and 25798<DEL>. Here are some commands for moving more rapidly about the line. 25799 25800`C-a' 25801 Move to the start of the line. 25802 25803`C-e' 25804 Move to the end of the line. 25805 25806`M-f' 25807 Move forward a word, where a word is composed of letters and 25808 digits. 25809 25810`M-b' 25811 Move backward a word. 25812 25813`C-l' 25814 Clear the screen, reprinting the current line at the top. 25815 25816 Notice how `C-f' moves forward a character, while `M-f' moves 25817forward a word. It is a loose convention that control keystrokes 25818operate on characters while meta keystrokes operate on words. 25819 25820 25821File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction 25822 2582331.2.3 Readline Killing Commands 25824-------------------------------- 25825 25826"Killing" text means to delete the text from the line, but to save it 25827away for later use, usually by "yanking" (re-inserting) it back into 25828the line. (`Cut' and `paste' are more recent jargon for `kill' and 25829`yank'.) 25830 25831 If the description for a command says that it `kills' text, then you 25832can be sure that you can get the text back in a different (or the same) 25833place later. 25834 25835 When you use a kill command, the text is saved in a "kill-ring". 25836Any number of consecutive kills save all of the killed text together, so 25837that when you yank it back, you get it all. The kill ring is not line 25838specific; the text that you killed on a previously typed line is 25839available to be yanked back later, when you are typing another line. 25840 25841 Here is the list of commands for killing text. 25842 25843`C-k' 25844 Kill the text from the current cursor position to the end of the 25845 line. 25846 25847`M-d' 25848 Kill from the cursor to the end of the current word, or, if between 25849 words, to the end of the next word. Word boundaries are the same 25850 as those used by `M-f'. 25851 25852`M-<DEL>' 25853 Kill from the cursor the start of the current word, or, if between 25854 words, to the start of the previous word. Word boundaries are the 25855 same as those used by `M-b'. 25856 25857`C-w' 25858 Kill from the cursor to the previous whitespace. This is 25859 different than `M-<DEL>' because the word boundaries differ. 25860 25861 25862 Here is how to "yank" the text back into the line. Yanking means to 25863copy the most-recently-killed text from the kill buffer. 25864 25865`C-y' 25866 Yank the most recently killed text back into the buffer at the 25867 cursor. 25868 25869`M-y' 25870 Rotate the kill-ring, and yank the new top. You can only do this 25871 if the prior command is `C-y' or `M-y'. 25872 25873 25874File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction 25875 2587631.2.4 Readline Arguments 25877------------------------- 25878 25879You can pass numeric arguments to Readline commands. Sometimes the 25880argument acts as a repeat count, other times it is the sign of the 25881argument that is significant. If you pass a negative argument to a 25882command which normally acts in a forward direction, that command will 25883act in a backward direction. For example, to kill text back to the 25884start of the line, you might type `M-- C-k'. 25885 25886 The general way to pass numeric arguments to a command is to type 25887meta digits before the command. If the first `digit' typed is a minus 25888sign (`-'), then the sign of the argument will be negative. Once you 25889have typed one meta digit to get the argument started, you can type the 25890remainder of the digits, and then the command. For example, to give 25891the `C-d' command an argument of 10, you could type `M-1 0 C-d', which 25892will delete the next ten characters on the input line. 25893 25894 25895File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction 25896 2589731.2.5 Searching for Commands in the History 25898-------------------------------------------- 25899 25900Readline provides commands for searching through the command history 25901for lines containing a specified string. There are two search modes: 25902"incremental" and "non-incremental". 25903 25904 Incremental searches begin before the user has finished typing the 25905search string. As each character of the search string is typed, 25906Readline displays the next entry from the history matching the string 25907typed so far. An incremental search requires only as many characters 25908as needed to find the desired history entry. To search backward in the 25909history for a particular string, type `C-r'. Typing `C-s' searches 25910forward through the history. The characters present in the value of 25911the `isearch-terminators' variable are used to terminate an incremental 25912search. If that variable has not been assigned a value, the <ESC> and 25913`C-J' characters will terminate an incremental search. `C-g' will 25914abort an incremental search and restore the original line. When the 25915search is terminated, the history entry containing the search string 25916becomes the current line. 25917 25918 To find other matching entries in the history list, type `C-r' or 25919`C-s' as appropriate. This will search backward or forward in the 25920history for the next entry matching the search string typed so far. 25921Any other key sequence bound to a Readline command will terminate the 25922search and execute that command. For instance, a <RET> will terminate 25923the search and accept the line, thereby executing the command from the 25924history list. A movement command will terminate the search, make the 25925last line found the current line, and begin editing. 25926 25927 Readline remembers the last incremental search string. If two 25928`C-r's are typed without any intervening characters defining a new 25929search string, any remembered search string is used. 25930 25931 Non-incremental searches read the entire search string before 25932starting to search for matching history lines. The search string may be 25933typed by the user or be part of the contents of the current line. 25934 25935 25936File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing 25937 2593831.3 Readline Init File 25939======================= 25940 25941Although the Readline library comes with a set of Emacs-like 25942keybindings installed by default, it is possible to use a different set 25943of keybindings. Any user can customize programs that use Readline by 25944putting commands in an "inputrc" file, conventionally in his home 25945directory. The name of this file is taken from the value of the 25946environment variable `INPUTRC'. If that variable is unset, the default 25947is `~/.inputrc'. 25948 25949 When a program which uses the Readline library starts up, the init 25950file is read, and the key bindings are set. 25951 25952 In addition, the `C-x C-r' command re-reads this init file, thus 25953incorporating any changes that you might have made to it. 25954 25955* Menu: 25956 25957* Readline Init File Syntax:: Syntax for the commands in the inputrc file. 25958 25959* Conditional Init Constructs:: Conditional key bindings in the inputrc file. 25960 25961* Sample Init File:: An example inputrc file. 25962 25963 25964File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File 25965 2596631.3.1 Readline Init File Syntax 25967-------------------------------- 25968 25969There are only a few basic constructs allowed in the Readline init 25970file. Blank lines are ignored. Lines beginning with a `#' are 25971comments. Lines beginning with a `$' indicate conditional constructs 25972(*note Conditional Init Constructs::). Other lines denote variable 25973settings and key bindings. 25974 25975Variable Settings 25976 You can modify the run-time behavior of Readline by altering the 25977 values of variables in Readline using the `set' command within the 25978 init file. The syntax is simple: 25979 25980 set VARIABLE VALUE 25981 25982 Here, for example, is how to change from the default Emacs-like 25983 key binding to use `vi' line editing commands: 25984 25985 set editing-mode vi 25986 25987 Variable names and values, where appropriate, are recognized 25988 without regard to case. Unrecognized variable names are ignored. 25989 25990 Boolean variables (those that can be set to on or off) are set to 25991 on if the value is null or empty, ON (case-insensitive), or 1. 25992 Any other value results in the variable being set to off. 25993 25994 A great deal of run-time behavior is changeable with the following 25995 variables. 25996 25997 `bell-style' 25998 Controls what happens when Readline wants to ring the 25999 terminal bell. If set to `none', Readline never rings the 26000 bell. If set to `visible', Readline uses a visible bell if 26001 one is available. If set to `audible' (the default), 26002 Readline attempts to ring the terminal's bell. 26003 26004 `bind-tty-special-chars' 26005 If set to `on', Readline attempts to bind the control 26006 characters treated specially by the kernel's terminal driver 26007 to their Readline equivalents. 26008 26009 `comment-begin' 26010 The string to insert at the beginning of the line when the 26011 `insert-comment' command is executed. The default value is 26012 `"#"'. 26013 26014 `completion-ignore-case' 26015 If set to `on', Readline performs filename matching and 26016 completion in a case-insensitive fashion. The default value 26017 is `off'. 26018 26019 `completion-query-items' 26020 The number of possible completions that determines when the 26021 user is asked whether the list of possibilities should be 26022 displayed. If the number of possible completions is greater 26023 than this value, Readline will ask the user whether or not he 26024 wishes to view them; otherwise, they are simply listed. This 26025 variable must be set to an integer value greater than or 26026 equal to 0. A negative value means Readline should never ask. 26027 The default limit is `100'. 26028 26029 `convert-meta' 26030 If set to `on', Readline will convert characters with the 26031 eighth bit set to an ASCII key sequence by stripping the 26032 eighth bit and prefixing an <ESC> character, converting them 26033 to a meta-prefixed key sequence. The default value is `on'. 26034 26035 `disable-completion' 26036 If set to `On', Readline will inhibit word completion. 26037 Completion characters will be inserted into the line as if 26038 they had been mapped to `self-insert'. The default is `off'. 26039 26040 `editing-mode' 26041 The `editing-mode' variable controls which default set of key 26042 bindings is used. By default, Readline starts up in Emacs 26043 editing mode, where the keystrokes are most similar to Emacs. 26044 This variable can be set to either `emacs' or `vi'. 26045 26046 `enable-keypad' 26047 When set to `on', Readline will try to enable the application 26048 keypad when it is called. Some systems need this to enable 26049 the arrow keys. The default is `off'. 26050 26051 `expand-tilde' 26052 If set to `on', tilde expansion is performed when Readline 26053 attempts word completion. The default is `off'. 26054 26055 `history-preserve-point' 26056 If set to `on', the history code attempts to place point at 26057 the same location on each history line retrieved with 26058 `previous-history' or `next-history'. The default is `off'. 26059 26060 `horizontal-scroll-mode' 26061 This variable can be set to either `on' or `off'. Setting it 26062 to `on' means that the text of the lines being edited will 26063 scroll horizontally on a single screen line when they are 26064 longer than the width of the screen, instead of wrapping onto 26065 a new screen line. By default, this variable is set to `off'. 26066 26067 `input-meta' 26068 If set to `on', Readline will enable eight-bit input (it will 26069 not clear the eighth bit in the characters it reads), 26070 regardless of what the terminal claims it can support. The 26071 default value is `off'. The name `meta-flag' is a synonym 26072 for this variable. 26073 26074 `isearch-terminators' 26075 The string of characters that should terminate an incremental 26076 search without subsequently executing the character as a 26077 command (*note Searching::). If this variable has not been 26078 given a value, the characters <ESC> and `C-J' will terminate 26079 an incremental search. 26080 26081 `keymap' 26082 Sets Readline's idea of the current keymap for key binding 26083 commands. Acceptable `keymap' names are `emacs', 26084 `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', 26085 `vi-command', and `vi-insert'. `vi' is equivalent to 26086 `vi-command'; `emacs' is equivalent to `emacs-standard'. The 26087 default value is `emacs'. The value of the `editing-mode' 26088 variable also affects the default keymap. 26089 26090 `mark-directories' 26091 If set to `on', completed directory names have a slash 26092 appended. The default is `on'. 26093 26094 `mark-modified-lines' 26095 This variable, when set to `on', causes Readline to display an 26096 asterisk (`*') at the start of history lines which have been 26097 modified. This variable is `off' by default. 26098 26099 `mark-symlinked-directories' 26100 If set to `on', completed names which are symbolic links to 26101 directories have a slash appended (subject to the value of 26102 `mark-directories'). The default is `off'. 26103 26104 `match-hidden-files' 26105 This variable, when set to `on', causes Readline to match 26106 files whose names begin with a `.' (hidden files) when 26107 performing filename completion, unless the leading `.' is 26108 supplied by the user in the filename to be completed. This 26109 variable is `on' by default. 26110 26111 `output-meta' 26112 If set to `on', Readline will display characters with the 26113 eighth bit set directly rather than as a meta-prefixed escape 26114 sequence. The default is `off'. 26115 26116 `page-completions' 26117 If set to `on', Readline uses an internal `more'-like pager 26118 to display a screenful of possible completions at a time. 26119 This variable is `on' by default. 26120 26121 `print-completions-horizontally' 26122 If set to `on', Readline will display completions with matches 26123 sorted horizontally in alphabetical order, rather than down 26124 the screen. The default is `off'. 26125 26126 `show-all-if-ambiguous' 26127 This alters the default behavior of the completion functions. 26128 If set to `on', words which have more than one possible 26129 completion cause the matches to be listed immediately instead 26130 of ringing the bell. The default value is `off'. 26131 26132 `show-all-if-unmodified' 26133 This alters the default behavior of the completion functions 26134 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to 26135 `on', words which have more than one possible completion 26136 without any possible partial completion (the possible 26137 completions don't share a common prefix) cause the matches to 26138 be listed immediately instead of ringing the bell. The 26139 default value is `off'. 26140 26141 `visible-stats' 26142 If set to `on', a character denoting a file's type is 26143 appended to the filename when listing possible completions. 26144 The default is `off'. 26145 26146 26147Key Bindings 26148 The syntax for controlling key bindings in the init file is 26149 simple. First you need to find the name of the command that you 26150 want to change. The following sections contain tables of the 26151 command name, the default keybinding, if any, and a short 26152 description of what the command does. 26153 26154 Once you know the name of the command, simply place on a line in 26155 the init file the name of the key you wish to bind the command to, 26156 a colon, and then the name of the command. The name of the key 26157 can be expressed in different ways, depending on what you find most 26158 comfortable. 26159 26160 In addition to command names, readline allows keys to be bound to 26161 a string that is inserted when the key is pressed (a MACRO). 26162 26163 KEYNAME: FUNCTION-NAME or MACRO 26164 KEYNAME is the name of a key spelled out in English. For 26165 example: 26166 Control-u: universal-argument 26167 Meta-Rubout: backward-kill-word 26168 Control-o: "> output" 26169 26170 In the above example, `C-u' is bound to the function 26171 `universal-argument', `M-DEL' is bound to the function 26172 `backward-kill-word', and `C-o' is bound to run the macro 26173 expressed on the right hand side (that is, to insert the text 26174 `> output' into the line). 26175 26176 A number of symbolic character names are recognized while 26177 processing this key binding syntax: DEL, ESC, ESCAPE, LFD, 26178 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. 26179 26180 "KEYSEQ": FUNCTION-NAME or MACRO 26181 KEYSEQ differs from KEYNAME above in that strings denoting an 26182 entire key sequence can be specified, by placing the key 26183 sequence in double quotes. Some GNU Emacs style key escapes 26184 can be used, as in the following example, but the special 26185 character names are not recognized. 26186 26187 "\C-u": universal-argument 26188 "\C-x\C-r": re-read-init-file 26189 "\e[11~": "Function Key 1" 26190 26191 In the above example, `C-u' is again bound to the function 26192 `universal-argument' (just as it was in the first example), 26193 `C-x C-r' is bound to the function `re-read-init-file', and 26194 `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function 26195 Key 1'. 26196 26197 26198 The following GNU Emacs style escape sequences are available when 26199 specifying key sequences: 26200 26201 `\C-' 26202 control prefix 26203 26204 `\M-' 26205 meta prefix 26206 26207 `\e' 26208 an escape character 26209 26210 `\\' 26211 backslash 26212 26213 `\"' 26214 <">, a double quotation mark 26215 26216 `\'' 26217 <'>, a single quote or apostrophe 26218 26219 In addition to the GNU Emacs style escape sequences, a second set 26220 of backslash escapes is available: 26221 26222 `\a' 26223 alert (bell) 26224 26225 `\b' 26226 backspace 26227 26228 `\d' 26229 delete 26230 26231 `\f' 26232 form feed 26233 26234 `\n' 26235 newline 26236 26237 `\r' 26238 carriage return 26239 26240 `\t' 26241 horizontal tab 26242 26243 `\v' 26244 vertical tab 26245 26246 `\NNN' 26247 the eight-bit character whose value is the octal value NNN 26248 (one to three digits) 26249 26250 `\xHH' 26251 the eight-bit character whose value is the hexadecimal value 26252 HH (one or two hex digits) 26253 26254 When entering the text of a macro, single or double quotes must be 26255 used to indicate a macro definition. Unquoted text is assumed to 26256 be a function name. In the macro body, the backslash escapes 26257 described above are expanded. Backslash will quote any other 26258 character in the macro text, including `"' and `''. For example, 26259 the following binding will make `C-x \' insert a single `\' into 26260 the line: 26261 "\C-x\\": "\\" 26262 26263 26264 26265File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File 26266 2626731.3.2 Conditional Init Constructs 26268---------------------------------- 26269 26270Readline implements a facility similar in spirit to the conditional 26271compilation features of the C preprocessor which allows key bindings 26272and variable settings to be performed as the result of tests. There 26273are four parser directives used. 26274 26275`$if' 26276 The `$if' construct allows bindings to be made based on the 26277 editing mode, the terminal being used, or the application using 26278 Readline. The text of the test extends to the end of the line; no 26279 characters are required to isolate it. 26280 26281 `mode' 26282 The `mode=' form of the `$if' directive is used to test 26283 whether Readline is in `emacs' or `vi' mode. This may be 26284 used in conjunction with the `set keymap' command, for 26285 instance, to set bindings in the `emacs-standard' and 26286 `emacs-ctlx' keymaps only if Readline is starting out in 26287 `emacs' mode. 26288 26289 `term' 26290 The `term=' form may be used to include terminal-specific key 26291 bindings, perhaps to bind the key sequences output by the 26292 terminal's function keys. The word on the right side of the 26293 `=' is tested against both the full name of the terminal and 26294 the portion of the terminal name before the first `-'. This 26295 allows `sun' to match both `sun' and `sun-cmd', for instance. 26296 26297 `application' 26298 The APPLICATION construct is used to include 26299 application-specific settings. Each program using the 26300 Readline library sets the APPLICATION NAME, and you can test 26301 for a particular value. This could be used to bind key 26302 sequences to functions useful for a specific program. For 26303 instance, the following command adds a key sequence that 26304 quotes the current or previous word in Bash: 26305 $if Bash 26306 # Quote the current or previous word 26307 "\C-xq": "\eb\"\ef\"" 26308 $endif 26309 26310`$endif' 26311 This command, as seen in the previous example, terminates an `$if' 26312 command. 26313 26314`$else' 26315 Commands in this branch of the `$if' directive are executed if the 26316 test fails. 26317 26318`$include' 26319 This directive takes a single filename as an argument and reads 26320 commands and bindings from that file. For example, the following 26321 directive reads from `/etc/inputrc': 26322 $include /etc/inputrc 26323 26324 26325File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File 26326 2632731.3.3 Sample Init File 26328----------------------- 26329 26330Here is an example of an INPUTRC file. This illustrates key binding, 26331variable assignment, and conditional syntax. 26332 26333 26334 # This file controls the behaviour of line input editing for 26335 # programs that use the GNU Readline library. Existing 26336 # programs include FTP, Bash, and GDB. 26337 # 26338 # You can re-read the inputrc file with C-x C-r. 26339 # Lines beginning with '#' are comments. 26340 # 26341 # First, include any systemwide bindings and variable 26342 # assignments from /etc/Inputrc 26343 $include /etc/Inputrc 26344 26345 # 26346 # Set various bindings for emacs mode. 26347 26348 set editing-mode emacs 26349 26350 $if mode=emacs 26351 26352 Meta-Control-h: backward-kill-word Text after the function name is ignored 26353 26354 # 26355 # Arrow keys in keypad mode 26356 # 26357 #"\M-OD": backward-char 26358 #"\M-OC": forward-char 26359 #"\M-OA": previous-history 26360 #"\M-OB": next-history 26361 # 26362 # Arrow keys in ANSI mode 26363 # 26364 "\M-[D": backward-char 26365 "\M-[C": forward-char 26366 "\M-[A": previous-history 26367 "\M-[B": next-history 26368 # 26369 # Arrow keys in 8 bit keypad mode 26370 # 26371 #"\M-\C-OD": backward-char 26372 #"\M-\C-OC": forward-char 26373 #"\M-\C-OA": previous-history 26374 #"\M-\C-OB": next-history 26375 # 26376 # Arrow keys in 8 bit ANSI mode 26377 # 26378 #"\M-\C-[D": backward-char 26379 #"\M-\C-[C": forward-char 26380 #"\M-\C-[A": previous-history 26381 #"\M-\C-[B": next-history 26382 26383 C-q: quoted-insert 26384 26385 $endif 26386 26387 # An old-style binding. This happens to be the default. 26388 TAB: complete 26389 26390 # Macros that are convenient for shell interaction 26391 $if Bash 26392 # edit the path 26393 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" 26394 # prepare to type a quoted word -- 26395 # insert open and close double quotes 26396 # and move to just after the open quote 26397 "\C-x\"": "\"\"\C-b" 26398 # insert a backslash (testing backslash escapes 26399 # in sequences and macros) 26400 "\C-x\\": "\\" 26401 # Quote the current or previous word 26402 "\C-xq": "\eb\"\ef\"" 26403 # Add a binding to refresh the line, which is unbound 26404 "\C-xr": redraw-current-line 26405 # Edit variable on current line. 26406 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" 26407 $endif 26408 26409 # use a visible bell if one is available 26410 set bell-style visible 26411 26412 # don't strip characters to 7 bits when reading 26413 set input-meta on 26414 26415 # allow iso-latin1 characters to be inserted rather 26416 # than converted to prefix-meta sequences 26417 set convert-meta off 26418 26419 # display characters with the eighth bit set directly 26420 # rather than as meta-prefixed characters 26421 set output-meta on 26422 26423 # if there are more than 150 possible completions for 26424 # a word, ask the user if he wants to see all of them 26425 set completion-query-items 150 26426 26427 # For FTP 26428 $if Ftp 26429 "\C-xg": "get \M-?" 26430 "\C-xt": "put \M-?" 26431 "\M-.": yank-last-arg 26432 $endif 26433 26434 26435File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing 26436 2643731.4 Bindable Readline Commands 26438=============================== 26439 26440* Menu: 26441 26442* Commands For Moving:: Moving about the line. 26443* Commands For History:: Getting at previous lines. 26444* Commands For Text:: Commands for changing text. 26445* Commands For Killing:: Commands for killing and yanking. 26446* Numeric Arguments:: Specifying numeric arguments, repeat counts. 26447* Commands For Completion:: Getting Readline to do the typing for you. 26448* Keyboard Macros:: Saving and re-executing typed characters 26449* Miscellaneous Commands:: Other miscellaneous commands. 26450 26451 This section describes Readline commands that may be bound to key 26452sequences. Command names without an accompanying key sequence are 26453unbound by default. 26454 26455 In the following descriptions, "point" refers to the current cursor 26456position, and "mark" refers to a cursor position saved by the 26457`set-mark' command. The text between the point and mark is referred to 26458as the "region". 26459 26460 26461File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands 26462 2646331.4.1 Commands For Moving 26464-------------------------- 26465 26466`beginning-of-line (C-a)' 26467 Move to the start of the current line. 26468 26469`end-of-line (C-e)' 26470 Move to the end of the line. 26471 26472`forward-char (C-f)' 26473 Move forward a character. 26474 26475`backward-char (C-b)' 26476 Move back a character. 26477 26478`forward-word (M-f)' 26479 Move forward to the end of the next word. Words are composed of 26480 letters and digits. 26481 26482`backward-word (M-b)' 26483 Move back to the start of the current or previous word. Words are 26484 composed of letters and digits. 26485 26486`clear-screen (C-l)' 26487 Clear the screen and redraw the current line, leaving the current 26488 line at the top of the screen. 26489 26490`redraw-current-line ()' 26491 Refresh the current line. By default, this is unbound. 26492 26493 26494 26495File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands 26496 2649731.4.2 Commands For Manipulating The History 26498-------------------------------------------- 26499 26500`accept-line (Newline or Return)' 26501 Accept the line regardless of where the cursor is. If this line is 26502 non-empty, it may be added to the history list for future recall 26503 with `add_history()'. If this line is a modified history line, 26504 the history line is restored to its original state. 26505 26506`previous-history (C-p)' 26507 Move `back' through the history list, fetching the previous 26508 command. 26509 26510`next-history (C-n)' 26511 Move `forward' through the history list, fetching the next command. 26512 26513`beginning-of-history (M-<)' 26514 Move to the first line in the history. 26515 26516`end-of-history (M->)' 26517 Move to the end of the input history, i.e., the line currently 26518 being entered. 26519 26520`reverse-search-history (C-r)' 26521 Search backward starting at the current line and moving `up' 26522 through the history as necessary. This is an incremental search. 26523 26524`forward-search-history (C-s)' 26525 Search forward starting at the current line and moving `down' 26526 through the the history as necessary. This is an incremental 26527 search. 26528 26529`non-incremental-reverse-search-history (M-p)' 26530 Search backward starting at the current line and moving `up' 26531 through the history as necessary using a non-incremental search 26532 for a string supplied by the user. 26533 26534`non-incremental-forward-search-history (M-n)' 26535 Search forward starting at the current line and moving `down' 26536 through the the history as necessary using a non-incremental search 26537 for a string supplied by the user. 26538 26539`history-search-forward ()' 26540 Search forward through the history for the string of characters 26541 between the start of the current line and the point. This is a 26542 non-incremental search. By default, this command is unbound. 26543 26544`history-search-backward ()' 26545 Search backward through the history for the string of characters 26546 between the start of the current line and the point. This is a 26547 non-incremental search. By default, this command is unbound. 26548 26549`yank-nth-arg (M-C-y)' 26550 Insert the first argument to the previous command (usually the 26551 second word on the previous line) at point. With an argument N, 26552 insert the Nth word from the previous command (the words in the 26553 previous command begin with word 0). A negative argument inserts 26554 the Nth word from the end of the previous command. Once the 26555 argument N is computed, the argument is extracted as if the `!N' 26556 history expansion had been specified. 26557 26558`yank-last-arg (M-. or M-_)' 26559 Insert last argument to the previous command (the last word of the 26560 previous history entry). With an argument, behave exactly like 26561 `yank-nth-arg'. Successive calls to `yank-last-arg' move back 26562 through the history list, inserting the last argument of each line 26563 in turn. The history expansion facilities are used to extract the 26564 last argument, as if the `!$' history expansion had been specified. 26565 26566 26567 26568File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands 26569 2657031.4.3 Commands For Changing Text 26571--------------------------------- 26572 26573`delete-char (C-d)' 26574 Delete the character at point. If point is at the beginning of 26575 the line, there are no characters in the line, and the last 26576 character typed was not bound to `delete-char', then return EOF. 26577 26578`backward-delete-char (Rubout)' 26579 Delete the character behind the cursor. A numeric argument means 26580 to kill the characters instead of deleting them. 26581 26582`forward-backward-delete-char ()' 26583 Delete the character under the cursor, unless the cursor is at the 26584 end of the line, in which case the character behind the cursor is 26585 deleted. By default, this is not bound to a key. 26586 26587`quoted-insert (C-q or C-v)' 26588 Add the next character typed to the line verbatim. This is how to 26589 insert key sequences like `C-q', for example. 26590 26591`tab-insert (M-<TAB>)' 26592 Insert a tab character. 26593 26594`self-insert (a, b, A, 1, !, ...)' 26595 Insert yourself. 26596 26597`transpose-chars (C-t)' 26598 Drag the character before the cursor forward over the character at 26599 the cursor, moving the cursor forward as well. If the insertion 26600 point is at the end of the line, then this transposes the last two 26601 characters of the line. Negative arguments have no effect. 26602 26603`transpose-words (M-t)' 26604 Drag the word before point past the word after point, moving point 26605 past that word as well. If the insertion point is at the end of 26606 the line, this transposes the last two words on the line. 26607 26608`upcase-word (M-u)' 26609 Uppercase the current (or following) word. With a negative 26610 argument, uppercase the previous word, but do not move the cursor. 26611 26612`downcase-word (M-l)' 26613 Lowercase the current (or following) word. With a negative 26614 argument, lowercase the previous word, but do not move the cursor. 26615 26616`capitalize-word (M-c)' 26617 Capitalize the current (or following) word. With a negative 26618 argument, capitalize the previous word, but do not move the cursor. 26619 26620`overwrite-mode ()' 26621 Toggle overwrite mode. With an explicit positive numeric argument, 26622 switches to overwrite mode. With an explicit non-positive numeric 26623 argument, switches to insert mode. This command affects only 26624 `emacs' mode; `vi' mode does overwrite differently. Each call to 26625 `readline()' starts in insert mode. 26626 26627 In overwrite mode, characters bound to `self-insert' replace the 26628 text at point rather than pushing the text to the right. 26629 Characters bound to `backward-delete-char' replace the character 26630 before point with a space. 26631 26632 By default, this command is unbound. 26633 26634 26635 26636File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands 26637 2663831.4.4 Killing And Yanking 26639-------------------------- 26640 26641`kill-line (C-k)' 26642 Kill the text from point to the end of the line. 26643 26644`backward-kill-line (C-x Rubout)' 26645 Kill backward to the beginning of the line. 26646 26647`unix-line-discard (C-u)' 26648 Kill backward from the cursor to the beginning of the current line. 26649 26650`kill-whole-line ()' 26651 Kill all characters on the current line, no matter where point is. 26652 By default, this is unbound. 26653 26654`kill-word (M-d)' 26655 Kill from point to the end of the current word, or if between 26656 words, to the end of the next word. Word boundaries are the same 26657 as `forward-word'. 26658 26659`backward-kill-word (M-<DEL>)' 26660 Kill the word behind point. Word boundaries are the same as 26661 `backward-word'. 26662 26663`unix-word-rubout (C-w)' 26664 Kill the word behind point, using white space as a word boundary. 26665 The killed text is saved on the kill-ring. 26666 26667`unix-filename-rubout ()' 26668 Kill the word behind point, using white space and the slash 26669 character as the word boundaries. The killed text is saved on the 26670 kill-ring. 26671 26672`delete-horizontal-space ()' 26673 Delete all spaces and tabs around point. By default, this is 26674 unbound. 26675 26676`kill-region ()' 26677 Kill the text in the current region. By default, this command is 26678 unbound. 26679 26680`copy-region-as-kill ()' 26681 Copy the text in the region to the kill buffer, so it can be yanked 26682 right away. By default, this command is unbound. 26683 26684`copy-backward-word ()' 26685 Copy the word before point to the kill buffer. The word 26686 boundaries are the same as `backward-word'. By default, this 26687 command is unbound. 26688 26689`copy-forward-word ()' 26690 Copy the word following point to the kill buffer. The word 26691 boundaries are the same as `forward-word'. By default, this 26692 command is unbound. 26693 26694`yank (C-y)' 26695 Yank the top of the kill ring into the buffer at point. 26696 26697`yank-pop (M-y)' 26698 Rotate the kill-ring, and yank the new top. You can only do this 26699 if the prior command is `yank' or `yank-pop'. 26700 26701 26702File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands 26703 2670431.4.5 Specifying Numeric Arguments 26705----------------------------------- 26706 26707`digit-argument (M-0, M-1, ... M--)' 26708 Add this digit to the argument already accumulating, or start a new 26709 argument. `M--' starts a negative argument. 26710 26711`universal-argument ()' 26712 This is another way to specify an argument. If this command is 26713 followed by one or more digits, optionally with a leading minus 26714 sign, those digits define the argument. If the command is 26715 followed by digits, executing `universal-argument' again ends the 26716 numeric argument, but is otherwise ignored. As a special case, if 26717 this command is immediately followed by a character that is 26718 neither a digit or minus sign, the argument count for the next 26719 command is multiplied by four. The argument count is initially 26720 one, so executing this function the first time makes the argument 26721 count four, a second time makes the argument count sixteen, and so 26722 on. By default, this is not bound to a key. 26723 26724 26725File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands 26726 2672731.4.6 Letting Readline Type For You 26728------------------------------------ 26729 26730`complete (<TAB>)' 26731 Attempt to perform completion on the text before point. The 26732 actual completion performed is application-specific. The default 26733 is filename completion. 26734 26735`possible-completions (M-?)' 26736 List the possible completions of the text before point. 26737 26738`insert-completions (M-*)' 26739 Insert all completions of the text before point that would have 26740 been generated by `possible-completions'. 26741 26742`menu-complete ()' 26743 Similar to `complete', but replaces the word to be completed with 26744 a single match from the list of possible completions. Repeated 26745 execution of `menu-complete' steps through the list of possible 26746 completions, inserting each match in turn. At the end of the list 26747 of completions, the bell is rung (subject to the setting of 26748 `bell-style') and the original text is restored. An argument of N 26749 moves N positions forward in the list of matches; a negative 26750 argument may be used to move backward through the list. This 26751 command is intended to be bound to <TAB>, but is unbound by 26752 default. 26753 26754`delete-char-or-list ()' 26755 Deletes the character under the cursor if not at the beginning or 26756 end of the line (like `delete-char'). If at the end of the line, 26757 behaves identically to `possible-completions'. This command is 26758 unbound by default. 26759 26760 26761 26762File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands 26763 2676431.4.7 Keyboard Macros 26765---------------------- 26766 26767`start-kbd-macro (C-x ()' 26768 Begin saving the characters typed into the current keyboard macro. 26769 26770`end-kbd-macro (C-x ))' 26771 Stop saving the characters typed into the current keyboard macro 26772 and save the definition. 26773 26774`call-last-kbd-macro (C-x e)' 26775 Re-execute the last keyboard macro defined, by making the 26776 characters in the macro appear as if typed at the keyboard. 26777 26778 26779 26780File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands 26781 2678231.4.8 Some Miscellaneous Commands 26783---------------------------------- 26784 26785`re-read-init-file (C-x C-r)' 26786 Read in the contents of the INPUTRC file, and incorporate any 26787 bindings or variable assignments found there. 26788 26789`abort (C-g)' 26790 Abort the current editing command and ring the terminal's bell 26791 (subject to the setting of `bell-style'). 26792 26793`do-uppercase-version (M-a, M-b, M-X, ...)' 26794 If the metafied character X is lowercase, run the command that is 26795 bound to the corresponding uppercase character. 26796 26797`prefix-meta (<ESC>)' 26798 Metafy the next character typed. This is for keyboards without a 26799 meta key. Typing `<ESC> f' is equivalent to typing `M-f'. 26800 26801`undo (C-_ or C-x C-u)' 26802 Incremental undo, separately remembered for each line. 26803 26804`revert-line (M-r)' 26805 Undo all changes made to this line. This is like executing the 26806 `undo' command enough times to get back to the beginning. 26807 26808`tilde-expand (M-~)' 26809 Perform tilde expansion on the current word. 26810 26811`set-mark (C-@)' 26812 Set the mark to the point. If a numeric argument is supplied, the 26813 mark is set to that position. 26814 26815`exchange-point-and-mark (C-x C-x)' 26816 Swap the point with the mark. The current cursor position is set 26817 to the saved position, and the old cursor position is saved as the 26818 mark. 26819 26820`character-search (C-])' 26821 A character is read and point is moved to the next occurrence of 26822 that character. A negative count searches for previous 26823 occurrences. 26824 26825`character-search-backward (M-C-])' 26826 A character is read and point is moved to the previous occurrence 26827 of that character. A negative count searches for subsequent 26828 occurrences. 26829 26830`insert-comment (M-#)' 26831 Without a numeric argument, the value of the `comment-begin' 26832 variable is inserted at the beginning of the current line. If a 26833 numeric argument is supplied, this command acts as a toggle: if 26834 the characters at the beginning of the line do not match the value 26835 of `comment-begin', the value is inserted, otherwise the 26836 characters in `comment-begin' are deleted from the beginning of 26837 the line. In either case, the line is accepted as if a newline 26838 had been typed. 26839 26840`dump-functions ()' 26841 Print all of the functions and their key bindings to the Readline 26842 output stream. If a numeric argument is supplied, the output is 26843 formatted in such a way that it can be made part of an INPUTRC 26844 file. This command is unbound by default. 26845 26846`dump-variables ()' 26847 Print all of the settable variables and their values to the 26848 Readline output stream. If a numeric argument is supplied, the 26849 output is formatted in such a way that it can be made part of an 26850 INPUTRC file. This command is unbound by default. 26851 26852`dump-macros ()' 26853 Print all of the Readline key sequences bound to macros and the 26854 strings they output. If a numeric argument is supplied, the 26855 output is formatted in such a way that it can be made part of an 26856 INPUTRC file. This command is unbound by default. 26857 26858`emacs-editing-mode (C-e)' 26859 When in `vi' command mode, this causes a switch to `emacs' editing 26860 mode. 26861 26862`vi-editing-mode (M-C-j)' 26863 When in `emacs' editing mode, this causes a switch to `vi' editing 26864 mode. 26865 26866 26867 26868File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing 26869 2687031.5 Readline vi Mode 26871===================== 26872 26873While the Readline library does not have a full set of `vi' editing 26874functions, it does contain enough to allow simple editing of the line. 26875The Readline `vi' mode behaves as specified in the POSIX 1003.2 26876standard. 26877 26878 In order to switch interactively between `emacs' and `vi' editing 26879modes, use the command `M-C-j' (bound to emacs-editing-mode when in 26880`vi' mode and to vi-editing-mode in `emacs' mode). The Readline 26881default is `emacs' mode. 26882 26883 When you enter a line in `vi' mode, you are already placed in 26884`insertion' mode, as if you had typed an `i'. Pressing <ESC> switches 26885you into `command' mode, where you can edit the text of the line with 26886the standard `vi' movement keys, move to previous history lines with 26887`k' and subsequent lines with `j', and so forth. 26888 26889 26890File: gdb.info, Node: Using History Interactively, Next: Formatting Documentation, Prev: Command Line Editing, Up: Top 26891 2689232 Using History Interactively 26893****************************** 26894 26895This chapter describes how to use the GNU History Library interactively, 26896from a user's standpoint. It should be considered a user's guide. For 26897information on using the GNU History Library in other programs, see the 26898GNU Readline Library Manual. 26899 26900* Menu: 26901 26902* History Interaction:: What it feels like using History as a user. 26903 26904 26905File: gdb.info, Node: History Interaction, Up: Using History Interactively 26906 2690732.1 History Expansion 26908====================== 26909 26910The History library provides a history expansion feature that is similar 26911to the history expansion provided by `csh'. This section describes the 26912syntax used to manipulate the history information. 26913 26914 History expansions introduce words from the history list into the 26915input stream, making it easy to repeat commands, insert the arguments 26916to a previous command into the current input line, or fix errors in 26917previous commands quickly. 26918 26919 History expansion takes place in two parts. The first is to 26920determine which line from the history list should be used during 26921substitution. The second is to select portions of that line for 26922inclusion into the current one. The line selected from the history is 26923called the "event", and the portions of that line that are acted upon 26924are called "words". Various "modifiers" are available to manipulate 26925the selected words. The line is broken into words in the same fashion 26926that Bash does, so that several words surrounded by quotes are 26927considered one word. History expansions are introduced by the 26928appearance of the history expansion character, which is `!' by default. 26929 26930* Menu: 26931 26932* Event Designators:: How to specify which history line to use. 26933* Word Designators:: Specifying which words are of interest. 26934* Modifiers:: Modifying the results of substitution. 26935 26936 26937File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction 26938 2693932.1.1 Event Designators 26940------------------------ 26941 26942An event designator is a reference to a command line entry in the 26943history list. 26944 26945`!' 26946 Start a history substitution, except when followed by a space, tab, 26947 the end of the line, or `='. 26948 26949`!N' 26950 Refer to command line N. 26951 26952`!-N' 26953 Refer to the command N lines back. 26954 26955`!!' 26956 Refer to the previous command. This is a synonym for `!-1'. 26957 26958`!STRING' 26959 Refer to the most recent command starting with STRING. 26960 26961`!?STRING[?]' 26962 Refer to the most recent command containing STRING. The trailing 26963 `?' may be omitted if the STRING is followed immediately by a 26964 newline. 26965 26966`^STRING1^STRING2^' 26967 Quick Substitution. Repeat the last command, replacing STRING1 26968 with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. 26969 26970`!#' 26971 The entire command line typed so far. 26972 26973 26974 26975File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction 26976 2697732.1.2 Word Designators 26978----------------------- 26979 26980Word designators are used to select desired words from the event. A 26981`:' separates the event specification from the word designator. It may 26982be omitted if the word designator begins with a `^', `$', `*', `-', or 26983`%'. Words are numbered from the beginning of the line, with the first 26984word being denoted by 0 (zero). Words are inserted into the current 26985line separated by single spaces. 26986 26987 For example, 26988 26989`!!' 26990 designates the preceding command. When you type this, the 26991 preceding command is repeated in toto. 26992 26993`!!:$' 26994 designates the last argument of the preceding command. This may be 26995 shortened to `!$'. 26996 26997`!fi:2' 26998 designates the second argument of the most recent command starting 26999 with the letters `fi'. 27000 27001 Here are the word designators: 27002 27003`0 (zero)' 27004 The `0'th word. For many applications, this is the command word. 27005 27006`N' 27007 The Nth word. 27008 27009`^' 27010 The first argument; that is, word 1. 27011 27012`$' 27013 The last argument. 27014 27015`%' 27016 The word matched by the most recent `?STRING?' search. 27017 27018`X-Y' 27019 A range of words; `-Y' abbreviates `0-Y'. 27020 27021`*' 27022 All of the words, except the `0'th. This is a synonym for `1-$'. 27023 It is not an error to use `*' if there is just one word in the 27024 event; the empty string is returned in that case. 27025 27026`X*' 27027 Abbreviates `X-$' 27028 27029`X-' 27030 Abbreviates `X-$' like `X*', but omits the last word. 27031 27032 27033 If a word designator is supplied without an event specification, the 27034previous command is used as the event. 27035 27036 27037File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction 27038 2703932.1.3 Modifiers 27040---------------- 27041 27042After the optional word designator, you can add a sequence of one or 27043more of the following modifiers, each preceded by a `:'. 27044 27045`h' 27046 Remove a trailing pathname component, leaving only the head. 27047 27048`t' 27049 Remove all leading pathname components, leaving the tail. 27050 27051`r' 27052 Remove a trailing suffix of the form `.SUFFIX', leaving the 27053 basename. 27054 27055`e' 27056 Remove all but the trailing suffix. 27057 27058`p' 27059 Print the new command but do not execute it. 27060 27061`s/OLD/NEW/' 27062 Substitute NEW for the first occurrence of OLD in the event line. 27063 Any delimiter may be used in place of `/'. The delimiter may be 27064 quoted in OLD and NEW with a single backslash. If `&' appears in 27065 NEW, it is replaced by OLD. A single backslash will quote the 27066 `&'. The final delimiter is optional if it is the last character 27067 on the input line. 27068 27069`&' 27070 Repeat the previous substitution. 27071 27072`g' 27073`a' 27074 Cause changes to be applied over the entire event line. Used in 27075 conjunction with `s', as in `gs/OLD/NEW/', or with `&'. 27076 27077`G' 27078 Apply the following `s' modifier once to each word in the event. 27079 27080 27081 27082File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: Using History Interactively, Up: Top 27083 27084Appendix A Formatting Documentation 27085*********************************** 27086 27087The GDB 4 release includes an already-formatted reference card, ready 27088for printing with PostScript or Ghostscript, in the `gdb' subdirectory 27089of the main source directory(1). If you can use PostScript or 27090Ghostscript with your printer, you can print the reference card 27091immediately with `refcard.ps'. 27092 27093 The release also includes the source for the reference card. You 27094can format it, using TeX, by typing: 27095 27096 make refcard.dvi 27097 27098 The GDB reference card is designed to print in "landscape" mode on 27099US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches 27100high. You will need to specify this form of printing as an option to 27101your DVI output program. 27102 27103 All the documentation for GDB comes as part of the machine-readable 27104distribution. The documentation is written in Texinfo format, which is 27105a documentation system that uses a single source file to produce both 27106on-line information and a printed manual. You can use one of the Info 27107formatting commands to create the on-line version of the documentation 27108and TeX (or `texi2roff') to typeset the printed version. 27109 27110 GDB includes an already formatted copy of the on-line Info version 27111of this manual in the `gdb' subdirectory. The main Info file is 27112`gdb-7.2.50.20100908-cvs/gdb/gdb.info', and it refers to subordinate 27113files matching `gdb.info*' in the same directory. If necessary, you 27114can print out these files, or read them with any editor; but they are 27115easier to read using the `info' subsystem in GNU Emacs or the 27116standalone `info' program, available as part of the GNU Texinfo 27117distribution. 27118 27119 If you want to format these Info files yourself, you need one of the 27120Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. 27121 27122 If you have `makeinfo' installed, and are in the top level GDB 27123source directory (`gdb-7.2.50.20100908-cvs', in the case of version 271247.2.50.20100908-cvs), you can make the Info file by typing: 27125 27126 cd gdb 27127 make gdb.info 27128 27129 If you want to typeset and print copies of this manual, you need TeX, 27130a program to print its DVI output files, and `texinfo.tex', the Texinfo 27131definitions file. 27132 27133 TeX is a typesetting program; it does not print files directly, but 27134produces output files called DVI files. To print a typeset document, 27135you need a program to print DVI files. If your system has TeX 27136installed, chances are it has such a program. The precise command to 27137use depends on your system; `lpr -d' is common; another (for PostScript 27138devices) is `dvips'. The DVI print command may require a file name 27139without any extension or a `.dvi' extension. 27140 27141 TeX also requires a macro definitions file called `texinfo.tex'. 27142This file tells TeX how to typeset a document written in Texinfo 27143format. On its own, TeX cannot either read or typeset a Texinfo file. 27144`texinfo.tex' is distributed with GDB and is located in the 27145`gdb-VERSION-NUMBER/texinfo' directory. 27146 27147 If you have TeX and a DVI printer program installed, you can typeset 27148and print this manual. First switch to the `gdb' subdirectory of the 27149main source directory (for example, to `gdb-7.2.50.20100908-cvs/gdb') 27150and type: 27151 27152 make gdb.dvi 27153 27154 Then give `gdb.dvi' to your DVI printing program. 27155 27156 ---------- Footnotes ---------- 27157 27158 (1) In `gdb-7.2.50.20100908-cvs/gdb/refcard.ps' of the version 271597.2.50.20100908-cvs release. 27160 27161 27162File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top 27163 27164Appendix B Installing GDB 27165************************* 27166 27167* Menu: 27168 27169* Requirements:: Requirements for building GDB 27170* Running Configure:: Invoking the GDB `configure' script 27171* Separate Objdir:: Compiling GDB in another directory 27172* Config Names:: Specifying names for hosts and targets 27173* Configure Options:: Summary of options for configure 27174* System-wide configuration:: Having a system-wide init file 27175 27176 27177File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB 27178 27179B.1 Requirements for Building GDB 27180================================= 27181 27182Building GDB requires various tools and packages to be available. 27183Other packages will be used only if they are found. 27184 27185Tools/Packages Necessary for Building GDB 27186========================================= 27187 27188ISO C90 compiler 27189 GDB is written in ISO C90. It should be buildable with any 27190 working C90 compiler, e.g. GCC. 27191 27192 27193Tools/Packages Optional for Building GDB 27194======================================== 27195 27196Expat 27197 GDB can use the Expat XML parsing library. This library may be 27198 included with your operating system distribution; if it is not, you 27199 can get the latest version from `http://expat.sourceforge.net'. 27200 The `configure' script will search for this library in several 27201 standard locations; if it is installed in an unusual path, you can 27202 use the `--with-libexpat-prefix' option to specify its location. 27203 27204 Expat is used for: 27205 27206 * Remote protocol memory maps (*note Memory Map Format::) 27207 27208 * Target descriptions (*note Target Descriptions::) 27209 27210 * Remote shared library lists (*note Library List Format::) 27211 27212 * MS-Windows shared libraries (*note Shared Libraries::) 27213 27214zlib 27215 GDB will use the `zlib' library, if available, to read compressed 27216 debug sections. Some linkers, such as GNU gold, are capable of 27217 producing binaries with compressed debug sections. If GDB is 27218 compiled with `zlib', it will be able to read the debug 27219 information in such binaries. 27220 27221 The `zlib' library is likely included with your operating system 27222 distribution; if it is not, you can get the latest version from 27223 `http://zlib.net'. 27224 27225iconv 27226 GDB's features related to character sets (*note Character Sets::) 27227 require a functioning `iconv' implementation. If you are on a GNU 27228 system, then this is provided by the GNU C Library. Some other 27229 systems also provide a working `iconv'. 27230 27231 On systems with `iconv', you can install GNU Libiconv. If you 27232 have previously installed Libiconv, you can use the 27233 `--with-libiconv-prefix' option to configure. 27234 27235 GDB's top-level `configure' and `Makefile' will arrange to build 27236 Libiconv if a directory named `libiconv' appears in the top-most 27237 source directory. If Libiconv is built this way, and if the 27238 operating system does not provide a suitable `iconv' 27239 implementation, then the just-built library will automatically be 27240 used by GDB. One easy way to set this up is to download GNU 27241 Libiconv, unpack it, and then rename the directory holding the 27242 Libiconv source code to `libiconv'. 27243 27244 27245File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB 27246 27247B.2 Invoking the GDB `configure' Script 27248======================================= 27249 27250GDB comes with a `configure' script that automates the process of 27251preparing GDB for installation; you can then use `make' to build the 27252`gdb' program. 27253 27254 The GDB distribution includes all the source code you need for GDB 27255in a single directory, whose name is usually composed by appending the 27256version number to `gdb'. 27257 27258 For example, the GDB version 7.2.50.20100908-cvs distribution is in 27259the `gdb-7.2.50.20100908-cvs' directory. That directory contains: 27260 27261`gdb-7.2.50.20100908-cvs/configure (and supporting files)' 27262 script for configuring GDB and all its supporting libraries 27263 27264`gdb-7.2.50.20100908-cvs/gdb' 27265 the source specific to GDB itself 27266 27267`gdb-7.2.50.20100908-cvs/bfd' 27268 source for the Binary File Descriptor library 27269 27270`gdb-7.2.50.20100908-cvs/include' 27271 GNU include files 27272 27273`gdb-7.2.50.20100908-cvs/libiberty' 27274 source for the `-liberty' free software library 27275 27276`gdb-7.2.50.20100908-cvs/opcodes' 27277 source for the library of opcode tables and disassemblers 27278 27279`gdb-7.2.50.20100908-cvs/readline' 27280 source for the GNU command-line interface 27281 27282`gdb-7.2.50.20100908-cvs/glob' 27283 source for the GNU filename pattern-matching subroutine 27284 27285`gdb-7.2.50.20100908-cvs/mmalloc' 27286 source for the GNU memory-mapped malloc package 27287 27288 The simplest way to configure and build GDB is to run `configure' 27289from the `gdb-VERSION-NUMBER' source directory, which in this example 27290is the `gdb-7.2.50.20100908-cvs' directory. 27291 27292 First switch to the `gdb-VERSION-NUMBER' source directory if you are 27293not already in it; then run `configure'. Pass the identifier for the 27294platform on which GDB will run as an argument. 27295 27296 For example: 27297 27298 cd gdb-7.2.50.20100908-cvs 27299 ./configure HOST 27300 make 27301 27302where HOST is an identifier such as `sun4' or `decstation', that 27303identifies the platform where GDB will run. (You can often leave off 27304HOST; `configure' tries to guess the correct value by examining your 27305system.) 27306 27307 Running `configure HOST' and then running `make' builds the `bfd', 27308`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. 27309The configured source files, and the binaries, are left in the 27310corresponding source directories. 27311 27312 `configure' is a Bourne-shell (`/bin/sh') script; if your system 27313does not recognize this automatically when you run a different shell, 27314you may need to run `sh' on it explicitly: 27315 27316 sh configure HOST 27317 27318 If you run `configure' from a directory that contains source 27319directories for multiple libraries or programs, such as the 27320`gdb-7.2.50.20100908-cvs' source directory for version 273217.2.50.20100908-cvs, `configure' creates configuration files for every 27322directory level underneath (unless you tell it not to, with the 27323`--norecursion' option). 27324 27325 You should run the `configure' script from the top directory in the 27326source tree, the `gdb-VERSION-NUMBER' directory. If you run 27327`configure' from one of the subdirectories, you will configure only 27328that subdirectory. That is usually not what you want. In particular, 27329if you run the first `configure' from the `gdb' subdirectory of the 27330`gdb-VERSION-NUMBER' directory, you will omit the configuration of 27331`bfd', `readline', and other sibling directories of the `gdb' 27332subdirectory. This leads to build errors about missing include files 27333such as `bfd/bfd.h'. 27334 27335 You can install `gdb' anywhere; it has no hardwired paths. However, 27336you should make sure that the shell on your path (named by the `SHELL' 27337environment variable) is publicly readable. Remember that GDB uses the 27338shell to start your program--some systems refuse to let GDB debug child 27339processes whose programs are not readable. 27340 27341 27342File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB 27343 27344B.3 Compiling GDB in Another Directory 27345====================================== 27346 27347If you want to run GDB versions for several host or target machines, 27348you need a different `gdb' compiled for each combination of host and 27349target. `configure' is designed to make this easy by allowing you to 27350generate each configuration in a separate subdirectory, rather than in 27351the source directory. If your `make' program handles the `VPATH' 27352feature (GNU `make' does), running `make' in each of these directories 27353builds the `gdb' program specified there. 27354 27355 To build `gdb' in a separate directory, run `configure' with the 27356`--srcdir' option to specify where to find the source. (You also need 27357to specify a path to find `configure' itself from your working 27358directory. If the path to `configure' would be the same as the 27359argument to `--srcdir', you can leave out the `--srcdir' option; it is 27360assumed.) 27361 27362 For example, with version 7.2.50.20100908-cvs, you can build GDB in a 27363separate directory for a Sun 4 like this: 27364 27365 cd gdb-7.2.50.20100908-cvs 27366 mkdir ../gdb-sun4 27367 cd ../gdb-sun4 27368 ../gdb-7.2.50.20100908-cvs/configure sun4 27369 make 27370 27371 When `configure' builds a configuration using a remote source 27372directory, it creates a tree for the binaries with the same structure 27373(and using the same names) as the tree under the source directory. In 27374the example, you'd find the Sun 4 library `libiberty.a' in the 27375directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. 27376 27377 Make sure that your path to the `configure' script has just one 27378instance of `gdb' in it. If your path to `configure' looks like 27379`../gdb-7.2.50.20100908-cvs/gdb/configure', you are configuring only 27380one subdirectory of GDB, not the whole package. This leads to build 27381errors about missing include files such as `bfd/bfd.h'. 27382 27383 One popular reason to build several GDB configurations in separate 27384directories is to configure GDB for cross-compiling (where GDB runs on 27385one machine--the "host"--while debugging programs that run on another 27386machine--the "target"). You specify a cross-debugging target by giving 27387the `--target=TARGET' option to `configure'. 27388 27389 When you run `make' to build a program or library, you must run it 27390in a configured directory--whatever directory you were in when you 27391called `configure' (or one of its subdirectories). 27392 27393 The `Makefile' that `configure' generates in each source directory 27394also runs recursively. If you type `make' in a source directory such 27395as `gdb-7.2.50.20100908-cvs' (or in a separate configured directory 27396configured with `--srcdir=DIRNAME/gdb-7.2.50.20100908-cvs'), you will 27397build all the required libraries, and then build GDB. 27398 27399 When you have multiple hosts or targets configured in separate 27400directories, you can run `make' on them in parallel (for example, if 27401they are NFS-mounted on each of the hosts); they will not interfere 27402with each other. 27403 27404 27405File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB 27406 27407B.4 Specifying Names for Hosts and Targets 27408========================================== 27409 27410The specifications used for hosts and targets in the `configure' script 27411are based on a three-part naming scheme, but some short predefined 27412aliases are also supported. The full naming scheme encodes three pieces 27413of information in the following pattern: 27414 27415 ARCHITECTURE-VENDOR-OS 27416 27417 For example, you can use the alias `sun4' as a HOST argument, or as 27418the value for TARGET in a `--target=TARGET' option. The equivalent 27419full name is `sparc-sun-sunos4'. 27420 27421 The `configure' script accompanying GDB does not provide any query 27422facility to list all supported host and target names or aliases. 27423`configure' calls the Bourne shell script `config.sub' to map 27424abbreviations to full names; you can read the script, if you wish, or 27425you can use it to test your guesses on abbreviations--for example: 27426 27427 % sh config.sub i386-linux 27428 i386-pc-linux-gnu 27429 % sh config.sub alpha-linux 27430 alpha-unknown-linux-gnu 27431 % sh config.sub hp9k700 27432 hppa1.1-hp-hpux 27433 % sh config.sub sun4 27434 sparc-sun-sunos4.1.1 27435 % sh config.sub sun3 27436 m68k-sun-sunos4.1.1 27437 % sh config.sub i986v 27438 Invalid configuration `i986v': machine `i986v' not recognized 27439 27440`config.sub' is also distributed in the GDB source directory 27441(`gdb-7.2.50.20100908-cvs', for version 7.2.50.20100908-cvs). 27442 27443 27444File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB 27445 27446B.5 `configure' Options 27447======================= 27448 27449Here is a summary of the `configure' options and arguments that are 27450most often useful for building GDB. `configure' also has several other 27451options not listed here. *note (configure.info)What Configure Does::, 27452for a full explanation of `configure'. 27453 27454 configure [--help] 27455 [--prefix=DIR] 27456 [--exec-prefix=DIR] 27457 [--srcdir=DIRNAME] 27458 [--norecursion] [--rm] 27459 [--target=TARGET] 27460 HOST 27461 27462You may introduce options with a single `-' rather than `--' if you 27463prefer; but you may abbreviate option names if you use `--'. 27464 27465`--help' 27466 Display a quick summary of how to invoke `configure'. 27467 27468`--prefix=DIR' 27469 Configure the source to install programs and files under directory 27470 `DIR'. 27471 27472`--exec-prefix=DIR' 27473 Configure the source to install programs under directory `DIR'. 27474 27475`--srcdir=DIRNAME' 27476 *Warning: using this option requires GNU `make', or another `make' 27477 that implements the `VPATH' feature.* 27478 Use this option to make configurations in directories separate 27479 from the GDB source directories. Among other things, you can use 27480 this to build (or maintain) several configurations simultaneously, 27481 in separate directories. `configure' writes 27482 configuration-specific files in the current directory, but 27483 arranges for them to use the source in the directory DIRNAME. 27484 `configure' creates directories under the working directory in 27485 parallel to the source directories below DIRNAME. 27486 27487`--norecursion' 27488 Configure only the directory level where `configure' is executed; 27489 do not propagate configuration to subdirectories. 27490 27491`--target=TARGET' 27492 Configure GDB for cross-debugging programs running on the specified 27493 TARGET. Without this option, GDB is configured to debug programs 27494 that run on the same machine (HOST) as GDB itself. 27495 27496 There is no convenient way to generate a list of all available 27497 targets. 27498 27499`HOST ...' 27500 Configure GDB to run on the specified HOST. 27501 27502 There is no convenient way to generate a list of all available 27503 hosts. 27504 27505 There are many other options available as well, but they are 27506generally needed for special purposes only. 27507 27508 27509File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB 27510 27511B.6 System-wide configuration and settings 27512========================================== 27513 27514GDB can be configured to have a system-wide init file; this file will 27515be read and executed at startup (*note What GDB does during startup: 27516Startup.). 27517 27518 Here is the corresponding configure option: 27519 27520`--with-system-gdbinit=FILE' 27521 Specify that the default location of the system-wide init file is 27522 FILE. 27523 27524 If GDB has been configured with the option `--prefix=$prefix', it 27525may be subject to relocation. Two possible cases: 27526 27527 * If the default location of this init file contains `$prefix', it 27528 will be subject to relocation. Suppose that the configure options 27529 are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit'; 27530 if GDB is moved from `$prefix' to `$install', the system init file 27531 is looked for as `$install/etc/gdbinit' instead of 27532 `$prefix/etc/gdbinit'. 27533 27534 * By contrast, if the default location does not contain the prefix, 27535 it will not be relocated. E.g. if GDB has been configured with 27536 `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit', 27537 then GDB will always look for `/usr/share/gdb/gdbinit', wherever 27538 GDB is installed. 27539 27540 27541File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top 27542 27543Appendix C Maintenance Commands 27544******************************* 27545 27546In addition to commands intended for GDB users, GDB includes a number 27547of commands intended for GDB developers, that are not documented 27548elsewhere in this manual. These commands are provided here for 27549reference. (For commands that turn on debugging messages, see *note 27550Debugging Output::.) 27551 27552`maint agent EXPRESSION' 27553`maint agent-eval EXPRESSION' 27554 Translate the given EXPRESSION into remote agent bytecodes. This 27555 command is useful for debugging the Agent Expression mechanism 27556 (*note Agent Expressions::). The `agent' version produces an 27557 expression useful for data collection, such as by tracepoints, 27558 while `maint agent-eval' produces an expression that evaluates 27559 directly to a result. For instance, a collection expression for 27560 `globa + globb' will include bytecodes to record four bytes of 27561 memory at each of the addresses of `globa' and `globb', while 27562 discarding the result of the addition, while an evaluation 27563 expression will do the addition and return the sum. 27564 27565`maint info breakpoints' 27566 Using the same format as `info breakpoints', display both the 27567 breakpoints you've set explicitly, and those GDB is using for 27568 internal purposes. Internal breakpoints are shown with negative 27569 breakpoint numbers. The type column identifies what kind of 27570 breakpoint is shown: 27571 27572 `breakpoint' 27573 Normal, explicitly set breakpoint. 27574 27575 `watchpoint' 27576 Normal, explicitly set watchpoint. 27577 27578 `longjmp' 27579 Internal breakpoint, used to handle correctly stepping through 27580 `longjmp' calls. 27581 27582 `longjmp resume' 27583 Internal breakpoint at the target of a `longjmp'. 27584 27585 `until' 27586 Temporary internal breakpoint used by the GDB `until' command. 27587 27588 `finish' 27589 Temporary internal breakpoint used by the GDB `finish' 27590 command. 27591 27592 `shlib events' 27593 Shared library events. 27594 27595 27596`set displaced-stepping' 27597`show displaced-stepping' 27598 Control whether or not GDB will do "displaced stepping" if the 27599 target supports it. Displaced stepping is a way to single-step 27600 over breakpoints without removing them from the inferior, by 27601 executing an out-of-line copy of the instruction that was 27602 originally at the breakpoint location. It is also known as 27603 out-of-line single-stepping. 27604 27605 `set displaced-stepping on' 27606 If the target architecture supports it, GDB will use 27607 displaced stepping to step over breakpoints. 27608 27609 `set displaced-stepping off' 27610 GDB will not use displaced stepping to step over breakpoints, 27611 even if such is supported by the target architecture. 27612 27613 `set displaced-stepping auto' 27614 This is the default mode. GDB will use displaced stepping 27615 only if non-stop mode is active (*note Non-Stop Mode::) and 27616 the target architecture supports displaced stepping. 27617 27618`maint check-symtabs' 27619 Check the consistency of psymtabs and symtabs. 27620 27621`maint cplus first_component NAME' 27622 Print the first C++ class/namespace component of NAME. 27623 27624`maint cplus namespace' 27625 Print the list of possible C++ namespaces. 27626 27627`maint demangle NAME' 27628 Demangle a C++ or Objective-C mangled NAME. 27629 27630`maint deprecate COMMAND [REPLACEMENT]' 27631`maint undeprecate COMMAND' 27632 Deprecate or undeprecate the named COMMAND. Deprecated commands 27633 cause GDB to issue a warning when you use them. The optional 27634 argument REPLACEMENT says which newer command should be used in 27635 favor of the deprecated one; if it is given, GDB will mention the 27636 replacement as part of the warning. 27637 27638`maint dump-me' 27639 Cause a fatal signal in the debugger and force it to dump its core. 27640 This is supported only on systems which support aborting a program 27641 with the `SIGQUIT' signal. 27642 27643`maint internal-error [MESSAGE-TEXT]' 27644`maint internal-warning [MESSAGE-TEXT]' 27645 Cause GDB to call the internal function `internal_error' or 27646 `internal_warning' and hence behave as though an internal error or 27647 internal warning has been detected. In addition to reporting the 27648 internal problem, these functions give the user the opportunity to 27649 either quit GDB or create a core file of the current GDB session. 27650 27651 These commands take an optional parameter MESSAGE-TEXT that is 27652 used as the text of the error or warning message. 27653 27654 Here's an example of using `internal-error': 27655 27656 (gdb) maint internal-error testing, 1, 2 27657 .../maint.c:121: internal-error: testing, 1, 2 27658 A problem internal to GDB has been detected. Further 27659 debugging may prove unreliable. 27660 Quit this debugging session? (y or n) n 27661 Create a core file? (y or n) n 27662 (gdb) 27663 27664`maint set internal-error ACTION [ask|yes|no]' 27665`maint show internal-error ACTION' 27666`maint set internal-warning ACTION [ask|yes|no]' 27667`maint show internal-warning ACTION' 27668 When GDB reports an internal problem (error or warning) it gives 27669 the user the opportunity to both quit GDB and create a core file 27670 of the current GDB session. These commands let you override the 27671 default behaviour for each particular ACTION, described in the 27672 table below. 27673 27674 `quit' 27675 You can specify that GDB should always (yes) or never (no) 27676 quit. The default is to ask the user what to do. 27677 27678 `corefile' 27679 You can specify that GDB should always (yes) or never (no) 27680 create a core file. The default is to ask the user what to 27681 do. 27682 27683`maint packet TEXT' 27684 If GDB is talking to an inferior via the serial protocol, then 27685 this command sends the string TEXT to the inferior, and displays 27686 the response packet. GDB supplies the initial `$' character, the 27687 terminating `#' character, and the checksum. 27688 27689`maint print architecture [FILE]' 27690 Print the entire architecture configuration. The optional argument 27691 FILE names the file where the output goes. 27692 27693`maint print c-tdesc' 27694 Print the current target description (*note Target Descriptions::) 27695 as a C source file. The created source file can be used in GDB 27696 when an XML parser is not available to parse the description. 27697 27698`maint print dummy-frames' 27699 Prints the contents of GDB's internal dummy-frame stack. 27700 27701 (gdb) b add 27702 ... 27703 (gdb) print add(2,3) 27704 Breakpoint 2, add (a=2, b=3) at ... 27705 58 return (a + b); 27706 The program being debugged stopped while in a function called from GDB. 27707 ... 27708 (gdb) maint print dummy-frames 27709 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 27710 top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c} 27711 call_lo=0x01014000 call_hi=0x01014001 27712 (gdb) 27713 27714 Takes an optional file parameter. 27715 27716`maint print registers [FILE]' 27717`maint print raw-registers [FILE]' 27718`maint print cooked-registers [FILE]' 27719`maint print register-groups [FILE]' 27720 Print GDB's internal register data structures. 27721 27722 The command `maint print raw-registers' includes the contents of 27723 the raw register cache; the command `maint print cooked-registers' 27724 includes the (cooked) value of all registers, including registers 27725 which aren't available on the target nor visible to user; and the 27726 command `maint print register-groups' includes the groups that each 27727 register is a member of. *Note Registers: (gdbint)Registers. 27728 27729 These commands take an optional parameter, a file name to which to 27730 write the information. 27731 27732`maint print reggroups [FILE]' 27733 Print GDB's internal register group data structures. The optional 27734 argument FILE tells to what file to write the information. 27735 27736 The register groups info looks like this: 27737 27738 (gdb) maint print reggroups 27739 Group Type 27740 general user 27741 float user 27742 all user 27743 vector user 27744 system user 27745 save internal 27746 restore internal 27747 27748`flushregs' 27749 This command forces GDB to flush its internal register cache. 27750 27751`maint print objfiles' 27752 Print a dump of all known object files. For each object file, this 27753 command prints its name, address in memory, and all of its psymtabs 27754 and symtabs. 27755 27756`maint print section-scripts [REGEXP]' 27757 Print a dump of scripts specified in the `.debug_gdb_section' 27758 section. If REGEXP is specified, only print scripts loaded by 27759 object files matching REGEXP. For each script, this command 27760 prints its name as specified in the objfile, and the full path if 27761 known. *Note .debug_gdb_scripts section::. 27762 27763`maint print statistics' 27764 This command prints, for each object file in the program, various 27765 data about that object file followed by the byte cache ("bcache") 27766 statistics for the object file. The objfile data includes the 27767 number of minimal, partial, full, and stabs symbols, the number of 27768 types defined by the objfile, the number of as yet unexpanded psym 27769 tables, the number of line tables and string tables, and the 27770 amount of memory used by the various tables. The bcache 27771 statistics include the counts, sizes, and counts of duplicates of 27772 all and unique objects, max, average, and median entry size, total 27773 memory used and its overhead and savings, and various measures of 27774 the hash table size and chain lengths. 27775 27776`maint print target-stack' 27777 A "target" is an interface between the debugger and a particular 27778 kind of file or process. Targets can be stacked in "strata", so 27779 that more than one target can potentially respond to a request. 27780 In particular, memory accesses will walk down the stack of targets 27781 until they find a target that is interested in handling that 27782 particular address. 27783 27784 This command prints a short description of each layer that was 27785 pushed on the "target stack", starting from the top layer down to 27786 the bottom one. 27787 27788`maint print type EXPR' 27789 Print the type chain for a type specified by EXPR. The argument 27790 can be either a type name or a symbol. If it is a symbol, the 27791 type of that symbol is described. The type chain produced by this 27792 command is a recursive definition of the data type as stored in 27793 GDB's data structures, including its flags and contained types. 27794 27795`maint set dwarf2 always-disassemble' 27796 27797`maint show dwarf2 always-disassemble' 27798 Control the behavior of `info address' when using DWARF debugging 27799 information. 27800 27801 The default is `off', which means that GDB should try to describe 27802 a variable's location in an easily readable format. When `on', 27803 GDB will instead display the DWARF location expression in an 27804 assembly-like format. Note that some locations are too complex 27805 for GDB to describe simply; in this case you will always see the 27806 disassembly form. 27807 27808 Here is an example of the resulting disassembly: 27809 27810 (gdb) info addr argc 27811 Symbol "argc" is a complex DWARF expression: 27812 1: DW_OP_fbreg 0 27813 27814 For more information on these expressions, see the DWARF standard 27815 (http://www.dwarfstd.org/). 27816 27817`maint set dwarf2 max-cache-age' 27818`maint show dwarf2 max-cache-age' 27819 Control the DWARF 2 compilation unit cache. 27820 27821 In object files with inter-compilation-unit references, such as 27822 those produced by the GCC option `-feliminate-dwarf2-dups', the 27823 DWARF 2 reader needs to frequently refer to previously read 27824 compilation units. This setting controls how long a compilation 27825 unit will remain in the cache if it is not referenced. A higher 27826 limit means that cached compilation units will be stored in memory 27827 longer, and more total memory will be used. Setting it to zero 27828 disables caching, which will slow down GDB startup, but reduce 27829 memory consumption. 27830 27831`maint set profile' 27832`maint show profile' 27833 Control profiling of GDB. 27834 27835 Profiling will be disabled until you use the `maint set profile' 27836 command to enable it. When you enable profiling, the system will 27837 begin collecting timing and execution count data; when you disable 27838 profiling or exit GDB, the results will be written to a log file. 27839 Remember that if you use profiling, GDB will overwrite the 27840 profiling log file (often called `gmon.out'). If you have a 27841 record of important profiling data in a `gmon.out' file, be sure 27842 to move it to a safe location. 27843 27844 Configuring with `--enable-profiling' arranges for GDB to be 27845 compiled with the `-pg' compiler option. 27846 27847`maint set show-debug-regs' 27848`maint show show-debug-regs' 27849 Control whether to show variables that mirror the hardware debug 27850 registers. Use `ON' to enable, `OFF' to disable. If enabled, the 27851 debug registers values are shown when GDB inserts or removes a 27852 hardware breakpoint or watchpoint, and when the inferior triggers 27853 a hardware-assisted breakpoint or watchpoint. 27854 27855`maint set show-all-tib' 27856`maint show show-all-tib' 27857 Control whether to show all non zero areas within a 1k block 27858 starting at thread local base, when using the `info w32 27859 thread-information-block' command. 27860 27861`maint space' 27862 Control whether to display memory usage for each command. If set 27863 to a nonzero value, GDB will display how much memory each command 27864 took, following the command's own output. This can also be 27865 requested by invoking GDB with the `--statistics' command-line 27866 switch (*note Mode Options::). 27867 27868`maint time' 27869 Control whether to display the execution time for each command. If 27870 set to a nonzero value, GDB will display how much time it took to 27871 execute each command, following the command's own output. The 27872 time is not printed for the commands that run the target, since 27873 there's no mechanism currently to compute how much time was spend 27874 by GDB and how much time was spend by the program been debugged. 27875 it's not possibly currently This can also be requested by invoking 27876 GDB with the `--statistics' command-line switch (*note Mode 27877 Options::). 27878 27879`maint translate-address [SECTION] ADDR' 27880 Find the symbol stored at the location specified by the address 27881 ADDR and an optional section name SECTION. If found, GDB prints 27882 the name of the closest symbol and an offset from the symbol's 27883 location to the specified address. This is similar to the `info 27884 address' command (*note Symbols::), except that this command also 27885 allows to find symbols in other sections. 27886 27887 If section was not specified, the section in which the symbol was 27888 found is also printed. For dynamically linked executables, the 27889 name of executable or shared library containing the symbol is 27890 printed as well. 27891 27892 27893 The following command is useful for non-interactive invocations of 27894GDB, such as in the test suite. 27895 27896`set watchdog NSEC' 27897 Set the maximum number of seconds GDB will wait for the target 27898 operation to finish. If this time expires, GDB reports and error 27899 and the command is aborted. 27900 27901`show watchdog' 27902 Show the current setting of the target wait timeout. 27903 27904 27905File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top 27906 27907Appendix D GDB Remote Serial Protocol 27908************************************* 27909 27910* Menu: 27911 27912* Overview:: 27913* Standard Replies:: 27914* Packets:: 27915* Stop Reply Packets:: 27916* General Query Packets:: 27917* Architecture-Specific Protocol Details:: 27918* Tracepoint Packets:: 27919* Host I/O Packets:: 27920* Interrupts:: 27921* Notification Packets:: 27922* Remote Non-Stop:: 27923* Packet Acknowledgment:: 27924* Examples:: 27925* File-I/O Remote Protocol Extension:: 27926* Library List Format:: 27927* Memory Map Format:: 27928* Thread List Format:: 27929 27930 27931File: gdb.info, Node: Overview, Next: Standard Replies, Up: Remote Protocol 27932 27933D.1 Overview 27934============ 27935 27936There may be occasions when you need to know something about the 27937protocol--for example, if there is only one serial port to your target 27938machine, you might want your program to do something special if it 27939recognizes a packet meant for GDB. 27940 27941 In the examples below, `->' and `<-' are used to indicate 27942transmitted and received data, respectively. 27943 27944 All GDB commands and responses (other than acknowledgments and 27945notifications, see *note Notification Packets::) are sent as a PACKET. 27946A PACKET is introduced with the character `$', the actual PACKET-DATA, 27947and the terminating character `#' followed by a two-digit CHECKSUM: 27948 27949 `$'PACKET-DATA`#'CHECKSUM 27950 The two-digit CHECKSUM is computed as the modulo 256 sum of all 27951characters between the leading `$' and the trailing `#' (an eight bit 27952unsigned checksum). 27953 27954 Implementors should note that prior to GDB 5.0 the protocol 27955specification also included an optional two-digit SEQUENCE-ID: 27956 27957 `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM 27958 27959That SEQUENCE-ID was appended to the acknowledgment. GDB has never 27960output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 27961must not accept SEQUENCE-ID. 27962 27963 When either the host or the target machine receives a packet, the 27964first response expected is an acknowledgment: either `+' (to indicate 27965the package was received correctly) or `-' (to request retransmission): 27966 27967 -> `$'PACKET-DATA`#'CHECKSUM 27968 <- `+' 27969 The `+'/`-' acknowledgments can be disabled once a connection is 27970established. *Note Packet Acknowledgment::, for details. 27971 27972 The host (GDB) sends COMMANDs, and the target (the debugging stub 27973incorporated in your program) sends a RESPONSE. In the case of step 27974and continue COMMANDs, the response is only sent when the operation has 27975completed, and the target has again stopped all threads in all attached 27976processes. This is the default all-stop mode behavior, but the remote 27977protocol also supports GDB's non-stop execution mode; see *note Remote 27978Non-Stop::, for details. 27979 27980 PACKET-DATA consists of a sequence of characters with the exception 27981of `#' and `$' (see `X' packet for additional exceptions). 27982 27983 Fields within the packet should be separated using `,' `;' or `:'. 27984Except where otherwise noted all numbers are represented in HEX with 27985leading zeros suppressed. 27986 27987 Implementors should note that prior to GDB 5.0, the character `:' 27988could not appear as the third character in a packet (as it would 27989potentially conflict with the SEQUENCE-ID). 27990 27991 Binary data in most packets is encoded either as two hexadecimal 27992digits per byte of binary data. This allowed the traditional remote 27993protocol to work over connections which were only seven-bit clean. 27994Some packets designed more recently assume an eight-bit clean 27995connection, and use a more efficient encoding to send and receive 27996binary data. 27997 27998 The binary data representation uses `7d' (ASCII `}') as an escape 27999character. Any escaped byte is transmitted as the escape character 28000followed by the original character XORed with `0x20'. For example, the 28001byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The 28002bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}') 28003must always be escaped. Responses sent by the stub must also escape 28004`0x2a' (ASCII `*'), so that it is not interpreted as the start of a 28005run-length encoded sequence (described next). 28006 28007 Response DATA can be run-length encoded to save space. Run-length 28008encoding replaces runs of identical characters with one instance of the 28009repeated character, followed by a `*' and a repeat count. The repeat 28010count is itself sent encoded, to avoid binary characters in DATA: a 28011value of N is sent as `N+29'. For a repeat count greater or equal to 280123, this produces a printable ASCII character, e.g. a space (ASCII code 2801332) for a repeat count of 3. (This is because run-length encoding 28014starts to win for counts 3 or more.) Thus, for example, `0* ' is a 28015run-length encoding of "0000": the space character after `*' means 28016repeat the leading `0' `32 - 29 = 3' more times. 28017 28018 The printable characters `#' and `$' or with a numeric value greater 28019than 126 must not be used. Runs of six repeats (`#') or seven repeats 28020(`$') can be expanded using a repeat count of only five (`"'). For 28021example, `00000000' can be encoded as `0*"00'. 28022 28023 In describing packets (and responses), each description has a 28024template showing the overall syntax, followed by an explanation of the 28025packet's meaning. We include spaces in some of the templates for 28026clarity; these are not part of the packet's syntax. No GDB packet uses 28027spaces to separate its components. For example, a template like `foo 28028BAR BAZ' describes a packet beginning with the three ASCII bytes `foo', 28029followed by a BAR, followed directly by a BAZ. GDB does not transmit a 28030space character between the `foo' and the BAR, or between the BAR and 28031the BAZ. 28032 28033 We place optional portions of a packet in [square brackets]; for 28034example, a template like `c [ADDR]' describes a packet beginning with 28035the single ASCII character `c', possibly followed by an ADDR. 28036 28037 28038File: gdb.info, Node: Standard Replies, Next: Packets, Prev: Overview, Up: Remote Protocol 28039 28040D.2 Standard Replies 28041==================== 28042 28043The remote protocol specifies a few standard replies. All commands 28044support these, except as noted in the individual command descriptions. 28045 28046`' 28047 For any COMMAND not supported by the stub, an empty response 28048 (`$#00') should be returned. That way it is possible to extend the 28049 protocol. A newer GDB can tell if a packet is supported based on 28050 that response (but see also *note qSupported::). 28051 28052`E XX' 28053 An error has occurred; XX is a two-digit hexadecimal error number. 28054 In almost all cases, the protocol does not specify the meaning of 28055 the error numbers; GDB usually ignores the numbers, or displays 28056 them to the user without further interpretation. 28057 28058`E.NAME[.MESSAGE]' 28059 An error has occurred; NAME is the name of the error. The name 28060 may contain letters, numbers, and `-' characters. If present, 28061 MESSAGE is an error message, encoded using the escaped eight-bit 28062 conventions for binary data described above. 28063 28064 Except as noted, named errors may only be returned to commands 28065 documented to expect them; this ensures that older stubs can 28066 interact with newer versions of GDB, even when interpretations for 28067 named errors have been added to the protocol. 28068 28069 The protocol uses the following error names: 28070 28071 `fatal' 28072 A fatal error has occurred; the stub will be unable to 28073 interact further with GDB. Fatal errors should always 28074 include a message explaining their cause. 28075 28076 Any command may return this error. 28077 28078 `memtype' 28079 The memory addressed is of the wrong type for the given 28080 command. For example, a `vFlashWrite' command applied to 28081 non-flash memory elicits an `E.memtype' error response. 28082 28083 28084 28085File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Standard Replies, Up: Remote Protocol 28086 28087D.3 Packets 28088=========== 28089 28090The following table provides a complete list of all currently defined 28091COMMANDs and their corresponding response DATA. *Note File-I/O Remote 28092Protocol Extension::, for details about the File I/O extension of the 28093remote protocol. 28094 28095 Each packet's description has a template showing the packet's overall 28096syntax, followed by an explanation of the packet's meaning. We include 28097spaces in some of the templates for clarity; these are not part of the 28098packet's syntax. No GDB packet uses spaces to separate its components. 28099For example, a template like `foo BAR BAZ' describes a packet beginning 28100with the three ASCII bytes `foo', followed by a BAR, followed directly 28101by a BAZ. GDB does not transmit a space character between the `foo' 28102and the BAR, or between the BAR and the BAZ. 28103 28104 Several packets and replies include a THREAD-ID field to identify a 28105thread. Normally these are positive numbers with a target-specific 28106interpretation, formatted as big-endian hex strings. A THREAD-ID can 28107also be a literal `-1' to indicate all threads, or `0' to pick any 28108thread. 28109 28110 In addition, the remote protocol supports a multiprocess feature in 28111which the THREAD-ID syntax is extended to optionally include both 28112process and thread ID fields, as `pPID.TID'. The PID (process) and TID 28113(thread) components each have the format described above: a positive 28114number with target-specific interpretation formatted as a big-endian 28115hex string, literal `-1' to indicate all processes or threads 28116(respectively), or `0' to indicate an arbitrary process or thread. 28117Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It 28118is an error to specify all processes but a specific thread, such as 28119`p-1.TID'. Note that the `p' prefix is _not_ used for those packets 28120and replies explicitly documented to include a process ID, rather than 28121a THREAD-ID. 28122 28123 The multiprocess THREAD-ID syntax extensions are only used if both 28124GDB and the stub report support for the `multiprocess' feature using 28125`qSupported'. *Note multiprocess extensions::, for more information. 28126 28127 Note that all packet forms beginning with an upper- or lower-case 28128letter, other than those described here, are reserved for future use. 28129 28130 A stub is required to support the `g', `G', `m', `M', `c', and `s' 28131COMMANDs. All other COMMANDs are optional. 28132 28133 Here are the packet descriptions. 28134 28135`!' 28136 Enable extended mode. In extended mode, the remote server is made 28137 persistent. The `R' packet is used to restart the program being 28138 debugged. 28139 28140 Reply: 28141 `OK' 28142 The remote target both supports and has enabled extended mode. 28143 28144`?' 28145 Indicate the reason the target halted. The reply is the same as 28146 for step and continue. This packet has a special interpretation 28147 when the target is in non-stop mode; see *note Remote Non-Stop::. 28148 28149 Reply: *Note Stop Reply Packets::, for the reply specifications. 28150 28151`A ARGLEN,ARGNUM,ARG,...' 28152 Initialized `argv[]' array passed into program. ARGLEN specifies 28153 the number of bytes in the hex encoded byte stream ARG. See 28154 `gdbserver' for more details. 28155 28156 Reply: 28157 `OK' 28158 The arguments were set. 28159 28160`b BAUD' 28161 (Don't use this packet; its behavior is not well-defined.) Change 28162 the serial line speed to BAUD. 28163 28164 JTC: _When does the transport layer state change? When it's 28165 received, or after the ACK is transmitted. In either case, there 28166 are problems if the command or the acknowledgment packet is 28167 dropped._ 28168 28169 Stan: _If people really wanted to add something like this, and get 28170 it working for the first time, they ought to modify ser-unix.c to 28171 send some kind of out-of-band message to a specially-setup stub 28172 and have the switch happen "in between" packets, so that from 28173 remote protocol's point of view, nothing actually happened._ 28174 28175`B ADDR,MODE' 28176 Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR. 28177 28178 Don't use this packet. Use the `Z' and `z' packets instead (*note 28179 insert breakpoint or watchpoint packet::). 28180 28181`bc' 28182 Backward continue. Execute the target system in reverse. No 28183 parameter. *Note Reverse Execution::, for more information. 28184 28185 Reply: *Note Stop Reply Packets::, for the reply specifications. 28186 28187`bs' 28188 Backward single step. Execute one instruction in reverse. No 28189 parameter. *Note Reverse Execution::, for more information. 28190 28191 Reply: *Note Stop Reply Packets::, for the reply specifications. 28192 28193`c [ADDR]' 28194 Continue. ADDR is address to resume. If ADDR is omitted, resume 28195 at current address. 28196 28197 Reply: *Note Stop Reply Packets::, for the reply specifications. 28198 28199`C SIG[;ADDR]' 28200 Continue with signal SIG (hex signal number). If `;ADDR' is 28201 omitted, resume at same address. 28202 28203 Reply: *Note Stop Reply Packets::, for the reply specifications. 28204 28205`d' 28206 Toggle debug flag. 28207 28208 Don't use this packet; instead, define a general set packet (*note 28209 General Query Packets::). 28210 28211`D' 28212`D;PID' 28213 The first form of the packet is used to detach GDB from the remote 28214 system. It is sent to the remote target before GDB disconnects 28215 via the `detach' command. 28216 28217 The second form, including a process ID, is used when multiprocess 28218 protocol extensions are enabled (*note multiprocess extensions::), 28219 to detach only a specific process. The PID is specified as a 28220 big-endian hex string. 28221 28222 Reply: 28223 `OK' 28224 for success 28225 28226`F RC,EE,CF;XX' 28227 A reply from GDB to an `F' packet sent by the target. This is 28228 part of the File-I/O protocol extension. *Note File-I/O Remote 28229 Protocol Extension::, for the specification. 28230 28231`g' 28232 Read general registers. 28233 28234 Reply: 28235 `XX...' 28236 Each byte of register data is described by two hex digits. 28237 The bytes with the register are transmitted in target byte 28238 order. The size of each register and their position within 28239 the `g' packet are determined by the GDB internal gdbarch 28240 functions `DEPRECATED_REGISTER_RAW_SIZE' and 28241 `gdbarch_register_name'. The specification of several 28242 standard `g' packets is specified below. 28243 28244`G XX...' 28245 Write general registers. *Note read registers packet::, for a 28246 description of the XX... data. 28247 28248 Reply: 28249 `OK' 28250 for success 28251 28252`H C THREAD-ID' 28253 Set thread for subsequent operations (`m', `M', `g', `G', et.al.). 28254 C depends on the operation to be performed: it should be `c' for 28255 step and continue operations, `g' for other operations. The 28256 thread designator THREAD-ID has the format and interpretation 28257 described in *note thread-id syntax::. 28258 28259 Reply: 28260 `OK' 28261 for success 28262 28263`i [ADDR[,NNN]]' 28264 Step the remote target by a single clock cycle. If `,NNN' is 28265 present, cycle step NNN cycles. If ADDR is present, cycle step 28266 starting at that address. 28267 28268`I' 28269 Signal, then cycle step. *Note step with signal packet::. *Note 28270 cycle step packet::. 28271 28272`k' 28273 Kill request. 28274 28275 FIXME: _There is no description of how to operate when a specific 28276 thread context has been selected (i.e. does 'k' kill only that 28277 thread?)_. 28278 28279`m ADDR,LENGTH' 28280 Read LENGTH bytes of memory starting at address ADDR. Note that 28281 ADDR may not be aligned to any particular boundary. 28282 28283 The stub need not use any particular size or alignment when 28284 gathering data from memory for the response; even if ADDR is 28285 word-aligned and LENGTH is a multiple of the word size, the stub 28286 is free to use byte accesses, or not. For this reason, this 28287 packet may not be suitable for accessing memory-mapped I/O devices. 28288 28289 Reply: 28290 `XX...' 28291 Memory contents; each byte is transmitted as a two-digit 28292 hexadecimal number. The reply may contain fewer bytes than 28293 requested if the server was able to read only part of the 28294 region of memory. 28295 28296`M ADDR,LENGTH:XX...' 28297 Write LENGTH bytes of memory starting at address ADDR. XX... is 28298 the data; each byte is transmitted as a two-digit hexadecimal 28299 number. 28300 28301 Reply: 28302 `OK' 28303 All the data was written successfully. (If only part of the 28304 data was written, this command returns an error.) 28305 28306`p N' 28307 Read the value of register N; N is in hex. *Note read registers 28308 packet::, for a description of how the returned register value is 28309 encoded. 28310 28311 Reply: 28312 `XX...' 28313 the register's value 28314 28315`P N...=R...' 28316 Write register N... with value R.... The register number N is in 28317 hexadecimal, and R... contains two hex digits for each byte in the 28318 register (target byte order). 28319 28320 Reply: 28321 `OK' 28322 for success 28323 28324`q NAME PARAMS...' 28325`Q NAME PARAMS...' 28326 General query (`q') and set (`Q'). These packets are described 28327 fully in *note General Query Packets::. 28328 28329`r' 28330 Reset the entire system. 28331 28332 Don't use this packet; use the `R' packet instead. 28333 28334`R XX' 28335 Restart the program being debugged. XX, while needed, is ignored. 28336 This packet is only available in extended mode (*note extended 28337 mode::). 28338 28339 The `R' packet has no reply. 28340 28341`s [ADDR]' 28342 Single step. ADDR is the address at which to resume. If ADDR is 28343 omitted, resume at same address. 28344 28345 Reply: *Note Stop Reply Packets::, for the reply specifications. 28346 28347`S SIG[;ADDR]' 28348 Step with signal. This is analogous to the `C' packet, but 28349 requests a single-step, rather than a normal resumption of 28350 execution. 28351 28352 Reply: *Note Stop Reply Packets::, for the reply specifications. 28353 28354`t ADDR:PP,MM' 28355 Search backwards starting at address ADDR for a match with pattern 28356 PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 28357 digits. 28358 28359`T THREAD-ID' 28360 Find out if the thread THREAD-ID is alive. *Note thread-id 28361 syntax::. 28362 28363 Reply: 28364 `OK' 28365 thread is still alive 28366 28367 `E NN' 28368 thread is dead 28369 28370`v' 28371 Packets starting with `v' are identified by a multi-letter name, 28372 up to the first `;' or `?' (or the end of the packet). 28373 28374`vAttach;PID' 28375 Attach to a new process with the specified process ID PID. The 28376 process ID is a hexadecimal integer identifying the process. In 28377 all-stop mode, all threads in the attached process are stopped; in 28378 non-stop mode, it may be attached without being stopped if that is 28379 supported by the target. 28380 28381 This packet is only available in extended mode (*note extended 28382 mode::). 28383 28384 Reply: 28385 `E NN' 28386 for an error 28387 28388 `Any stop packet' 28389 for success in all-stop mode (*note Stop Reply Packets::) 28390 28391 `OK' 28392 for success in non-stop mode (*note Remote Non-Stop::) 28393 28394`vCont[;ACTION[:THREAD-ID]]...' 28395 Resume the inferior, specifying different actions for each thread. 28396 If an action is specified with no THREAD-ID, then it is applied to 28397 any threads that don't have a specific action specified; if no 28398 default action is specified then other threads should remain 28399 stopped in all-stop mode and in their current state in non-stop 28400 mode. Specifying multiple default actions is an error; specifying 28401 no actions is also an error. Thread IDs are specified using the 28402 syntax described in *note thread-id syntax::. 28403 28404 Currently supported actions are: 28405 28406 `c' 28407 Continue. 28408 28409 `C SIG' 28410 Continue with signal SIG. The signal SIG should be two hex 28411 digits. 28412 28413 `s' 28414 Step. 28415 28416 `S SIG' 28417 Step with signal SIG. The signal SIG should be two hex 28418 digits. 28419 28420 `t' 28421 Stop. 28422 28423 The optional argument ADDR normally associated with the `c', `C', 28424 `s', and `S' packets is not supported in `vCont'. 28425 28426 The `t' action is only relevant in non-stop mode (*note Remote 28427 Non-Stop::) and may be ignored by the stub otherwise. A stop 28428 reply should be generated for any affected thread not already 28429 stopped. When a thread is stopped by means of a `t' action, the 28430 corresponding stop reply should indicate that the thread has 28431 stopped with signal `0', regardless of whether the target uses 28432 some other signal as an implementation detail. 28433 28434 Reply: *Note Stop Reply Packets::, for the reply specifications. 28435 28436`vCont?' 28437 Request a list of actions supported by the `vCont' packet. 28438 28439 Reply: 28440 `vCont[;ACTION...]' 28441 The `vCont' packet is supported. Each ACTION is a supported 28442 command in the `vCont' packet. 28443 28444 `' 28445 The `vCont' packet is not supported. 28446 28447`vFile:OPERATION:PARAMETER...' 28448 Perform a file operation on the target system. For details, see 28449 *note Host I/O Packets::. 28450 28451`vFlashErase:ADDR,LENGTH' 28452 Direct the stub to erase LENGTH bytes of flash starting at ADDR. 28453 The region may enclose any number of flash blocks, but its start 28454 and end must fall on block boundaries, as indicated by the flash 28455 block size appearing in the memory map (*note Memory Map 28456 Format::). GDB groups flash memory programming operations 28457 together, and sends a `vFlashDone' request after each group; the 28458 stub is allowed to delay erase operation until the `vFlashDone' 28459 packet is received. 28460 28461 The stub must support `vCont' if it reports support for 28462 multiprocess extensions (*note multiprocess extensions::). Note 28463 that in this case `vCont' actions can be specified to apply to all 28464 threads in a process by using the `pPID.-1' form of the THREAD-ID. 28465 28466 Reply: 28467 `OK' 28468 for success 28469 28470 `E.memtype' 28471 for vFlashErase addressing non-flash memory 28472 28473`vFlashWrite:ADDR:XX...' 28474 Direct the stub to write data to flash address ADDR. The data is 28475 passed in binary form using the same encoding as for the `X' 28476 packet (*note Binary Data::). The memory ranges specified by 28477 `vFlashWrite' packets preceding a `vFlashDone' packet must not 28478 overlap, and must appear in order of increasing addresses 28479 (although `vFlashErase' packets for higher addresses may already 28480 have been received; the ordering is guaranteed only between 28481 `vFlashWrite' packets). If a packet writes to an address that was 28482 neither erased by a preceding `vFlashErase' packet nor by some 28483 other target-specific method, the results are unpredictable. 28484 28485 Reply: 28486 `OK' 28487 for success 28488 28489 `E.memtype' 28490 for vFlashWrite addressing non-flash memory 28491 28492`vFlashDone' 28493 Indicate to the stub that flash programming operation is finished. 28494 The stub is permitted to delay or batch the effects of a group of 28495 `vFlashErase' and `vFlashWrite' packets until a `vFlashDone' 28496 packet is received. The contents of the affected regions of flash 28497 memory are unpredictable until the `vFlashDone' request is 28498 completed. 28499 28500`vKill;PID' 28501 Kill the process with the specified process ID. PID is a 28502 hexadecimal integer identifying the process. This packet is used 28503 in preference to `k' when multiprocess protocol extensions are 28504 supported; see *note multiprocess extensions::. 28505 28506 Reply: 28507 `E NN' 28508 for an error 28509 28510 `OK' 28511 for success 28512 28513`vRun;FILENAME[;ARGUMENT]...' 28514 Run the program FILENAME, passing it each ARGUMENT on its command 28515 line. The file and arguments are hex-encoded strings. If 28516 FILENAME is an empty string, the stub may use a default program 28517 (e.g. the last program run). The program is created in the stopped 28518 state. 28519 28520 This packet is only available in extended mode (*note extended 28521 mode::). 28522 28523 Reply: 28524 `E NN' 28525 for an error 28526 28527 `Any stop packet' 28528 for success (*note Stop Reply Packets::) 28529 28530`vStopped' 28531 In non-stop mode (*note Remote Non-Stop::), acknowledge a previous 28532 stop reply and prompt for the stub to report another one. 28533 28534 Reply: 28535 `Any stop packet' 28536 if there is another unreported stop event (*note Stop Reply 28537 Packets::) 28538 28539 `OK' 28540 if there are no unreported stop events 28541 28542`X ADDR,LENGTH:XX...' 28543 Write data to memory, where the data is transmitted in binary. 28544 ADDR is address, LENGTH is number of bytes, `XX...' is binary data 28545 (*note Binary Data::). 28546 28547 Reply: 28548 `OK' 28549 for success 28550 28551`z TYPE,ADDR,KIND' 28552`Z TYPE,ADDR,KIND' 28553 Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint 28554 starting at address ADDRESS of kind KIND. 28555 28556 Each breakpoint and watchpoint packet TYPE is documented 28557 separately. 28558 28559 _Implementation notes: A remote target shall return an empty string 28560 for an unrecognized breakpoint or watchpoint packet TYPE. A 28561 remote target shall support either both or neither of a given 28562 `ZTYPE...' and `zTYPE...' packet pair. To avoid potential 28563 problems with duplicate packets, the operations should be 28564 implemented in an idempotent way._ 28565 28566`z0,ADDR,KIND' 28567`Z0,ADDR,KIND' 28568 Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR 28569 of type KIND. 28570 28571 A memory breakpoint is implemented by replacing the instruction at 28572 ADDR with a software breakpoint or trap instruction. The KIND is 28573 target-specific and typically indicates the size of the breakpoint 28574 in bytes that should be inserted. E.g., the ARM and MIPS can 28575 insert either a 2 or 4 byte breakpoint. Some architectures have 28576 additional meanings for KIND; see *note Architecture-Specific 28577 Protocol Details::. 28578 28579 _Implementation note: It is possible for a target to copy or move 28580 code that contains memory breakpoints (e.g., when implementing 28581 overlays). The behavior of this packet, in the presence of such a 28582 target, is not defined._ 28583 28584 Reply: 28585 `OK' 28586 success 28587 28588`z1,ADDR,KIND' 28589`Z1,ADDR,KIND' 28590 Insert (`Z1') or remove (`z1') a hardware breakpoint at address 28591 ADDR. 28592 28593 A hardware breakpoint is implemented using a mechanism that is not 28594 dependant on being able to modify the target's memory. KIND has 28595 the same meaning as in `Z0' packets. 28596 28597 _Implementation note: A hardware breakpoint is not affected by code 28598 movement._ 28599 28600 Reply: 28601 `OK' 28602 success 28603 28604`z2,ADDR,KIND' 28605`Z2,ADDR,KIND' 28606 Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND 28607 is interpreted as the number of bytes to watch. 28608 28609 Reply: 28610 `OK' 28611 success 28612 28613`z3,ADDR,KIND' 28614`Z3,ADDR,KIND' 28615 Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is 28616 interpreted as the number of bytes to watch. 28617 28618 Reply: 28619 `OK' 28620 success 28621 28622`z4,ADDR,KIND' 28623`Z4,ADDR,KIND' 28624 Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND 28625 is interpreted as the number of bytes to watch. 28626 28627 Reply: 28628 `OK' 28629 success 28630 28631 28632 Error responses use one of the following formats: 28633 28634`ENN' 28635 28636`E.TEXT' 28637 28638`ENN :TEXT' 28639 28640 Error numbers are not well defined, any non-zero error number can be 28641used to indicate an error. NN is a 2 character hex encoded value. The 28642TEXT string may provide additional information about the error. 28643 28644 28645File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol 28646 28647D.4 Stop Reply Packets 28648====================== 28649 28650The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?' 28651packets can receive any of the below as a reply. Except for `?' and 28652`vStopped', that reply is only returned when the target halts. In the 28653below the exact meaning of "signal number" is defined by the header 28654`include/gdb/signals.h' in the GDB source code. 28655 28656 As in the description of request packets, we include spaces in the 28657reply templates for clarity; these are not part of the reply packet's 28658syntax. No GDB stop reply packet uses spaces to separate its 28659components. 28660 28661`S AA' 28662 The program received signal number AA (a two-digit hexadecimal 28663 number). This is equivalent to a `T' response with no N:R pairs. 28664 28665`T AA N1:R1;N2:R2;...' 28666 The program received signal number AA (a two-digit hexadecimal 28667 number). This is equivalent to an `S' response, except that the 28668 `N:R' pairs can carry values of important registers and other 28669 information directly in the stop reply packet, reducing round-trip 28670 latency. Single-step and breakpoint traps are reported this way. 28671 Each `N:R' pair is interpreted as follows: 28672 28673 * If N is a hexadecimal number, it is a register number, and the 28674 corresponding R gives that register's value. R is a series 28675 of bytes in target byte order, with each byte given by a 28676 two-digit hex number. 28677 28678 * If N is `thread', then R is the THREAD-ID of the stopped 28679 thread, as specified in *note thread-id syntax::. 28680 28681 * If N is `core', then R is the hexadecimal number of the core 28682 on which the stop event was detected. 28683 28684 * If N is a recognized "stop reason", it describes a more 28685 specific event that stopped the target. The currently 28686 defined stop reasons are listed below. AA should be `05', 28687 the trap signal. At most one stop reason should be present. 28688 28689 * Otherwise, GDB should ignore this `N:R' pair and go on to the 28690 next; this allows us to extend the protocol in the future. 28691 28692 The currently defined stop reasons are: 28693 28694 `watch' 28695 `rwatch' 28696 `awatch' 28697 The packet indicates a watchpoint hit, and R is the data 28698 address, in hex. 28699 28700 `library' 28701 The packet indicates that the loaded libraries have changed. 28702 GDB should use `qXfer:libraries:read' to fetch a new list of 28703 loaded libraries. R is ignored. 28704 28705 `replaylog' 28706 The packet indicates that the target cannot continue replaying 28707 logged execution events, because it has reached the end (or 28708 the beginning when executing backward) of the log. The value 28709 of R will be either `begin' or `end'. *Note Reverse 28710 Execution::, for more information. 28711 28712`W AA' 28713`W AA ; process:PID' 28714 The process exited, and AA is the exit status. This is only 28715 applicable to certain targets. 28716 28717 The second form of the response, including the process ID of the 28718 exited process, can be used only when GDB has reported support for 28719 multiprocess protocol extensions; see *note multiprocess 28720 extensions::. The PID is formatted as a big-endian hex string. 28721 28722`X AA' 28723`X AA ; process:PID' 28724 The process terminated with signal AA. 28725 28726 The second form of the response, including the process ID of the 28727 terminated process, can be used only when GDB has reported support 28728 for multiprocess protocol extensions; see *note multiprocess 28729 extensions::. The PID is formatted as a big-endian hex string. 28730 28731`O XX...' 28732 `XX...' is hex encoding of ASCII data, to be written as the 28733 program's console output. This can happen at any time while the 28734 program is running and the debugger should continue to wait for 28735 `W', `T', etc. This reply is not permitted in non-stop mode. 28736 28737`F CALL-ID,PARAMETER...' 28738 CALL-ID is the identifier which says which host system call should 28739 be called. This is just the name of the function. Translation 28740 into the correct system call is only applicable as it's defined in 28741 GDB. *Note File-I/O Remote Protocol Extension::, for a list of 28742 implemented system calls. 28743 28744 `PARAMETER...' is a list of parameters as defined for this very 28745 system call. 28746 28747 The target replies with this packet when it expects GDB to call a 28748 host system call on behalf of the target. GDB replies with an 28749 appropriate `F' packet and keeps up waiting for the next reply 28750 packet from the target. The latest `C', `c', `S' or `s' action is 28751 expected to be continued. *Note File-I/O Remote Protocol 28752 Extension::, for more details. 28753 28754 28755 28756File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol 28757 28758D.5 General Query Packets 28759========================= 28760 28761Packets starting with `q' are "general query packets"; packets starting 28762with `Q' are "general set packets". General query and set packets are 28763a semi-unified form for retrieving and sending information to and from 28764the stub. 28765 28766 The initial letter of a query or set packet is followed by a name 28767indicating what sort of thing the packet applies to. For example, GDB 28768may use a `qSymbol' packet to exchange symbol definitions with the 28769stub. These packet names follow some conventions: 28770 28771 * The name must not contain commas, colons or semicolons. 28772 28773 * Most GDB query and set packets have a leading upper case letter. 28774 28775 * The names of custom vendor packets should use a company prefix, in 28776 lower case, followed by a period. For example, packets designed at 28777 the Acme Corporation might begin with `qacme.foo' (for querying 28778 foos) or `Qacme.bar' (for setting bars). 28779 28780 The name of a query or set packet should be separated from any 28781parameters by a `:'; the parameters themselves should be separated by 28782`,' or `;'. Stubs must be careful to match the full packet name, and 28783check for a separator or the end of the packet, in case two packet 28784names share a common prefix. New packets should not begin with `qC', 28785`qP', or `qL'(1). 28786 28787 Like the descriptions of the other packets, each description here 28788has a template showing the packet's overall syntax, followed by an 28789explanation of the packet's meaning. We include spaces in some of the 28790templates for clarity; these are not part of the packet's syntax. No 28791GDB packet uses spaces to separate its components. 28792 28793 Here are the currently defined query and set packets: 28794 28795`qAuth:USERNAME,PASSWORD' 28796 Request permission to debug the target. The USERNAME and PASSWORD 28797 are the values from `set remote username' and `set remote 28798 password', both encoded as hex strings. If the target accepts the 28799 username and password, then it replies with `OK'; otherwise it 28800 replies with an error and may disconnect on its own. If the 28801 target requires a login (`MustAuth' feature), then if this packet 28802 is not supplied soon after connection, then the target may choose 28803 to return errors to all packets and/or disconnect. 28804 28805`QAllow:OP:VAL...' 28806 Specify which operations GDB expects to request of the target, as 28807 a semicolon-separated list of operation name and value pairs. 28808 Possible values for OP include `WriteReg', `WriteMem', 28809 `InsertBreak', `InsertTrace', `InsertFastTrace', and `Stop'. VAL 28810 is either 0, indicating that GDB will not request the operation, 28811 or 1, indicating that it may. (The target can then use this to 28812 set up its own internals optimally, for instance if the debugger 28813 never expects to insert breakpoints, it may not need to install 28814 its own trap handler.) 28815 28816`qC' 28817 Return the current thread ID. 28818 28819 Reply: 28820 `QC THREAD-ID' 28821 Where THREAD-ID is a thread ID as documented in *note 28822 thread-id syntax::. 28823 28824 `(anything else)' 28825 Any other reply implies the old thread ID. 28826 28827`qCRC:ADDR,LENGTH' 28828 Compute the CRC checksum of a block of memory using CRC-32 defined 28829 in IEEE 802.3. The CRC is computed byte at a time, taking the most 28830 significant bit of each byte first. The initial pattern code 28831 `0xffffffff' is used to ensure leading zeros affect the CRC. 28832 28833 _Note:_ This is the same CRC used in validating separate debug 28834 files (*note Debugging Information in Separate Files: Separate 28835 Debug Files.). However the algorithm is slightly different. When 28836 validating separate debug files, the CRC is computed taking the 28837 _least_ significant bit of each byte first, and the final result 28838 is inverted to detect trailing zeros. 28839 28840 Reply: 28841 `C CRC32' 28842 The specified memory region's checksum is CRC32. 28843 28844`qfThreadInfo' 28845`qsThreadInfo' 28846 Obtain a list of all active thread IDs from the target (OS). 28847 Since there may be too many active threads to fit into one reply 28848 packet, this query works iteratively: it may require more than one 28849 query/reply sequence to obtain the entire list of threads. The 28850 first query of the sequence will be the `qfThreadInfo' query; 28851 subsequent queries in the sequence will be the `qsThreadInfo' 28852 query. 28853 28854 NOTE: This packet replaces the `qL' query (see below). 28855 28856 Reply: 28857 `m THREAD-ID' 28858 A single thread ID 28859 28860 `m THREAD-ID,THREAD-ID...' 28861 a comma-separated list of thread IDs 28862 28863 `l' 28864 (lower case letter `L') denotes end of list. 28865 28866 In response to each query, the target will reply with a list of 28867 one or more thread IDs, separated by commas. GDB will respond to 28868 each reply with a request for more thread ids (using the `qs' form 28869 of the query), until the target responds with `l' (lower-case ell, 28870 for "last"). Refer to *note thread-id syntax::, for the format of 28871 the THREAD-ID fields. 28872 28873`qGetTLSAddr:THREAD-ID,OFFSET,LM' 28874 Fetch the address associated with thread local storage specified 28875 by THREAD-ID, OFFSET, and LM. 28876 28877 THREAD-ID is the thread ID associated with the thread for which to 28878 fetch the TLS address. *Note thread-id syntax::. 28879 28880 OFFSET is the (big endian, hex encoded) offset associated with the 28881 thread local variable. (This offset is obtained from the debug 28882 information associated with the variable.) 28883 28884 LM is the (big endian, hex encoded) OS/ABI-specific encoding of the 28885 the load module associated with the thread local storage. For 28886 example, a GNU/Linux system will pass the link map address of the 28887 shared object associated with the thread local storage under 28888 consideration. Other operating environments may choose to 28889 represent the load module differently, so the precise meaning of 28890 this parameter will vary. 28891 28892 Reply: 28893 `XX...' 28894 Hex encoded (big endian) bytes representing the address of 28895 the thread local storage requested. 28896 28897`qGetTIBAddr:THREAD-ID' 28898 Fetch address of the Windows OS specific Thread Information Block. 28899 28900 THREAD-ID is the thread ID associated with the thread. 28901 28902 Reply: 28903 `XX...' 28904 Hex encoded (big endian) bytes representing the linear 28905 address of the thread information block. 28906 28907 `E NN' 28908 An error occured. This means that either the thread was not 28909 found, or the address could not be retrieved. 28910 28911 `' 28912 An empty reply indicates that `qGetTIBAddr' is not supported 28913 by the stub. 28914 28915`qL STARTFLAG THREADCOUNT NEXTTHREAD' 28916 Obtain thread information from RTOS. Where: STARTFLAG (one hex 28917 digit) is one to indicate the first query and zero to indicate a 28918 subsequent query; THREADCOUNT (two hex digits) is the maximum 28919 number of threads the response packet can contain; and NEXTTHREAD 28920 (eight hex digits), for subsequent queries (STARTFLAG is zero), is 28921 returned in the response as ARGTHREAD. 28922 28923 Don't use this packet; use the `qfThreadInfo' query instead (see 28924 above). 28925 28926 Reply: 28927 `qM COUNT DONE ARGTHREAD THREAD...' 28928 Where: COUNT (two hex digits) is the number of threads being 28929 returned; DONE (one hex digit) is zero to indicate more 28930 threads and one indicates no further threads; ARGTHREADID 28931 (eight hex digits) is NEXTTHREAD from the request packet; 28932 THREAD... is a sequence of thread IDs from the target. 28933 THREADID (eight hex digits). See 28934 `remote.c:parse_threadlist_response()'. 28935 28936`qOffsets' 28937 Get section offsets that the target used when relocating the 28938 downloaded image. 28939 28940 Reply: 28941 `Text=XXX;Data=YYY[;Bss=ZZZ]' 28942 Relocate the `Text' section by XXX from its original address. 28943 Relocate the `Data' section by YYY from its original address. 28944 If the object file format provides segment information (e.g. 28945 ELF `PT_LOAD' program headers), GDB will relocate entire 28946 segments by the supplied offsets. 28947 28948 _Note: while a `Bss' offset may be included in the response, 28949 GDB ignores this and instead applies the `Data' offset to the 28950 `Bss' section._ 28951 28952 `TextSeg=XXX[;DataSeg=YYY]' 28953 Relocate the first segment of the object file, which 28954 conventionally contains program code, to a starting address 28955 of XXX. If `DataSeg' is specified, relocate the second 28956 segment, which conventionally contains modifiable data, to a 28957 starting address of YYY. GDB will report an error if the 28958 object file does not contain segment information, or does not 28959 contain at least as many segments as mentioned in the reply. 28960 Extra segments are kept at fixed offsets relative to the last 28961 relocated segment. 28962 28963`qP MODE THREAD-ID' 28964 Returns information on THREAD-ID. Where: MODE is a hex encoded 32 28965 bit mode; THREAD-ID is a thread ID (*note thread-id syntax::). 28966 28967 Don't use this packet; use the `qThreadExtraInfo' query instead 28968 (see below). 28969 28970 Reply: see `remote.c:remote_unpack_thread_info_response()'. 28971 28972`QNonStop:1' 28973 28974`QNonStop:0' 28975 Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode. 28976 *Note Remote Non-Stop::, for more information. 28977 28978 Reply: 28979 `OK' 28980 The request succeeded. 28981 28982 `E NN' 28983 An error occurred. NN are hex digits. 28984 28985 `' 28986 An empty reply indicates that `QNonStop' is not supported by 28987 the stub. 28988 28989 This packet is not probed by default; the remote stub must request 28990 it, by supplying an appropriate `qSupported' response (*note 28991 qSupported::). Use of this packet is controlled by the `set 28992 non-stop' command; *note Non-Stop Mode::. 28993 28994`QPassSignals: SIGNAL [;SIGNAL]...' 28995 Each listed SIGNAL should be passed directly to the inferior 28996 process. Signals are numbered identically to continue packets and 28997 stop replies (*note Stop Reply Packets::). Each SIGNAL list item 28998 should be strictly greater than the previous item. These signals 28999 do not need to stop the inferior, or be reported to GDB. All 29000 other signals should be reported to GDB. Multiple `QPassSignals' 29001 packets do not combine; any earlier `QPassSignals' list is 29002 completely replaced by the new list. This packet improves 29003 performance when using `handle SIGNAL nostop noprint pass'. 29004 29005 Reply: 29006 `OK' 29007 The request succeeded. 29008 29009 Use of this packet is controlled by the `set remote pass-signals' 29010 command (*note set remote pass-signals: Remote Configuration.). 29011 This packet is not probed by default; the remote stub must request 29012 it, by supplying an appropriate `qSupported' response (*note 29013 qSupported::). 29014 29015`qRcmd,COMMAND' 29016 COMMAND (hex encoded) is passed to the local interpreter for 29017 execution. Invalid commands should be reported using the output 29018 string. Before the final result packet, the target may also 29019 respond with a number of intermediate `OOUTPUT' console output 29020 packets. _Implementors should note that providing access to a 29021 stubs's interpreter may have security implications_. 29022 29023 Reply: 29024 `OK' 29025 A command response with no output. 29026 29027 `OUTPUT' 29028 A command response with the hex encoded output string OUTPUT. 29029 29030 (Note that the `qRcmd' packet's name is separated from the command 29031 by a `,', not a `:', contrary to the naming conventions above. 29032 Please don't use this packet as a model for new packets.) 29033 29034`qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN' 29035 Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and 29036 LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes, 29037 hex encoded. 29038 29039 Reply: 29040 `0' 29041 The pattern was not found. 29042 29043 `1,address' 29044 The pattern was found at ADDRESS. 29045 29046 `E NN' 29047 A badly formed request or an error was encountered while 29048 searching memory. 29049 29050 `' 29051 An empty reply indicates that `qSearch:memory' is not 29052 recognized. 29053 29054`QStartNoAckMode' 29055 Request that the remote stub disable the normal `+'/`-' protocol 29056 acknowledgments (*note Packet Acknowledgment::). 29057 29058 Reply: 29059 `OK' 29060 The stub has switched to no-acknowledgment mode. GDB 29061 acknowledges this reponse, but neither the stub nor GDB shall 29062 send or expect further `+'/`-' acknowledgments in the current 29063 connection. 29064 29065 `' 29066 An empty reply indicates that the stub does not support 29067 no-acknowledgment mode. 29068 29069`qSupported [:GDBFEATURE [;GDBFEATURE]... ]' 29070 Tell the remote stub about features supported by GDB, and query 29071 the stub for features it supports. This packet allows GDB and the 29072 remote stub to take advantage of each others' features. 29073 `qSupported' also consolidates multiple feature probes at startup, 29074 to improve GDB performance--a single larger packet performs better 29075 than multiple smaller probe packets on high-latency links. Some 29076 features may enable behavior which must not be on by default, e.g. 29077 because it would confuse older clients or stubs. Other features 29078 may describe packets which could be automatically probed for, but 29079 are not. These features must be reported before GDB will use 29080 them. This "default unsupported" behavior is not appropriate for 29081 all packets, but it helps to keep the initial connection time 29082 under control with new versions of GDB which support increasing 29083 numbers of packets. 29084 29085 Reply: 29086 `STUBFEATURE [;STUBFEATURE]...' 29087 The stub supports or does not support each returned 29088 STUBFEATURE, depending on the form of each STUBFEATURE (see 29089 below for the possible forms). 29090 29091 The allowed forms for each feature (either a GDBFEATURE in the 29092 `qSupported' packet, or a STUBFEATURE in the response) are: 29093 29094 `NAME=VALUE' 29095 The remote protocol feature NAME is supported, and associated 29096 with the specified VALUE. The format of VALUE depends on the 29097 feature, but it must not include a semicolon. 29098 29099 `NAME+' 29100 The remote protocol feature NAME is supported, and does not 29101 need an associated value. 29102 29103 `NAME-' 29104 The remote protocol feature NAME is not supported. 29105 29106 `NAME?' 29107 The remote protocol feature NAME may be supported, and GDB 29108 should auto-detect support in some other way when it is 29109 needed. This form will not be used for GDBFEATURE 29110 notifications, but may be used for STUBFEATURE responses. 29111 29112 Whenever the stub receives a `qSupported' request, the supplied 29113 set of GDB features should override any previous request. This 29114 allows GDB to put the stub in a known state, even if the stub had 29115 previously been communicating with a different version of GDB. 29116 29117 The following values of GDBFEATURE (for the packet sent by GDB) 29118 are defined: 29119 29120 `multiprocess' 29121 This feature indicates whether GDB supports multiprocess 29122 extensions to the remote protocol. GDB does not use such 29123 extensions unless the stub also reports that it supports them 29124 by including `multiprocess+' in its `qSupported' reply. 29125 *Note multiprocess extensions::, for details. 29126 29127 `xmlRegisters' 29128 This feature indicates that GDB supports the XML target 29129 description. If the stub sees `xmlRegisters=' with target 29130 specific strings separated by a comma, it will report register 29131 description. 29132 29133 `qRelocInsn' 29134 This feature indicates whether GDB supports the `qRelocInsn' 29135 packet (*note Relocate instruction reply packet: Tracepoint 29136 Packets.). 29137 29138 Stubs should ignore any unknown values for GDBFEATURE. Any GDB 29139 which sends a `qSupported' packet supports receiving packets of 29140 unlimited length (earlier versions of GDB may reject overly long 29141 responses). Additional values for GDBFEATURE may be defined in 29142 the future to let the stub take advantage of new features in GDB, 29143 e.g. incompatible improvements in the remote protocol--the 29144 `multiprocess' feature is an example of such a feature. The 29145 stub's reply should be independent of the GDBFEATURE entries sent 29146 by GDB; first GDB describes all the features it supports, and then 29147 the stub replies with all the features it supports. 29148 29149 Similarly, GDB will silently ignore unrecognized stub feature 29150 responses, as long as each response uses one of the standard forms. 29151 29152 Some features are flags. A stub which supports a flag feature 29153 should respond with a `+' form response. Other features require 29154 values, and the stub should respond with an `=' form response. 29155 29156 Each feature has a default value, which GDB will use if 29157 `qSupported' is not available or if the feature is not mentioned 29158 in the `qSupported' response. The default values are fixed; a 29159 stub is free to omit any feature responses that match the defaults. 29160 29161 Not all features can be probed, but for those which can, the 29162 probing mechanism is useful: in some cases, a stub's internal 29163 architecture may not allow the protocol layer to know some 29164 information about the underlying target in advance. This is 29165 especially common in stubs which may be configured for multiple 29166 targets. 29167 29168 These are the currently defined stub features and their properties: 29169 29170 Feature Name Value Default Probe Allowed 29171 Required 29172 `PacketSize' Yes `-' No 29173 `qXfer:auxv:read' No `-' Yes 29174 `qXfer:features:read' No `-' Yes 29175 `qXfer:libraries:read' No `-' Yes 29176 `qXfer:memory-map:read' No `-' Yes 29177 `qXfer:sdata:read' No `-' Yes 29178 `qXfer:spu:read' No `-' Yes 29179 `qXfer:spu:write' No `-' Yes 29180 `qXfer:siginfo:read' No `-' Yes 29181 `qXfer:siginfo:write' No `-' Yes 29182 `qXfer:threads:read' No `-' Yes 29183 `QNonStop' No `-' Yes 29184 `QPassSignals' No `-' Yes 29185 `QStartNoAckMode' No `-' Yes 29186 `multiprocess' No `-' No 29187 `MustAuth' No `-' No 29188 `ConditionalTracepoints'No `-' No 29189 `ReverseContinue' No `-' No 29190 `ReverseStep' No `-' No 29191 `TracepointSource' No `-' No 29192 `QAllow' No `-' No 29193 29194 These are the currently defined stub features, in more detail: 29195 29196 `PacketSize=BYTES' 29197 The remote stub can accept packets up to at least BYTES in 29198 length. GDB will send packets up to this size for bulk 29199 transfers, and will never send larger packets. This is a 29200 limit on the data characters in the packet, including the 29201 frame and checksum. There is no trailing NUL byte in a 29202 remote protocol packet; if the stub stores packets in a 29203 NUL-terminated format, it should allow an extra byte in its 29204 buffer for the NUL. If this stub feature is not supported, 29205 GDB guesses based on the size of the `g' packet response. 29206 29207 `qXfer:auxv:read' 29208 The remote stub understands the `qXfer:auxv:read' packet 29209 (*note qXfer auxiliary vector read::). 29210 29211 `qXfer:features:read' 29212 The remote stub understands the `qXfer:features:read' packet 29213 (*note qXfer target description read::). 29214 29215 `qXfer:libraries:read' 29216 The remote stub understands the `qXfer:libraries:read' packet 29217 (*note qXfer library list read::). 29218 29219 `qXfer:memory-map:read' 29220 The remote stub understands the `qXfer:memory-map:read' packet 29221 (*note qXfer memory map read::). 29222 29223 `qXfer:sdata:read' 29224 The remote stub understands the `qXfer:sdata:read' packet 29225 (*note qXfer sdata read::). 29226 29227 `qXfer:spu:read' 29228 The remote stub understands the `qXfer:spu:read' packet 29229 (*note qXfer spu read::). 29230 29231 `qXfer:spu:write' 29232 The remote stub understands the `qXfer:spu:write' packet 29233 (*note qXfer spu write::). 29234 29235 `qXfer:siginfo:read' 29236 The remote stub understands the `qXfer:siginfo:read' packet 29237 (*note qXfer siginfo read::). 29238 29239 `qXfer:siginfo:write' 29240 The remote stub understands the `qXfer:siginfo:write' packet 29241 (*note qXfer siginfo write::). 29242 29243 `qXfer:threads:read' 29244 The remote stub understands the `qXfer:threads:read' packet 29245 (*note qXfer threads read::). 29246 29247 `QNonStop' 29248 The remote stub understands the `QNonStop' packet (*note 29249 QNonStop::). 29250 29251 `QPassSignals' 29252 The remote stub understands the `QPassSignals' packet (*note 29253 QPassSignals::). 29254 29255 `QStartNoAckMode' 29256 The remote stub understands the `QStartNoAckMode' packet and 29257 prefers to operate in no-acknowledgment mode. *Note Packet 29258 Acknowledgment::. 29259 29260 `multiprocess' 29261 The remote stub understands the multiprocess extensions to 29262 the remote protocol syntax. The multiprocess extensions 29263 affect the syntax of thread IDs in both packets and replies 29264 (*note thread-id syntax::), and add process IDs to the `D' 29265 packet and `W' and `X' replies. Note that reporting this 29266 feature indicates support for the syntactic extensions only, 29267 not that the stub necessarily supports debugging of more than 29268 one process at a time. The stub must not use multiprocess 29269 extensions in packet replies unless GDB has also indicated it 29270 supports them in its `qSupported' request. 29271 29272 `MustAuth' 29273 GDB must send an authentication packet `qAuth' and the 29274 username/password pair must be accepted, otherwise the target 29275 will return an error and disconnect. 29276 29277 `qXfer:osdata:read' 29278 The remote stub understands the `qXfer:osdata:read' packet 29279 ((*note qXfer osdata read::). 29280 29281 `ConditionalTracepoints' 29282 The remote stub accepts and implements conditional 29283 expressions defined for tracepoints (*note Tracepoint 29284 Conditions::). 29285 29286 `ReverseContinue' 29287 The remote stub accepts and implements the reverse continue 29288 packet (*note bc::). 29289 29290 `ReverseStep' 29291 The remote stub accepts and implements the reverse step packet 29292 (*note bs::). 29293 29294 `TracepointSource' 29295 The remote stub understands the `QTDPsrc' packet that supplies 29296 the source form of tracepoint definitions. 29297 29298 `QAllow' 29299 The remote stub understands the `QAllow' packet. 29300 29301 `StaticTracepoint' 29302 The remote stub supports static tracepoints. 29303 29304 29305`qSymbol::' 29306 Notify the target that GDB is prepared to serve symbol lookup 29307 requests. Accept requests from the target for the values of 29308 symbols. 29309 29310 Reply: 29311 `OK' 29312 The target does not need to look up any (more) symbols. 29313 29314 `qSymbol:SYM_NAME' 29315 The target requests the value of symbol SYM_NAME (hex 29316 encoded). GDB may provide the value by using the 29317 `qSymbol:SYM_VALUE:SYM_NAME' message, described below. 29318 29319`qSymbol:SYM_VALUE:SYM_NAME' 29320 Set the value of SYM_NAME to SYM_VALUE. 29321 29322 SYM_NAME (hex encoded) is the name of a symbol whose value the 29323 target has previously requested. 29324 29325 SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot 29326 supply a value for SYM_NAME, then this field will be empty. 29327 29328 Reply: 29329 `OK' 29330 The target does not need to look up any (more) symbols. 29331 29332 `qSymbol:SYM_NAME' 29333 The target requests the value of a new symbol SYM_NAME (hex 29334 encoded). GDB will continue to supply the values of symbols 29335 (if available), until the target ceases to request them. 29336 29337`qTBuffer' 29338 29339`QTBuffer' 29340 29341`QTDisconnected' 29342`QTDP' 29343`QTDPsrc' 29344`QTDV' 29345`qTfP' 29346`qTfV' 29347`QTFrame' 29348 *Note Tracepoint Packets::. 29349 29350`qThreadExtraInfo,THREAD-ID' 29351 Obtain a printable string description of a thread's attributes from 29352 the target OS. THREAD-ID is a thread ID; see *note thread-id 29353 syntax::. This string may contain anything that the target OS 29354 thinks is interesting for GDB to tell the user about the thread. 29355 The string is displayed in GDB's `info threads' display. Some 29356 examples of possible thread extra info strings are `Runnable', or 29357 `Blocked on Mutex'. 29358 29359 Reply: 29360 `XX...' 29361 Where `XX...' is a hex encoding of ASCII data, comprising the 29362 printable string containing the extra information about the 29363 thread's attributes. 29364 29365 (Note that the `qThreadExtraInfo' packet's name is separated from 29366 the command by a `,', not a `:', contrary to the naming 29367 conventions above. Please don't use this packet as a model for new 29368 packets.) 29369 29370`QTSave' 29371 29372`qTsP' 29373 29374`qTsV' 29375`QTStart' 29376`QTStop' 29377`QTinit' 29378`QTro' 29379`qTStatus' 29380`qTV' 29381`qTfSTM' 29382`qTsSTM' 29383`qTSTMat' 29384 *Note Tracepoint Packets::. 29385 29386`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH' 29387 Read uninterpreted bytes from the target's special data area 29388 identified by the keyword OBJECT. Request LENGTH bytes starting 29389 at OFFSET bytes into the data. The content and encoding of ANNEX 29390 is specific to OBJECT; it can supply additional details about what 29391 data to access. 29392 29393 Here are the specific requests of this form defined so far. All 29394 `qXfer:OBJECT:read:...' requests use the same reply formats, 29395 listed below. 29396 29397 `qXfer:auxv:read::OFFSET,LENGTH' 29398 Access the target's "auxiliary vector". *Note auxiliary 29399 vector: OS Information. Note ANNEX must be empty. 29400 29401 This packet is not probed by default; the remote stub must 29402 request it, by supplying an appropriate `qSupported' response 29403 (*note qSupported::). 29404 29405 `qXfer:features:read:ANNEX:OFFSET,LENGTH' 29406 Access the "target description". *Note Target 29407 Descriptions::. The annex specifies which XML document to 29408 access. The main description is always loaded from the 29409 `target.xml' annex. 29410 29411 This packet is not probed by default; the remote stub must 29412 request it, by supplying an appropriate `qSupported' response 29413 (*note qSupported::). 29414 29415 `qXfer:libraries:read:ANNEX:OFFSET,LENGTH' 29416 Access the target's list of loaded libraries. *Note Library 29417 List Format::. The annex part of the generic `qXfer' packet 29418 must be empty (*note qXfer read::). 29419 29420 Targets which maintain a list of libraries in the program's 29421 memory do not need to implement this packet; it is designed 29422 for platforms where the operating system manages the list of 29423 loaded libraries. 29424 29425 This packet is not probed by default; the remote stub must 29426 request it, by supplying an appropriate `qSupported' response 29427 (*note qSupported::). 29428 29429 `qXfer:memory-map:read::OFFSET,LENGTH' 29430 Access the target's "memory-map". *Note Memory Map Format::. 29431 The annex part of the generic `qXfer' packet must be empty 29432 (*note qXfer read::). 29433 29434 This packet is not probed by default; the remote stub must 29435 request it, by supplying an appropriate `qSupported' response 29436 (*note qSupported::). 29437 29438 `qXfer:sdata:read::OFFSET,LENGTH' 29439 Read contents of the extra collected static tracepoint marker 29440 information. The annex part of the generic `qXfer' packet 29441 must be empty (*note qXfer read::). *Note Tracepoint Action 29442 Lists: Tracepoint Actions. 29443 29444 This packet is not probed by default; the remote stub must 29445 request it, by supplying an appropriate `qSupported' response 29446 (*note qSupported::). 29447 29448 `qXfer:siginfo:read::OFFSET,LENGTH' 29449 Read contents of the extra signal information on the target 29450 system. The annex part of the generic `qXfer' packet must be 29451 empty (*note qXfer read::). 29452 29453 This packet is not probed by default; the remote stub must 29454 request it, by supplying an appropriate `qSupported' response 29455 (*note qSupported::). 29456 29457 `qXfer:spu:read:ANNEX:OFFSET,LENGTH' 29458 Read contents of an `spufs' file on the target system. The 29459 annex specifies which file to read; it must be of the form 29460 `ID/NAME', where ID specifies an SPU context ID in the target 29461 process, and NAME identifes the `spufs' file in that context 29462 to be accessed. 29463 29464 This packet is not probed by default; the remote stub must 29465 request it, by supplying an appropriate `qSupported' response 29466 (*note qSupported::). 29467 29468 `qXfer:threads:read::OFFSET,LENGTH' 29469 Access the list of threads on target. *Note Thread List 29470 Format::. The annex part of the generic `qXfer' packet must 29471 be empty (*note qXfer read::). 29472 29473 This packet is not probed by default; the remote stub must 29474 request it, by supplying an appropriate `qSupported' response 29475 (*note qSupported::). 29476 29477 `qXfer:osdata:read::OFFSET,LENGTH' 29478 Access the target's "operating system information". *Note 29479 Operating System Information::. 29480 29481 29482 Reply: 29483 `m DATA' 29484 Data DATA (*note Binary Data::) has been read from the 29485 target. There may be more data at a higher address (although 29486 it is permitted to return `m' even for the last valid block 29487 of data, as long as at least one byte of data was read). 29488 DATA may have fewer bytes than the LENGTH in the request. 29489 29490 `l DATA' 29491 Data DATA (*note Binary Data::) has been read from the target. 29492 There is no more data to be read. DATA may have fewer bytes 29493 than the LENGTH in the request. 29494 29495 `l' 29496 The OFFSET in the request is at the end of the data. There 29497 is no more data to be read. 29498 29499 `E00' 29500 The request was malformed, or ANNEX was invalid. 29501 29502 `E NN' 29503 The offset was invalid, or there was an error encountered 29504 reading the data. NN is a hex-encoded `errno' value. 29505 29506 `' 29507 An empty reply indicates the OBJECT string was not recognized 29508 by the stub, or that the object does not support reading. 29509 29510`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...' 29511 Write uninterpreted bytes into the target's special data area 29512 identified by the keyword OBJECT, starting at OFFSET bytes into 29513 the data. DATA... is the binary-encoded data (*note Binary 29514 Data::) to be written. The content and encoding of ANNEX is 29515 specific to OBJECT; it can supply additional details about what 29516 data to access. 29517 29518 Here are the specific requests of this form defined so far. All 29519 `qXfer:OBJECT:write:...' requests use the same reply formats, 29520 listed below. 29521 29522 `qXfer:siginfo:write::OFFSET:DATA...' 29523 Write DATA to the extra signal information on the target 29524 system. The annex part of the generic `qXfer' packet must be 29525 empty (*note qXfer write::). 29526 29527 This packet is not probed by default; the remote stub must 29528 request it, by supplying an appropriate `qSupported' response 29529 (*note qSupported::). 29530 29531 `qXfer:spu:write:ANNEX:OFFSET:DATA...' 29532 Write DATA to an `spufs' file on the target system. The 29533 annex specifies which file to write; it must be of the form 29534 `ID/NAME', where ID specifies an SPU context ID in the target 29535 process, and NAME identifes the `spufs' file in that context 29536 to be accessed. 29537 29538 This packet is not probed by default; the remote stub must 29539 request it, by supplying an appropriate `qSupported' response 29540 (*note qSupported::). 29541 29542 Reply: 29543 `NN' 29544 NN (hex encoded) is the number of bytes written. This may be 29545 fewer bytes than supplied in the request. 29546 29547 `E00' 29548 The request was malformed, or ANNEX was invalid. 29549 29550 `E NN' 29551 The offset was invalid, or there was an error encountered 29552 writing the data. NN is a hex-encoded `errno' value. 29553 29554 `' 29555 An empty reply indicates the OBJECT string was not recognized 29556 by the stub, or that the object does not support writing. 29557 29558`qXfer:OBJECT:OPERATION:...' 29559 Requests of this form may be added in the future. When a stub does 29560 not recognize the OBJECT keyword, or its support for OBJECT does 29561 not recognize the OPERATION keyword, the stub must respond with an 29562 empty packet. 29563 29564`qAttached:PID' 29565 Return an indication of whether the remote server attached to an 29566 existing process or created a new process. When the multiprocess 29567 protocol extensions are supported (*note multiprocess 29568 extensions::), PID is an integer in hexadecimal format identifying 29569 the target process. Otherwise, GDB will omit the PID field and 29570 the query packet will be simplified as `qAttached'. 29571 29572 This query is used, for example, to know whether the remote process 29573 should be detached or killed when a GDB session is ended with the 29574 `quit' command. 29575 29576 Reply: 29577 `1' 29578 The remote server attached to an existing process. 29579 29580 `0' 29581 The remote server created a new process. 29582 29583 `E NN' 29584 A badly formed request or an error was encountered. 29585 29586 29587 ---------- Footnotes ---------- 29588 29589 (1) The `qP' and `qL' packets predate these conventions, and have 29590arguments without any terminator for the packet name; we suspect they 29591are in widespread use in places that are difficult to upgrade. The 29592`qC' packet has no arguments, but some existing stubs (e.g. RedBoot) 29593are known to not check for the end of the packet. 29594 29595 29596File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol 29597 29598D.6 Architecture-Specific Protocol Details 29599========================================== 29600 29601This section describes how the remote protocol is applied to specific 29602target architectures. Also see *note Standard Target Features::, for 29603details of XML target descriptions for each architecture. 29604 29605D.6.1 ARM 29606--------- 29607 29608D.6.1.1 Breakpoint Kinds 29609........................ 29610 29611These breakpoint kinds are defined for the `Z0' and `Z1' packets. 29612 296132 29614 16-bit Thumb mode breakpoint. 29615 296163 29617 32-bit Thumb mode (Thumb-2) breakpoint. 29618 296194 29620 32-bit ARM mode breakpoint. 29621 29622 29623D.6.2 MIPS 29624---------- 29625 29626D.6.2.1 Register Packet Format 29627.............................. 29628 29629The following `g'/`G' packets have previously been defined. In the 29630below, some thirty-two bit registers are transferred as sixty-four 29631bits. Those registers should be zero/sign extended (which?) to fill 29632the space allocated. Register bytes are transferred in target byte 29633order. The two nibbles within a register byte are transferred 29634most-significant - least-significant. 29635 29636MIPS32 29637 All registers are transferred as thirty-two bit quantities in the 29638 order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 29639 floating-point registers; fsr; fir; fp. 29640 29641MIPS64 29642 All registers are transferred as sixty-four bit quantities 29643 (including thirty-two bit registers such as `sr'). The ordering 29644 is the same as `MIPS32'. 29645 29646 29647D.6.2.2 Breakpoint Kinds 29648........................ 29649 29650These breakpoint kinds are defined for the `Z0' and `Z1' packets. 29651 296522 29653 16-bit MIPS16 mode breakpoint. 29654 296553 29656 16-bit microMIPS mode breakpoint. 29657 296584 29659 32-bit standard MIPS mode breakpoint. 29660 296615 29662 32-bit microMIPS mode breakpoint. 29663 29664 29665 29666File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol 29667 29668D.7 Tracepoint Packets 29669====================== 29670 29671Here we describe the packets GDB uses to implement tracepoints (*note 29672Tracepoints::). 29673 29674`QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]' 29675 Create a new tracepoint, number N, at ADDR. If ENA is `E', then 29676 the tracepoint is enabled; if it is `D', then the tracepoint is 29677 disabled. STEP is the tracepoint's step count, and PASS is its 29678 pass count. If an `F' is present, then the tracepoint is to be a 29679 fast tracepoint, and the FLEN is the number of bytes that the 29680 target should copy elsewhere to make room for the tracepoint. If 29681 an `X' is present, it introduces a tracepoint condition, which 29682 consists of a hexadecimal length, followed by a comma and 29683 hex-encoded bytes, in a manner similar to action encodings as 29684 described below. If the trailing `-' is present, further `QTDP' 29685 packets will follow to specify this tracepoint's actions. 29686 29687 Replies: 29688 `OK' 29689 The packet was understood and carried out. 29690 29691 `qRelocInsn' 29692 *Note Relocate instruction reply packet: Tracepoint Packets. 29693 29694`QTDP:-N:ADDR:[S]ACTION...[-]' 29695 Define actions to be taken when a tracepoint is hit. N and ADDR 29696 must be the same as in the initial `QTDP' packet for this 29697 tracepoint. This packet may only be sent immediately after 29698 another `QTDP' packet that ended with a `-'. If the trailing `-' 29699 is present, further `QTDP' packets will follow, specifying more 29700 actions for this tracepoint. 29701 29702 In the series of action packets for a given tracepoint, at most one 29703 can have an `S' before its first ACTION. If such a packet is 29704 sent, it and the following packets define "while-stepping" 29705 actions. Any prior packets define ordinary actions -- that is, 29706 those taken when the tracepoint is first hit. If no action packet 29707 has an `S', then all the packets in the series specify ordinary 29708 tracepoint actions. 29709 29710 The `ACTION...' portion of the packet is a series of actions, 29711 concatenated without separators. Each action has one of the 29712 following forms: 29713 29714 `R MASK' 29715 Collect the registers whose bits are set in MASK. MASK is a 29716 hexadecimal number whose I'th bit is set if register number I 29717 should be collected. (The least significant bit is numbered 29718 zero.) Note that MASK may be any number of digits long; it 29719 may not fit in a 32-bit word. 29720 29721 `M BASEREG,OFFSET,LEN' 29722 Collect LEN bytes of memory starting at the address in 29723 register number BASEREG, plus OFFSET. If BASEREG is `-1', 29724 then the range has a fixed address: OFFSET is the address of 29725 the lowest byte to collect. The BASEREG, OFFSET, and LEN 29726 parameters are all unsigned hexadecimal values (the `-1' 29727 value for BASEREG is a special case). 29728 29729 `X LEN,EXPR' 29730 Evaluate EXPR, whose length is LEN, and collect memory as it 29731 directs. EXPR is an agent expression, as described in *note 29732 Agent Expressions::. Each byte of the expression is encoded 29733 as a two-digit hex number in the packet; LEN is the number of 29734 bytes in the expression (and thus one-half the number of hex 29735 digits in the packet). 29736 29737 29738 Any number of actions may be packed together in a single `QTDP' 29739 packet, as long as the packet does not exceed the maximum packet 29740 length (400 bytes, for many stubs). There may be only one `R' 29741 action per tracepoint, and it must precede any `M' or `X' actions. 29742 Any registers referred to by `M' and `X' actions must be collected 29743 by a preceding `R' action. (The "while-stepping" actions are 29744 treated as if they were attached to a separate tracepoint, as far 29745 as these restrictions are concerned.) 29746 29747 Replies: 29748 `OK' 29749 The packet was understood and carried out. 29750 29751 `qRelocInsn' 29752 *Note Relocate instruction reply packet: Tracepoint Packets. 29753 29754`QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES' 29755 Specify a source string of tracepoint N at address ADDR. This is 29756 useful to get accurate reproduction of the tracepoints originally 29757 downloaded at the beginning of the trace run. TYPE is the name of 29758 the tracepoint part, such as `cond' for the tracepoint's 29759 conditional expression (see below for a list of types), while 29760 BYTES is the string, encoded in hexadecimal. 29761 29762 START is the offset of the BYTES within the overall source string, 29763 while SLEN is the total length of the source string. This is 29764 intended for handling source strings that are longer than will fit 29765 in a single packet. 29766 29767 The available string types are `at' for the location, `cond' for 29768 the conditional, and `cmd' for an action command. GDB sends a 29769 separate packet for each command in the action list, in the same 29770 order in which the commands are stored in the list. 29771 29772 The target does not need to do anything with source strings except 29773 report them back as part of the replies to the `qTfP'/`qTsP' query 29774 packets. 29775 29776 Although this packet is optional, and GDB will only send it if the 29777 target replies with `TracepointSource' *Note General Query 29778 Packets::, it makes both disconnected tracing and trace files much 29779 easier to use. Otherwise the user must be careful that the 29780 tracepoints in effect while looking at trace frames are identical 29781 to the ones in effect during the trace run; even a small 29782 discrepancy could cause `tdump' not to work, or a particular trace 29783 frame not be found. 29784 29785`QTDV:N:VALUE' 29786 Create a new trace state variable, number N, with an initial value 29787 of VALUE, which is a 64-bit signed integer. Both N and VALUE are 29788 encoded as hexadecimal values. GDB has the option of not using 29789 this packet for initial values of zero; the target should simply 29790 create the trace state variables as they are mentioned in 29791 expressions. 29792 29793`QTFrame:N' 29794 Select the N'th tracepoint frame from the buffer, and use the 29795 register and memory contents recorded there to answer subsequent 29796 request packets from GDB. 29797 29798 A successful reply from the stub indicates that the stub has found 29799 the requested frame. The response is a series of parts, 29800 concatenated without separators, describing the frame we selected. 29801 Each part has one of the following forms: 29802 29803 `F F' 29804 The selected frame is number N in the trace frame buffer; F 29805 is a hexadecimal number. If F is `-1', then there was no 29806 frame matching the criteria in the request packet. 29807 29808 `T T' 29809 The selected trace frame records a hit of tracepoint number T; 29810 T is a hexadecimal number. 29811 29812 29813`QTFrame:pc:ADDR' 29814 Like `QTFrame:N', but select the first tracepoint frame after the 29815 currently selected frame whose PC is ADDR; ADDR is a hexadecimal 29816 number. 29817 29818`QTFrame:tdp:T' 29819 Like `QTFrame:N', but select the first tracepoint frame after the 29820 currently selected frame that is a hit of tracepoint T; T is a 29821 hexadecimal number. 29822 29823`QTFrame:range:START:END' 29824 Like `QTFrame:N', but select the first tracepoint frame after the 29825 currently selected frame whose PC is between START (inclusive) and 29826 END (inclusive); START and END are hexadecimal numbers. 29827 29828`QTFrame:outside:START:END' 29829 Like `QTFrame:range:START:END', but select the first frame 29830 _outside_ the given range of addresses (exclusive). 29831 29832`QTStart' 29833 Begin the tracepoint experiment. Begin collecting data from 29834 tracepoint hits in the trace frame buffer. This packet supports 29835 the `qRelocInsn' reply (*note Relocate instruction reply packet: 29836 Tracepoint Packets.). 29837 29838`QTStop' 29839 End the tracepoint experiment. Stop collecting trace frames. 29840 29841`QTinit' 29842 Clear the table of tracepoints, and empty the trace frame buffer. 29843 29844`QTro:START1,END1:START2,END2:...' 29845 Establish the given ranges of memory as "transparent". The stub 29846 will answer requests for these ranges from memory's current 29847 contents, if they were not collected as part of the tracepoint hit. 29848 29849 GDB uses this to mark read-only regions of memory, like those 29850 containing program code. Since these areas never change, they 29851 should still have the same contents they did when the tracepoint 29852 was hit, so there's no reason for the stub to refuse to provide 29853 their contents. 29854 29855`QTDisconnected:VALUE' 29856 Set the choice to what to do with the tracing run when GDB 29857 disconnects from the target. A VALUE of 1 directs the target to 29858 continue the tracing run, while 0 tells the target to stop tracing 29859 if GDB is no longer in the picture. 29860 29861`qTStatus' 29862 Ask the stub if there is a trace experiment running right now. 29863 29864 The reply has the form: 29865 29866 `TRUNNING[;FIELD]...' 29867 RUNNING is a single digit `1' if the trace is presently 29868 running, or `0' if not. It is followed by semicolon-separated 29869 optional fields that an agent may use to report additional 29870 status. 29871 29872 29873 If the trace is not running, the agent may report any of several 29874 explanations as one of the optional fields: 29875 29876 `tnotrun:0' 29877 No trace has been run yet. 29878 29879 `tstop:0' 29880 The trace was stopped by a user-originated stop command. 29881 29882 `tfull:0' 29883 The trace stopped because the trace buffer filled up. 29884 29885 `tdisconnected:0' 29886 The trace stopped because GDB disconnected from the target. 29887 29888 `tpasscount:TPNUM' 29889 The trace stopped because tracepoint TPNUM exceeded its pass 29890 count. 29891 29892 `terror:TEXT:TPNUM' 29893 The trace stopped because tracepoint TPNUM had an error. The 29894 string TEXT is available to describe the nature of the error 29895 (for instance, a divide by zero in the condition expression). 29896 TEXT is hex encoded. 29897 29898 `tunknown:0' 29899 The trace stopped for some other reason. 29900 29901 29902 Additional optional fields supply statistical and other 29903 information. Although not required, they are extremely useful for 29904 users monitoring the progress of a trace run. If a trace has 29905 stopped, and these numbers are reported, they must reflect the 29906 state of the just-stopped trace. 29907 29908 `tframes:N' 29909 The number of trace frames in the buffer. 29910 29911 `tcreated:N' 29912 The total number of trace frames created during the run. This 29913 may be larger than the trace frame count, if the buffer is 29914 circular. 29915 29916 `tsize:N' 29917 The total size of the trace buffer, in bytes. 29918 29919 `tfree:N' 29920 The number of bytes still unused in the buffer. 29921 29922 `circular:N' 29923 The value of the circular trace buffer flag. `1' means that 29924 the trace buffer is circular and old trace frames will be 29925 discarded if necessary to make room, `0' means that the trace 29926 buffer is linear and may fill up. 29927 29928 `disconn:N' 29929 The value of the disconnected tracing flag. `1' means that 29930 tracing will continue after GDB disconnects, `0' means that 29931 the trace run will stop. 29932 29933 29934`qTV:VAR' 29935 Ask the stub for the value of the trace state variable number VAR. 29936 29937 Replies: 29938 `VVALUE' 29939 The value of the variable is VALUE. This will be the current 29940 value of the variable if the user is examining a running 29941 target, or a saved value if the variable was collected in the 29942 trace frame that the user is looking at. Note that multiple 29943 requests may result in different reply values, such as when 29944 requesting values while the program is running. 29945 29946 `U' 29947 The value of the variable is unknown. This would occur, for 29948 example, if the user is examining a trace frame in which the 29949 requested variable was not collected. 29950 29951`qTfP' 29952`qTsP' 29953 These packets request data about tracepoints that are being used by 29954 the target. GDB sends `qTfP' to get the first piece of data, and 29955 multiple `qTsP' to get additional pieces. Replies to these 29956 packets generally take the form of the `QTDP' packets that define 29957 tracepoints. (FIXME add detailed syntax) 29958 29959`qTfV' 29960`qTsV' 29961 These packets request data about trace state variables that are on 29962 the target. GDB sends `qTfV' to get the first vari of data, and 29963 multiple `qTsV' to get additional variables. Replies to these 29964 packets follow the syntax of the `QTDV' packets that define trace 29965 state variables. 29966 29967`qTfSTM' 29968`qTsSTM' 29969 These packets request data about static tracepoint markers that 29970 exist in the target program. GDB sends `qTfSTM' to get the first 29971 piece of data, and multiple `qTsSTM' to get additional pieces. 29972 Replies to these packets take the following form: 29973 29974 Reply: 29975 `m ADDRESS:ID:EXTRA' 29976 A single marker 29977 29978 `m ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...' 29979 a comma-separated list of markers 29980 29981 `l' 29982 (lower case letter `L') denotes end of list. 29983 29984 `E NN' 29985 An error occurred. NN are hex digits. 29986 29987 `' 29988 An empty reply indicates that the request is not supported by 29989 the stub. 29990 29991 ADDRESS is encoded in hex. ID and EXTRA are strings encoded in 29992 hex. 29993 29994 In response to each query, the target will reply with a list of 29995 one or more markers, separated by commas. GDB will respond to each 29996 reply with a request for more markers (using the `qs' form of the 29997 query), until the target responds with `l' (lower-case ell, for 29998 "last"). 29999 30000`qTSTMat:ADDRESS' 30001 This packets requests data about static tracepoint markers in the 30002 target program at ADDRESS. Replies to this packet follow the 30003 syntax of the `qTfSTM' and `qTsSTM' packets that list static 30004 tracepoint markers. 30005 30006`QTSave:FILENAME' 30007 This packet directs the target to save trace data to the file name 30008 FILENAME in the target's filesystem. FILENAME is encoded as a hex 30009 string; the interpretation of the file name (relative vs absolute, 30010 wild cards, etc) is up to the target. 30011 30012`qTBuffer:OFFSET,LEN' 30013 Return up to LEN bytes of the current contents of trace buffer, 30014 starting at OFFSET. The trace buffer is treated as if it were a 30015 contiguous collection of traceframes, as per the trace file format. 30016 The reply consists as many hex-encoded bytes as the target can 30017 deliver in a packet; it is not an error to return fewer than were 30018 asked for. A reply consisting of just `l' indicates that no bytes 30019 are available. 30020 30021`QTBuffer:circular:VALUE' 30022 This packet directs the target to use a circular trace buffer if 30023 VALUE is 1, or a linear buffer if the value is 0. 30024 30025 30026D.7.1 Relocate instruction reply packet 30027--------------------------------------- 30028 30029When installing fast tracepoints in memory, the target may need to 30030relocate the instruction currently at the tracepoint address to a 30031different address in memory. For most instructions, a simple copy is 30032enough, but, for example, call instructions that implicitly push the 30033return address on the stack, and relative branches or other PC-relative 30034instructions require offset adjustment, so that the effect of executing 30035the instruction at a different address is the same as if it had 30036executed in the original location. 30037 30038 In response to several of the tracepoint packets, the target may also 30039respond with a number of intermediate `qRelocInsn' request packets 30040before the final result packet, to have GDB handle this relocation 30041operation. If a packet supports this mechanism, its documentation will 30042explicitly say so. See for example the above descriptions for the 30043`QTStart' and `QTDP' packets. The format of the request is: 30044 30045`qRelocInsn:FROM;TO' 30046 This requests GDB to copy instruction at address FROM to address 30047 TO, possibly adjusted so that executing the instruction at TO has 30048 the same effect as executing it at FROM. GDB writes the adjusted 30049 instruction to target memory starting at TO. 30050 30051 Replies: 30052`qRelocInsn:ADJUSTED_SIZE' 30053 Informs the stub the relocation is complete. ADJUSTED_SIZE is the 30054 length in bytes of resulting relocated instruction sequence. 30055 30056`E NN' 30057 A badly formed request was detected, or an error was encountered 30058 while relocating the instruction. 30059 30060 30061File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol 30062 30063D.8 Host I/O Packets 30064==================== 30065 30066The "Host I/O" packets allow GDB to perform I/O operations on the far 30067side of a remote link. For example, Host I/O is used to upload and 30068download files to a remote target with its own filesystem. Host I/O 30069uses the same constant values and data structure layout as the 30070target-initiated File-I/O protocol. However, the Host I/O packets are 30071structured differently. The target-initiated protocol relies on target 30072memory to store parameters and buffers. Host I/O requests are 30073initiated by GDB, and the target's memory is not involved. *Note 30074File-I/O Remote Protocol Extension::, for more details on the 30075target-initiated protocol. 30076 30077 The Host I/O request packets all encode a single operation along with 30078its arguments. They have this format: 30079 30080`vFile:OPERATION: PARAMETER...' 30081 OPERATION is the name of the particular request; the target should 30082 compare the entire packet name up to the second colon when checking 30083 for a supported operation. The format of PARAMETER depends on the 30084 operation. Numbers are always passed in hexadecimal. Negative 30085 numbers have an explicit minus sign (i.e. two's complement is not 30086 used). Strings (e.g. filenames) are encoded as a series of 30087 hexadecimal bytes. The last argument to a system call may be a 30088 buffer of escaped binary data (*note Binary Data::). 30089 30090 30091 The valid responses to Host I/O packets are: 30092 30093`F RESULT [, ERRNO] [; ATTACHMENT]' 30094 RESULT is the integer value returned by this operation, usually 30095 non-negative for success and -1 for errors. If an error has 30096 occured, ERRNO will be included in the result. ERRNO will have a 30097 value defined by the File-I/O protocol (*note Errno Values::). For 30098 operations which return data, ATTACHMENT supplies the data as a 30099 binary buffer. Binary buffers in response packets are escaped in 30100 the normal way (*note Binary Data::). See the individual packet 30101 documentation for the interpretation of RESULT and ATTACHMENT. 30102 30103`' 30104 An empty response indicates that this operation is not recognized. 30105 30106 30107 These are the supported Host I/O operations: 30108 30109`vFile:open: PATHNAME, FLAGS, MODE' 30110 Open a file at PATHNAME and return a file descriptor for it, or 30111 return -1 if an error occurs. PATHNAME is a string, FLAGS is an 30112 integer indicating a mask of open flags (*note Open Flags::), and 30113 MODE is an integer indicating a mask of mode bits to use if the 30114 file is created (*note mode_t Values::). *Note open::, for 30115 details of the open flags and mode values. 30116 30117`vFile:close: FD' 30118 Close the open file corresponding to FD and return 0, or -1 if an 30119 error occurs. 30120 30121`vFile:pread: FD, COUNT, OFFSET' 30122 Read data from the open file corresponding to FD. Up to COUNT 30123 bytes will be read from the file, starting at OFFSET relative to 30124 the start of the file. The target may read fewer bytes; common 30125 reasons include packet size limits and an end-of-file condition. 30126 The number of bytes read is returned. Zero should only be 30127 returned for a successful read at the end of the file, or if COUNT 30128 was zero. 30129 30130 The data read should be returned as a binary attachment on success. 30131 If zero bytes were read, the response should include an empty 30132 binary attachment (i.e. a trailing semicolon). The return value 30133 is the number of target bytes read; the binary attachment may be 30134 longer if some characters were escaped. 30135 30136`vFile:pwrite: FD, OFFSET, DATA' 30137 Write DATA (a binary buffer) to the open file corresponding to FD. 30138 Start the write at OFFSET from the start of the file. Unlike many 30139 `write' system calls, there is no separate COUNT argument; the 30140 length of DATA in the packet is used. `vFile:write' returns the 30141 number of bytes written, which may be shorter than the length of 30142 DATA, or -1 if an error occurred. 30143 30144`vFile:unlink: PATHNAME' 30145 Delete the file at PATHNAME on the target. Return 0, or -1 if an 30146 error occurs. PATHNAME is a string. 30147 30148 30149 30150File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol 30151 30152D.9 Interrupts 30153============== 30154 30155When a program on the remote target is running, GDB may attempt to 30156interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by 30157`g', control of which is specified via GDB's `interrupt-sequence'. 30158 30159 The precise meaning of `BREAK' is defined by the transport mechanism 30160and may, in fact, be undefined. GDB does not currently define a 30161`BREAK' mechanism for any of the network interfaces except for TCP, in 30162which case GDB sends the `telnet' BREAK sequence. 30163 30164 `Ctrl-C', on the other hand, is defined and implemented for all 30165transport mechanisms. It is represented by sending the single byte 30166`0x03' without any of the usual packet overhead described in the 30167Overview section (*note Overview::). When a `0x03' byte is transmitted 30168as part of a packet, it is considered to be packet data and does _not_ 30169represent an interrupt. E.g., an `X' packet (*note X packet::), used 30170for binary downloads, may include an unescaped `0x03' as part of its 30171packet. 30172 30173 `BREAK' followed by `g' is also known as Magic SysRq g. When Linux 30174kernel receives this sequence from serial port, it stops execution and 30175connects to gdb. 30176 30177 Stubs are not required to recognize these interrupt mechanisms and 30178the precise meaning associated with receipt of the interrupt is 30179implementation defined. If the target supports debugging of multiple 30180threads and/or processes, it should attempt to interrupt all 30181currently-executing threads and processes. If the stub is successful 30182at interrupting the running program, it should send one of the stop 30183reply packets (*note Stop Reply Packets::) to GDB as a result of 30184successfully stopping the program in all-stop mode, and a stop reply 30185for each stopped thread in non-stop mode. Interrupts received while the 30186program is stopped are discarded. 30187 30188 30189File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol 30190 30191D.10 Notification Packets 30192========================= 30193 30194The GDB remote serial protocol includes "notifications", packets that 30195require no acknowledgment. Both the GDB and the stub may send 30196notifications (although the only notifications defined at present are 30197sent by the stub). Notifications carry information without incurring 30198the round-trip latency of an acknowledgment, and so are useful for 30199low-impact communications where occasional packet loss is not a problem. 30200 30201 A notification packet has the form `% DATA # CHECKSUM', where DATA 30202is the content of the notification, and CHECKSUM is a checksum of DATA, 30203computed and formatted as for ordinary GDB packets. A notification's 30204DATA never contains `$', `%' or `#' characters. Upon receiving a 30205notification, the recipient sends no `+' or `-' to acknowledge the 30206notification's receipt or to report its corruption. 30207 30208 Every notification's DATA begins with a name, which contains no 30209colon characters, followed by a colon character. 30210 30211 Recipients should silently ignore corrupted notifications and 30212notifications they do not understand. Recipients should restart 30213timeout periods on receipt of a well-formed notification, whether or 30214not they understand it. 30215 30216 Senders should only send the notifications described here when this 30217protocol description specifies that they are permitted. In the future, 30218we may extend the protocol to permit existing notifications in new 30219contexts; this rule helps older senders avoid confusing newer 30220recipients. 30221 30222 (Older versions of GDB ignore bytes received until they see the `$' 30223byte that begins an ordinary packet, so new stubs may transmit 30224notifications without fear of confusing older clients. There are no 30225notifications defined for GDB to send at the moment, but we assume that 30226most older stubs would ignore them, as well.) 30227 30228 The following notification packets from the stub to GDB are defined: 30229 30230`Stop: REPLY' 30231 Report an asynchronous stop event in non-stop mode. The REPLY has 30232 the form of a stop reply, as described in *note Stop Reply 30233 Packets::. Refer to *note Remote Non-Stop::, for information on 30234 how these notifications are acknowledged by GDB. 30235 30236 30237File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol 30238 30239D.11 Remote Protocol Support for Non-Stop Mode 30240============================================== 30241 30242GDB's remote protocol supports non-stop debugging of multi-threaded 30243programs, as described in *note Non-Stop Mode::. If the stub supports 30244non-stop mode, it should report that to GDB by including `QNonStop+' in 30245its `qSupported' response (*note qSupported::). 30246 30247 GDB typically sends a `QNonStop' packet only when establishing a new 30248connection with the stub. Entering non-stop mode does not alter the 30249state of any currently-running threads, but targets must stop all 30250threads in any already-attached processes when entering all-stop mode. 30251GDB uses the `?' packet as necessary to probe the target state after a 30252mode change. 30253 30254 In non-stop mode, when an attached process encounters an event that 30255would otherwise be reported with a stop reply, it uses the asynchronous 30256notification mechanism (*note Notification Packets::) to inform GDB. 30257In contrast to all-stop mode, where all threads in all processes are 30258stopped when a stop reply is sent, in non-stop mode only the thread 30259reporting the stop event is stopped. That is, when reporting a `S' or 30260`T' response to indicate completion of a step operation, hitting a 30261breakpoint, or a fault, only the affected thread is stopped; any other 30262still-running threads continue to run. When reporting a `W' or `X' 30263response, all running threads belonging to other attached processes 30264continue to run. 30265 30266 Only one stop reply notification at a time may be pending; if 30267additional stop events occur before GDB has acknowledged the previous 30268notification, they must be queued by the stub for later synchronous 30269transmission in response to `vStopped' packets from GDB. Because the 30270notification mechanism is unreliable, the stub is permitted to resend a 30271stop reply notification if it believes GDB may not have received it. 30272GDB ignores additional stop reply notifications received before it has 30273finished processing a previous notification and the stub has completed 30274sending any queued stop events. 30275 30276 Otherwise, GDB must be prepared to receive a stop reply notification 30277at any time. Specifically, they may appear when GDB is not otherwise 30278reading input from the stub, or when GDB is expecting to read a normal 30279synchronous response or a `+'/`-' acknowledgment to a packet it has 30280sent. Notification packets are distinct from any other communication 30281from the stub so there is no ambiguity. 30282 30283 After receiving a stop reply notification, GDB shall acknowledge it 30284by sending a `vStopped' packet (*note vStopped packet::) as a regular, 30285synchronous request to the stub. Such acknowledgment is not required 30286to happen immediately, as GDB is permitted to send other, unrelated 30287packets to the stub first, which the stub should process normally. 30288 30289 Upon receiving a `vStopped' packet, if the stub has other queued 30290stop events to report to GDB, it shall respond by sending a normal stop 30291reply response. GDB shall then send another `vStopped' packet to 30292solicit further responses; again, it is permitted to send other, 30293unrelated packets as well which the stub should process normally. 30294 30295 If the stub receives a `vStopped' packet and there are no additional 30296stop events to report, the stub shall return an `OK' response. At this 30297point, if further stop events occur, the stub shall send a new stop 30298reply notification, GDB shall accept the notification, and the process 30299shall be repeated. 30300 30301 In non-stop mode, the target shall respond to the `?' packet as 30302follows. First, any incomplete stop reply notification/`vStopped' 30303sequence in progress is abandoned. The target must begin a new 30304sequence reporting stop events for all stopped threads, whether or not 30305it has previously reported those events to GDB. The first stop reply 30306is sent as a synchronous reply to the `?' packet, and subsequent stop 30307replies are sent as responses to `vStopped' packets using the mechanism 30308described above. The target must not send asynchronous stop reply 30309notifications until the sequence is complete. If all threads are 30310running when the target receives the `?' packet, or if the target is 30311not attached to any process, it shall respond `OK'. 30312 30313 30314File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol 30315 30316D.12 Packet Acknowledgment 30317========================== 30318 30319By default, when either the host or the target machine receives a 30320packet, the first response expected is an acknowledgment: either `+' 30321(to indicate the package was received correctly) or `-' (to request 30322retransmission). This mechanism allows the GDB remote protocol to 30323operate over unreliable transport mechanisms, such as a serial line. 30324 30325 In cases where the transport mechanism is itself reliable (such as a 30326pipe or TCP connection), the `+'/`-' acknowledgments are redundant. It 30327may be desirable to disable them in that case to reduce communication 30328overhead, or for other reasons. This can be accomplished by means of 30329the `QStartNoAckMode' packet; *note QStartNoAckMode::. 30330 30331 When in no-acknowledgment mode, neither the stub nor GDB shall send 30332or expect `+'/`-' protocol acknowledgments. The packet and response 30333format still includes the normal checksum, as described in *note 30334Overview::, but the checksum may be ignored by the receiver. 30335 30336 If the stub supports `QStartNoAckMode' and prefers to operate in 30337no-acknowledgment mode, it should report that to GDB by including 30338`QStartNoAckMode+' in its response to `qSupported'; *note qSupported::. 30339If GDB also supports `QStartNoAckMode' and it has not been disabled via 30340the `set remote noack-packet off' command (*note Remote 30341Configuration::), GDB may then send a `QStartNoAckMode' packet to the 30342stub. Only then may the stub actually turn off packet acknowledgments. 30343GDB sends a final `+' acknowledgment of the stub's `OK' response, which 30344can be safely ignored by the stub. 30345 30346 Note that `set remote noack-packet' command only affects negotiation 30347between GDB and the stub when subsequent connections are made; it does 30348not affect the protocol acknowledgment state for any current connection. 30349Since `+'/`-' acknowledgments are enabled by default when a new 30350connection is established, there is also no protocol request to 30351re-enable the acknowledgments for the current connection, once disabled. 30352 30353 30354File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol 30355 30356D.13 Examples 30357============= 30358 30359Example sequence of a target being re-started. Notice how the restart 30360does not get any direct output: 30361 30362 -> `R00' 30363 <- `+' 30364 _target restarts_ 30365 -> `?' 30366 <- `+' 30367 <- `T001:1234123412341234' 30368 -> `+' 30369 30370 Example sequence of a target being stepped by a single instruction: 30371 30372 -> `G1445...' 30373 <- `+' 30374 -> `s' 30375 <- `+' 30376 _time passes_ 30377 <- `T001:1234123412341234' 30378 -> `+' 30379 -> `g' 30380 <- `+' 30381 <- `1455...' 30382 -> `+' 30383 30384 30385File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol 30386 30387D.14 File-I/O Remote Protocol Extension 30388======================================= 30389 30390* Menu: 30391 30392* File-I/O Overview:: 30393* Protocol Basics:: 30394* The F Request Packet:: 30395* The F Reply Packet:: 30396* The Ctrl-C Message:: 30397* Console I/O:: 30398* List of Supported Calls:: 30399* Protocol-specific Representation of Datatypes:: 30400* Constants:: 30401* File-I/O Examples:: 30402 30403 30404File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension 30405 30406D.14.1 File-I/O Overview 30407------------------------ 30408 30409The "File I/O remote protocol extension" (short: File-I/O) allows the 30410target to use the host's file system and console I/O to perform various 30411system calls. System calls on the target system are translated into a 30412remote protocol packet to the host system, which then performs the 30413needed actions and returns a response packet to the target system. 30414This simulates file system operations even on targets that lack file 30415systems. 30416 30417 The protocol is defined to be independent of both the host and 30418target systems. It uses its own internal representation of datatypes 30419and values. Both GDB and the target's GDB stub are responsible for 30420translating the system-dependent value representations into the internal 30421protocol representations when data is transmitted. 30422 30423 The communication is synchronous. A system call is possible only 30424when GDB is waiting for a response from the `C', `c', `S' or `s' 30425packets. While GDB handles the request for a system call, the target 30426is stopped to allow deterministic access to the target's memory. 30427Therefore File-I/O is not interruptible by target signals. On the 30428other hand, it is possible to interrupt File-I/O by a user interrupt 30429(`Ctrl-C') within GDB. 30430 30431 The target's request to perform a host system call does not finish 30432the latest `C', `c', `S' or `s' action. That means, after finishing 30433the system call, the target returns to continuing the previous activity 30434(continue, step). No additional continue or step request from GDB is 30435required. 30436 30437 (gdb) continue 30438 <- target requests 'system call X' 30439 target is stopped, GDB executes system call 30440 -> GDB returns result 30441 ... target continues, GDB returns to wait for the target 30442 <- target hits breakpoint and sends a Txx packet 30443 30444 The protocol only supports I/O on the console and to regular files on 30445the host file system. Character or block special devices, pipes, named 30446pipes, sockets or any other communication method on the host system are 30447not supported by this protocol. 30448 30449 File I/O is not supported in non-stop mode. 30450 30451 30452File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension 30453 30454D.14.2 Protocol Basics 30455---------------------- 30456 30457The File-I/O protocol uses the `F' packet as the request as well as 30458reply packet. Since a File-I/O system call can only occur when GDB is 30459waiting for a response from the continuing or stepping target, the 30460File-I/O request is a reply that GDB has to expect as a result of a 30461previous `C', `c', `S' or `s' packet. This `F' packet contains all 30462information needed to allow GDB to call the appropriate host system 30463call: 30464 30465 * A unique identifier for the requested system call. 30466 30467 * All parameters to the system call. Pointers are given as addresses 30468 in the target memory address space. Pointers to strings are given 30469 as pointer/length pair. Numerical values are given as they are. 30470 Numerical control flags are given in a protocol-specific 30471 representation. 30472 30473 30474 At this point, GDB has to perform the following actions. 30475 30476 * If the parameters include pointer values to data needed as input 30477 to a system call, GDB requests this data from the target with a 30478 standard `m' packet request. This additional communication has to 30479 be expected by the target implementation and is handled as any 30480 other `m' packet. 30481 30482 * GDB translates all value from protocol representation to host 30483 representation as needed. Datatypes are coerced into the host 30484 types. 30485 30486 * GDB calls the system call. 30487 30488 * It then coerces datatypes back to protocol representation. 30489 30490 * If the system call is expected to return data in buffer space 30491 specified by pointer parameters to the call, the data is 30492 transmitted to the target using a `M' or `X' packet. This packet 30493 has to be expected by the target implementation and is handled as 30494 any other `M' or `X' packet. 30495 30496 30497 Eventually GDB replies with another `F' packet which contains all 30498necessary information for the target to continue. This at least 30499contains 30500 30501 * Return value. 30502 30503 * `errno', if has been changed by the system call. 30504 30505 * "Ctrl-C" flag. 30506 30507 30508 After having done the needed type and value coercion, the target 30509continues the latest continue or step action. 30510 30511 30512File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension 30513 30514D.14.3 The `F' Request Packet 30515----------------------------- 30516 30517The `F' request packet has the following format: 30518 30519`FCALL-ID,PARAMETER...' 30520 CALL-ID is the identifier to indicate the host system call to be 30521 called. This is just the name of the function. 30522 30523 PARAMETER... are the parameters to the system call. Parameters 30524 are hexadecimal integer values, either the actual values in case 30525 of scalar datatypes, pointers to target buffer space in case of 30526 compound datatypes and unspecified memory areas, or pointer/length 30527 pairs in case of string parameters. These are appended to the 30528 CALL-ID as a comma-delimited list. All values are transmitted in 30529 ASCII string representation, pointer/length pairs separated by a 30530 slash. 30531 30532 30533 30534File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension 30535 30536D.14.4 The `F' Reply Packet 30537--------------------------- 30538 30539The `F' reply packet has the following format: 30540 30541`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT' 30542 RETCODE is the return code of the system call as hexadecimal value. 30543 30544 ERRNO is the `errno' set by the call, in protocol-specific 30545 representation. This parameter can be omitted if the call was 30546 successful. 30547 30548 CTRL-C FLAG is only sent if the user requested a break. In this 30549 case, ERRNO must be sent as well, even if the call was successful. 30550 The CTRL-C FLAG itself consists of the character `C': 30551 30552 F0,0,C 30553 30554 or, if the call was interrupted before the host call has been 30555 performed: 30556 30557 F-1,4,C 30558 30559 assuming 4 is the protocol-specific representation of `EINTR'. 30560 30561 30562 30563File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension 30564 30565D.14.5 The `Ctrl-C' Message 30566--------------------------- 30567 30568If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply 30569Packet::), the target should behave as if it had gotten a break 30570message. The meaning for the target is "system call interrupted by 30571`SIGINT'". Consequentially, the target should actually stop (as with a 30572break message) and return to GDB with a `T02' packet. 30573 30574 It's important for the target to know in which state the system call 30575was interrupted. There are two possible cases: 30576 30577 * The system call hasn't been performed on the host yet. 30578 30579 * The system call on the host has been finished. 30580 30581 30582 These two states can be distinguished by the target by the value of 30583the returned `errno'. If it's the protocol representation of `EINTR', 30584the system call hasn't been performed. This is equivalent to the 30585`EINTR' handling on POSIX systems. In any other case, the target may 30586presume that the system call has been finished -- successfully or not 30587-- and should behave as if the break message arrived right after the 30588system call. 30589 30590 GDB must behave reliably. If the system call has not been called 30591yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno' 30592in the packet. If the system call on the host has been finished before 30593the user requests a break, the full action must be finished by GDB. 30594This requires sending `M' or `X' packets as necessary. The `F' packet 30595may only be sent when either nothing has happened or the full action 30596has been completed. 30597 30598 30599File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension 30600 30601D.14.6 Console I/O 30602------------------ 30603 30604By default and if not explicitly closed by the target system, the file 30605descriptors 0, 1 and 2 are connected to the GDB console. Output on the 30606GDB console is handled as any other file output operation (`write(1, 30607...)' or `write(2, ...)'). Console input is handled by GDB so that 30608after the target read request from file descriptor 0 all following 30609typing is buffered until either one of the following conditions is met: 30610 30611 * The user types `Ctrl-c'. The behaviour is as explained above, and 30612 the `read' system call is treated as finished. 30613 30614 * The user presses <RET>. This is treated as end of input with a 30615 trailing newline. 30616 30617 * The user types `Ctrl-d'. This is treated as end of input. No 30618 trailing character (neither newline nor `Ctrl-D') is appended to 30619 the input. 30620 30621 30622 If the user has typed more characters than fit in the buffer given to 30623the `read' call, the trailing characters are buffered in GDB until 30624either another `read(0, ...)' is requested by the target, or debugging 30625is stopped at the user's request. 30626 30627 30628File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension 30629 30630D.14.7 List of Supported Calls 30631------------------------------ 30632 30633* Menu: 30634 30635* open:: 30636* close:: 30637* read:: 30638* write:: 30639* lseek:: 30640* rename:: 30641* unlink:: 30642* stat/fstat:: 30643* gettimeofday:: 30644* isatty:: 30645* system:: 30646 30647 30648File: gdb.info, Node: open, Next: close, Up: List of Supported Calls 30649 30650open 30651.... 30652 30653Synopsis: 30654 int open(const char *pathname, int flags); 30655 int open(const char *pathname, int flags, mode_t mode); 30656 30657Request: 30658 `Fopen,PATHPTR/LEN,FLAGS,MODE' 30659 30660 FLAGS is the bitwise `OR' of the following values: 30661 30662 `O_CREAT' 30663 If the file does not exist it will be created. The host 30664 rules apply as far as file ownership and time stamps are 30665 concerned. 30666 30667 `O_EXCL' 30668 When used with `O_CREAT', if the file already exists it is an 30669 error and open() fails. 30670 30671 `O_TRUNC' 30672 If the file already exists and the open mode allows writing 30673 (`O_RDWR' or `O_WRONLY' is given) it will be truncated to 30674 zero length. 30675 30676 `O_APPEND' 30677 The file is opened in append mode. 30678 30679 `O_RDONLY' 30680 The file is opened for reading only. 30681 30682 `O_WRONLY' 30683 The file is opened for writing only. 30684 30685 `O_RDWR' 30686 The file is opened for reading and writing. 30687 30688 Other bits are silently ignored. 30689 30690 MODE is the bitwise `OR' of the following values: 30691 30692 `S_IRUSR' 30693 User has read permission. 30694 30695 `S_IWUSR' 30696 User has write permission. 30697 30698 `S_IRGRP' 30699 Group has read permission. 30700 30701 `S_IWGRP' 30702 Group has write permission. 30703 30704 `S_IROTH' 30705 Others have read permission. 30706 30707 `S_IWOTH' 30708 Others have write permission. 30709 30710 Other bits are silently ignored. 30711 30712Return value: 30713 `open' returns the new file descriptor or -1 if an error occurred. 30714 30715Errors: 30716 30717 `EEXIST' 30718 PATHNAME already exists and `O_CREAT' and `O_EXCL' were used. 30719 30720 `EISDIR' 30721 PATHNAME refers to a directory. 30722 30723 `EACCES' 30724 The requested access is not allowed. 30725 30726 `ENAMETOOLONG' 30727 PATHNAME was too long. 30728 30729 `ENOENT' 30730 A directory component in PATHNAME does not exist. 30731 30732 `ENODEV' 30733 PATHNAME refers to a device, pipe, named pipe or socket. 30734 30735 `EROFS' 30736 PATHNAME refers to a file on a read-only filesystem and write 30737 access was requested. 30738 30739 `EFAULT' 30740 PATHNAME is an invalid pointer value. 30741 30742 `ENOSPC' 30743 No space on device to create the file. 30744 30745 `EMFILE' 30746 The process already has the maximum number of files open. 30747 30748 `ENFILE' 30749 The limit on the total number of files open on the system has 30750 been reached. 30751 30752 `EINTR' 30753 The call was interrupted by the user. 30754 30755 30756 30757File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls 30758 30759close 30760..... 30761 30762Synopsis: 30763 int close(int fd); 30764 30765Request: 30766 `Fclose,FD' 30767 30768Return value: 30769 `close' returns zero on success, or -1 if an error occurred. 30770 30771Errors: 30772 30773 `EBADF' 30774 FD isn't a valid open file descriptor. 30775 30776 `EINTR' 30777 The call was interrupted by the user. 30778 30779 30780 30781File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls 30782 30783read 30784.... 30785 30786Synopsis: 30787 int read(int fd, void *buf, unsigned int count); 30788 30789Request: 30790 `Fread,FD,BUFPTR,COUNT' 30791 30792Return value: 30793 On success, the number of bytes read is returned. Zero indicates 30794 end of file. If count is zero, read returns zero as well. On 30795 error, -1 is returned. 30796 30797Errors: 30798 30799 `EBADF' 30800 FD is not a valid file descriptor or is not open for reading. 30801 30802 `EFAULT' 30803 BUFPTR is an invalid pointer value. 30804 30805 `EINTR' 30806 The call was interrupted by the user. 30807 30808 30809 30810File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls 30811 30812write 30813..... 30814 30815Synopsis: 30816 int write(int fd, const void *buf, unsigned int count); 30817 30818Request: 30819 `Fwrite,FD,BUFPTR,COUNT' 30820 30821Return value: 30822 On success, the number of bytes written are returned. Zero 30823 indicates nothing was written. On error, -1 is returned. 30824 30825Errors: 30826 30827 `EBADF' 30828 FD is not a valid file descriptor or is not open for writing. 30829 30830 `EFAULT' 30831 BUFPTR is an invalid pointer value. 30832 30833 `EFBIG' 30834 An attempt was made to write a file that exceeds the 30835 host-specific maximum file size allowed. 30836 30837 `ENOSPC' 30838 No space on device to write the data. 30839 30840 `EINTR' 30841 The call was interrupted by the user. 30842 30843 30844 30845File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls 30846 30847lseek 30848..... 30849 30850Synopsis: 30851 long lseek (int fd, long offset, int flag); 30852 30853Request: 30854 `Flseek,FD,OFFSET,FLAG' 30855 30856 FLAG is one of: 30857 30858 `SEEK_SET' 30859 The offset is set to OFFSET bytes. 30860 30861 `SEEK_CUR' 30862 The offset is set to its current location plus OFFSET bytes. 30863 30864 `SEEK_END' 30865 The offset is set to the size of the file plus OFFSET bytes. 30866 30867Return value: 30868 On success, the resulting unsigned offset in bytes from the 30869 beginning of the file is returned. Otherwise, a value of -1 is 30870 returned. 30871 30872Errors: 30873 30874 `EBADF' 30875 FD is not a valid open file descriptor. 30876 30877 `ESPIPE' 30878 FD is associated with the GDB console. 30879 30880 `EINVAL' 30881 FLAG is not a proper value. 30882 30883 `EINTR' 30884 The call was interrupted by the user. 30885 30886 30887 30888File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls 30889 30890rename 30891...... 30892 30893Synopsis: 30894 int rename(const char *oldpath, const char *newpath); 30895 30896Request: 30897 `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN' 30898 30899Return value: 30900 On success, zero is returned. On error, -1 is returned. 30901 30902Errors: 30903 30904 `EISDIR' 30905 NEWPATH is an existing directory, but OLDPATH is not a 30906 directory. 30907 30908 `EEXIST' 30909 NEWPATH is a non-empty directory. 30910 30911 `EBUSY' 30912 OLDPATH or NEWPATH is a directory that is in use by some 30913 process. 30914 30915 `EINVAL' 30916 An attempt was made to make a directory a subdirectory of 30917 itself. 30918 30919 `ENOTDIR' 30920 A component used as a directory in OLDPATH or new path is 30921 not a directory. Or OLDPATH is a directory and NEWPATH 30922 exists but is not a directory. 30923 30924 `EFAULT' 30925 OLDPATHPTR or NEWPATHPTR are invalid pointer values. 30926 30927 `EACCES' 30928 No access to the file or the path of the file. 30929 30930 `ENAMETOOLONG' 30931 OLDPATH or NEWPATH was too long. 30932 30933 `ENOENT' 30934 A directory component in OLDPATH or NEWPATH does not exist. 30935 30936 `EROFS' 30937 The file is on a read-only filesystem. 30938 30939 `ENOSPC' 30940 The device containing the file has no room for the new 30941 directory entry. 30942 30943 `EINTR' 30944 The call was interrupted by the user. 30945 30946 30947 30948File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls 30949 30950unlink 30951...... 30952 30953Synopsis: 30954 int unlink(const char *pathname); 30955 30956Request: 30957 `Funlink,PATHNAMEPTR/LEN' 30958 30959Return value: 30960 On success, zero is returned. On error, -1 is returned. 30961 30962Errors: 30963 30964 `EACCES' 30965 No access to the file or the path of the file. 30966 30967 `EPERM' 30968 The system does not allow unlinking of directories. 30969 30970 `EBUSY' 30971 The file PATHNAME cannot be unlinked because it's being used 30972 by another process. 30973 30974 `EFAULT' 30975 PATHNAMEPTR is an invalid pointer value. 30976 30977 `ENAMETOOLONG' 30978 PATHNAME was too long. 30979 30980 `ENOENT' 30981 A directory component in PATHNAME does not exist. 30982 30983 `ENOTDIR' 30984 A component of the path is not a directory. 30985 30986 `EROFS' 30987 The file is on a read-only filesystem. 30988 30989 `EINTR' 30990 The call was interrupted by the user. 30991 30992 30993 30994File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls 30995 30996stat/fstat 30997.......... 30998 30999Synopsis: 31000 int stat(const char *pathname, struct stat *buf); 31001 int fstat(int fd, struct stat *buf); 31002 31003Request: 31004 `Fstat,PATHNAMEPTR/LEN,BUFPTR' 31005 `Ffstat,FD,BUFPTR' 31006 31007Return value: 31008 On success, zero is returned. On error, -1 is returned. 31009 31010Errors: 31011 31012 `EBADF' 31013 FD is not a valid open file. 31014 31015 `ENOENT' 31016 A directory component in PATHNAME does not exist or the path 31017 is an empty string. 31018 31019 `ENOTDIR' 31020 A component of the path is not a directory. 31021 31022 `EFAULT' 31023 PATHNAMEPTR is an invalid pointer value. 31024 31025 `EACCES' 31026 No access to the file or the path of the file. 31027 31028 `ENAMETOOLONG' 31029 PATHNAME was too long. 31030 31031 `EINTR' 31032 The call was interrupted by the user. 31033 31034 31035 31036File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls 31037 31038gettimeofday 31039............ 31040 31041Synopsis: 31042 int gettimeofday(struct timeval *tv, void *tz); 31043 31044Request: 31045 `Fgettimeofday,TVPTR,TZPTR' 31046 31047Return value: 31048 On success, 0 is returned, -1 otherwise. 31049 31050Errors: 31051 31052 `EINVAL' 31053 TZ is a non-NULL pointer. 31054 31055 `EFAULT' 31056 TVPTR and/or TZPTR is an invalid pointer value. 31057 31058 31059 31060File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls 31061 31062isatty 31063...... 31064 31065Synopsis: 31066 int isatty(int fd); 31067 31068Request: 31069 `Fisatty,FD' 31070 31071Return value: 31072 Returns 1 if FD refers to the GDB console, 0 otherwise. 31073 31074Errors: 31075 31076 `EINTR' 31077 The call was interrupted by the user. 31078 31079 31080 Note that the `isatty' call is treated as a special case: it returns 310811 to the target if the file descriptor is attached to the GDB console, 310820 otherwise. Implementing through system calls would require 31083implementing `ioctl' and would be more complex than needed. 31084 31085 31086File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls 31087 31088system 31089...... 31090 31091Synopsis: 31092 int system(const char *command); 31093 31094Request: 31095 `Fsystem,COMMANDPTR/LEN' 31096 31097Return value: 31098 If LEN is zero, the return value indicates whether a shell is 31099 available. A zero return value indicates a shell is not available. 31100 For non-zero LEN, the value returned is -1 on error and the return 31101 status of the command otherwise. Only the exit status of the 31102 command is returned, which is extracted from the host's `system' 31103 return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh' 31104 could not be executed, 127 is returned. 31105 31106Errors: 31107 31108 `EINTR' 31109 The call was interrupted by the user. 31110 31111 31112 GDB takes over the full task of calling the necessary host calls to 31113perform the `system' call. The return value of `system' on the host is 31114simplified before it's returned to the target. Any termination signal 31115information from the child process is discarded, and the return value 31116consists entirely of the exit status of the called command. 31117 31118 Due to security concerns, the `system' call is by default refused by 31119GDB. The user has to allow this call explicitly with the `set remote 31120system-call-allowed 1' command. 31121 31122`set remote system-call-allowed' 31123 Control whether to allow the `system' calls in the File I/O 31124 protocol for the remote target. The default is zero (disabled). 31125 31126`show remote system-call-allowed' 31127 Show whether the `system' calls are allowed in the File I/O 31128 protocol. 31129 31130 31131File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension 31132 31133D.14.8 Protocol-specific Representation of Datatypes 31134---------------------------------------------------- 31135 31136* Menu: 31137 31138* Integral Datatypes:: 31139* Pointer Values:: 31140* Memory Transfer:: 31141* struct stat:: 31142* struct timeval:: 31143 31144 31145File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes 31146 31147Integral Datatypes 31148.................. 31149 31150The integral datatypes used in the system calls are `int', `unsigned 31151int', `long', `unsigned long', `mode_t', and `time_t'. 31152 31153 `int', `unsigned int', `mode_t' and `time_t' are implemented as 32 31154bit values in this protocol. 31155 31156 `long' and `unsigned long' are implemented as 64 bit types. 31157 31158 *Note Limits::, for corresponding MIN and MAX values (similar to 31159those in `limits.h') to allow range checking on host and target. 31160 31161 `time_t' datatypes are defined as seconds since the Epoch. 31162 31163 All integral datatypes transferred as part of a memory read or write 31164of a structured datatype e.g. a `struct stat' have to be given in big 31165endian byte order. 31166 31167 31168File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes 31169 31170Pointer Values 31171.............. 31172 31173Pointers to target data are transmitted as they are. An exception is 31174made for pointers to buffers for which the length isn't transmitted as 31175part of the function call, namely strings. Strings are transmitted as 31176a pointer/length pair, both as hex values, e.g. 31177 31178 `1aaf/12' 31179 31180which is a pointer to data of length 18 bytes at position 0x1aaf. The 31181length is defined as the full string length in bytes, including the 31182trailing null byte. For example, the string `"hello world"' at address 311830x123456 is transmitted as 31184 31185 `123456/d' 31186 31187 31188File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes 31189 31190Memory Transfer 31191............... 31192 31193Structured data which is transferred using a memory read or write (for 31194example, a `struct stat') is expected to be in a protocol-specific 31195format with all scalar multibyte datatypes being big endian. 31196Translation to this representation needs to be done both by the target 31197before the `F' packet is sent, and by GDB before it transfers memory to 31198the target. Transferred pointers to structured data should point to 31199the already-coerced data at any time. 31200 31201 31202File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes 31203 31204struct stat 31205........... 31206 31207The buffer of type `struct stat' used by the target and GDB is defined 31208as follows: 31209 31210 struct stat { 31211 unsigned int st_dev; /* device */ 31212 unsigned int st_ino; /* inode */ 31213 mode_t st_mode; /* protection */ 31214 unsigned int st_nlink; /* number of hard links */ 31215 unsigned int st_uid; /* user ID of owner */ 31216 unsigned int st_gid; /* group ID of owner */ 31217 unsigned int st_rdev; /* device type (if inode device) */ 31218 unsigned long st_size; /* total size, in bytes */ 31219 unsigned long st_blksize; /* blocksize for filesystem I/O */ 31220 unsigned long st_blocks; /* number of blocks allocated */ 31221 time_t st_atime; /* time of last access */ 31222 time_t st_mtime; /* time of last modification */ 31223 time_t st_ctime; /* time of last change */ 31224 }; 31225 31226 The integral datatypes conform to the definitions given in the 31227appropriate section (see *note Integral Datatypes::, for details) so 31228this structure is of size 64 bytes. 31229 31230 The values of several fields have a restricted meaning and/or range 31231of values. 31232 31233`st_dev' 31234 A value of 0 represents a file, 1 the console. 31235 31236`st_ino' 31237 No valid meaning for the target. Transmitted unchanged. 31238 31239`st_mode' 31240 Valid mode bits are described in *note Constants::. Any other 31241 bits have currently no meaning for the target. 31242 31243`st_uid' 31244`st_gid' 31245`st_rdev' 31246 No valid meaning for the target. Transmitted unchanged. 31247 31248`st_atime' 31249`st_mtime' 31250`st_ctime' 31251 These values have a host and file system dependent accuracy. 31252 Especially on Windows hosts, the file system may not support exact 31253 timing values. 31254 31255 The target gets a `struct stat' of the above representation and is 31256responsible for coercing it to the target representation before 31257continuing. 31258 31259 Note that due to size differences between the host, target, and 31260protocol representations of `struct stat' members, these members could 31261eventually get truncated on the target. 31262 31263 31264File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes 31265 31266struct timeval 31267.............. 31268 31269The buffer of type `struct timeval' used by the File-I/O protocol is 31270defined as follows: 31271 31272 struct timeval { 31273 time_t tv_sec; /* second */ 31274 long tv_usec; /* microsecond */ 31275 }; 31276 31277 The integral datatypes conform to the definitions given in the 31278appropriate section (see *note Integral Datatypes::, for details) so 31279this structure is of size 8 bytes. 31280 31281 31282File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension 31283 31284D.14.9 Constants 31285---------------- 31286 31287The following values are used for the constants inside of the protocol. 31288GDB and target are responsible for translating these values before and 31289after the call as needed. 31290 31291* Menu: 31292 31293* Open Flags:: 31294* mode_t Values:: 31295* Errno Values:: 31296* Lseek Flags:: 31297* Limits:: 31298 31299 31300File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants 31301 31302Open Flags 31303.......... 31304 31305All values are given in hexadecimal representation. 31306 31307 O_RDONLY 0x0 31308 O_WRONLY 0x1 31309 O_RDWR 0x2 31310 O_APPEND 0x8 31311 O_CREAT 0x200 31312 O_TRUNC 0x400 31313 O_EXCL 0x800 31314 31315 31316File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants 31317 31318mode_t Values 31319............. 31320 31321All values are given in octal representation. 31322 31323 S_IFREG 0100000 31324 S_IFDIR 040000 31325 S_IRUSR 0400 31326 S_IWUSR 0200 31327 S_IXUSR 0100 31328 S_IRGRP 040 31329 S_IWGRP 020 31330 S_IXGRP 010 31331 S_IROTH 04 31332 S_IWOTH 02 31333 S_IXOTH 01 31334 31335 31336File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants 31337 31338Errno Values 31339............ 31340 31341All values are given in decimal representation. 31342 31343 EPERM 1 31344 ENOENT 2 31345 EINTR 4 31346 EBADF 9 31347 EACCES 13 31348 EFAULT 14 31349 EBUSY 16 31350 EEXIST 17 31351 ENODEV 19 31352 ENOTDIR 20 31353 EISDIR 21 31354 EINVAL 22 31355 ENFILE 23 31356 EMFILE 24 31357 EFBIG 27 31358 ENOSPC 28 31359 ESPIPE 29 31360 EROFS 30 31361 ENAMETOOLONG 91 31362 EUNKNOWN 9999 31363 31364 `EUNKNOWN' is used as a fallback error value if a host system returns 31365 any error value not in the list of supported error numbers. 31366 31367 31368File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants 31369 31370Lseek Flags 31371........... 31372 31373 SEEK_SET 0 31374 SEEK_CUR 1 31375 SEEK_END 2 31376 31377 31378File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants 31379 31380Limits 31381...... 31382 31383All values are given in decimal representation. 31384 31385 INT_MIN -2147483648 31386 INT_MAX 2147483647 31387 UINT_MAX 4294967295 31388 LONG_MIN -9223372036854775808 31389 LONG_MAX 9223372036854775807 31390 ULONG_MAX 18446744073709551615 31391 31392 31393File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension 31394 31395D.14.10 File-I/O Examples 31396------------------------- 31397 31398Example sequence of a write call, file descriptor 3, buffer is at target 31399address 0x1234, 6 bytes should be written: 31400 31401 <- `Fwrite,3,1234,6' 31402 _request memory read from target_ 31403 -> `m1234,6' 31404 <- XXXXXX 31405 _return "6 bytes written"_ 31406 -> `F6' 31407 31408 Example sequence of a read call, file descriptor 3, buffer is at 31409target address 0x1234, 6 bytes should be read: 31410 31411 <- `Fread,3,1234,6' 31412 _request memory write to target_ 31413 -> `X1234,6:XXXXXX' 31414 _return "6 bytes read"_ 31415 -> `F6' 31416 31417 Example sequence of a read call, call fails on the host due to 31418invalid file descriptor (`EBADF'): 31419 31420 <- `Fread,3,1234,6' 31421 -> `F-1,9' 31422 31423 Example sequence of a read call, user presses `Ctrl-c' before 31424syscall on host is called: 31425 31426 <- `Fread,3,1234,6' 31427 -> `F-1,4,C' 31428 <- `T02' 31429 31430 Example sequence of a read call, user presses `Ctrl-c' after syscall 31431on host is called: 31432 31433 <- `Fread,3,1234,6' 31434 -> `X1234,6:XXXXXX' 31435 <- `T02' 31436 31437 31438File: gdb.info, Node: Library List Format, Next: Memory Map Format, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol 31439 31440D.15 Library List Format 31441======================== 31442 31443On some platforms, a dynamic loader (e.g. `ld.so') runs in the same 31444process as your application to manage libraries. In this case, GDB can 31445use the loader's symbol table and normal memory operations to maintain 31446a list of shared libraries. On other platforms, the operating system 31447manages loaded libraries. GDB can not retrieve the list of currently 31448loaded libraries through memory operations, so it uses the 31449`qXfer:libraries:read' packet (*note qXfer library list read::) 31450instead. The remote stub queries the target's operating system and 31451reports which libraries are loaded. 31452 31453 The `qXfer:libraries:read' packet returns an XML document which 31454lists loaded libraries and their offsets. Each library has an 31455associated name and one or more segment or section base addresses, 31456which report where the library was loaded in memory. 31457 31458 For the common case of libraries that are fully linked binaries, the 31459library should have a list of segments. If the target supports dynamic 31460linking of a relocatable object file, its library XML element should 31461instead include a list of allocated sections. The segment or section 31462bases are start addresses, not relocation offsets; they do not depend 31463on the library's link-time base addresses. 31464 31465 GDB must be linked with the Expat library to support XML library 31466lists. *Note Expat::. 31467 31468 A simple memory map, with one loaded library relocated by a single 31469offset, looks like this: 31470 31471 <library-list> 31472 <library name="/lib/libc.so.6"> 31473 <segment address="0x10000000"/> 31474 </library> 31475 </library-list> 31476 31477 Another simple memory map, with one loaded library with three 31478allocated sections (.text, .data, .bss), looks like this: 31479 31480 <library-list> 31481 <library name="sharedlib.o"> 31482 <section address="0x10000000"/> 31483 <section address="0x20000000"/> 31484 <section address="0x30000000"/> 31485 </library> 31486 </library-list> 31487 31488 The format of a library list is described by this DTD: 31489 31490 <!-- library-list: Root element with versioning --> 31491 <!ELEMENT library-list (library)*> 31492 <!ATTLIST library-list version CDATA #FIXED "1.0"> 31493 <!ELEMENT library (segment*, section*)> 31494 <!ATTLIST library name CDATA #REQUIRED> 31495 <!ELEMENT segment EMPTY> 31496 <!ATTLIST segment address CDATA #REQUIRED> 31497 <!ELEMENT section EMPTY> 31498 <!ATTLIST section address CDATA #REQUIRED> 31499 31500 In addition, segments and section descriptors cannot be mixed within 31501a single library element, and you must supply at least one segment or 31502section for each library. 31503 31504 31505File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format, Up: Remote Protocol 31506 31507D.16 Memory Map Format 31508====================== 31509 31510To be able to write into flash memory, GDB needs to obtain a memory map 31511from the target. This section describes the format of the memory map. 31512 31513 The memory map is obtained using the `qXfer:memory-map:read' (*note 31514qXfer memory map read::) packet and is an XML document that lists 31515memory regions. 31516 31517 GDB must be linked with the Expat library to support XML memory 31518maps. *Note Expat::. 31519 31520 The top-level structure of the document is shown below: 31521 31522 <?xml version="1.0"?> 31523 <!DOCTYPE memory-map 31524 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" 31525 "http://sourceware.org/gdb/gdb-memory-map.dtd"> 31526 <memory-map> 31527 region... 31528 </memory-map> 31529 31530 Each region can be either: 31531 31532 * A region of RAM starting at ADDR and extending for LENGTH bytes 31533 from there: 31534 31535 <memory type="ram" start="ADDR" length="LENGTH"/> 31536 31537 * A region of read-only memory: 31538 31539 <memory type="rom" start="ADDR" length="LENGTH"/> 31540 31541 * A region of flash memory, with erasure blocks BLOCKSIZE bytes in 31542 length: 31543 31544 <memory type="flash" start="ADDR" length="LENGTH"> 31545 <property name="blocksize">BLOCKSIZE</property> 31546 </memory> 31547 31548 31549 Regions must not overlap. GDB assumes that areas of memory not 31550covered by the memory map are RAM, and uses the ordinary `M' and `X' 31551packets to write to addresses in such ranges. 31552 31553 The formal DTD for memory map format is given below: 31554 31555 <!-- ................................................... --> 31556 <!-- Memory Map XML DTD ................................ --> 31557 <!-- File: memory-map.dtd .............................. --> 31558 <!-- .................................... .............. --> 31559 <!-- memory-map.dtd --> 31560 <!-- memory-map: Root element with versioning --> 31561 <!ELEMENT memory-map (memory | property)> 31562 <!ATTLIST memory-map version CDATA #FIXED "1.0.0"> 31563 <!ELEMENT memory (property)> 31564 <!-- memory: Specifies a memory region, 31565 and its type, or device. --> 31566 <!ATTLIST memory type CDATA #REQUIRED 31567 start CDATA #REQUIRED 31568 length CDATA #REQUIRED 31569 device CDATA #IMPLIED> 31570 <!-- property: Generic attribute tag --> 31571 <!ELEMENT property (#PCDATA | property)*> 31572 <!ATTLIST property name CDATA #REQUIRED> 31573 31574 31575File: gdb.info, Node: Thread List Format, Prev: Memory Map Format, Up: Remote Protocol 31576 31577D.17 Thread List Format 31578======================= 31579 31580To efficiently update the list of threads and their attributes, GDB 31581issues the `qXfer:threads:read' packet (*note qXfer threads read::) and 31582obtains the XML document with the following structure: 31583 31584 <?xml version="1.0"?> 31585 <threads> 31586 <thread id="id" core="0"> 31587 ... description ... 31588 </thread> 31589 </threads> 31590 31591 Each `thread' element must have the `id' attribute that identifies 31592the thread (*note thread-id syntax::). The `core' attribute, if 31593present, specifies which processor core the thread was last executing 31594on. The content of the of `thread' element is interpreted as 31595human-readable auxilliary information. 31596 31597 31598File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top 31599 31600Appendix E The GDB Agent Expression Mechanism 31601********************************************* 31602 31603In some applications, it is not feasible for the debugger to interrupt 31604the program's execution long enough for the developer to learn anything 31605helpful about its behavior. If the program's correctness depends on its 31606real-time behavior, delays introduced by a debugger might cause the 31607program to fail, even when the code itself is correct. It is useful to 31608be able to observe the program's behavior without interrupting it. 31609 31610 Using GDB's `trace' and `collect' commands, the user can specify 31611locations in the program, and arbitrary expressions to evaluate when 31612those locations are reached. Later, using the `tfind' command, she can 31613examine the values those expressions had when the program hit the trace 31614points. The expressions may also denote objects in memory -- 31615structures or arrays, for example -- whose values GDB should record; 31616while visiting a particular tracepoint, the user may inspect those 31617objects as if they were in memory at that moment. However, because GDB 31618records these values without interacting with the user, it can do so 31619quickly and unobtrusively, hopefully not disturbing the program's 31620behavior. 31621 31622 When GDB is debugging a remote target, the GDB "agent" code running 31623on the target computes the values of the expressions itself. To avoid 31624having a full symbolic expression evaluator on the agent, GDB translates 31625expressions in the source language into a simpler bytecode language, and 31626then sends the bytecode to the agent; the agent then executes the 31627bytecode, and records the values for GDB to retrieve later. 31628 31629 The bytecode language is simple; there are forty-odd opcodes, the 31630bulk of which are the usual vocabulary of C operands (addition, 31631subtraction, shifts, and so on) and various sizes of literals and 31632memory reference operations. The bytecode interpreter operates 31633strictly on machine-level values -- various sizes of integers and 31634floating point numbers -- and requires no information about types or 31635symbols; thus, the interpreter's internal data structures are simple, 31636and each bytecode requires only a few native machine instructions to 31637implement it. The interpreter is small, and strict limits on the 31638memory and time required to evaluate an expression are easy to 31639determine, making it suitable for use by the debugging agent in 31640real-time applications. 31641 31642* Menu: 31643 31644* General Bytecode Design:: Overview of the interpreter. 31645* Bytecode Descriptions:: What each one does. 31646* Using Agent Expressions:: How agent expressions fit into the big picture. 31647* Varying Target Capabilities:: How to discover what the target can do. 31648* Rationale:: Why we did it this way. 31649 31650 31651File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions 31652 31653E.1 General Bytecode Design 31654=========================== 31655 31656The agent represents bytecode expressions as an array of bytes. Each 31657instruction is one byte long (thus the term "bytecode"). Some 31658instructions are followed by operand bytes; for example, the `goto' 31659instruction is followed by a destination for the jump. 31660 31661 The bytecode interpreter is a stack-based machine; most instructions 31662pop their operands off the stack, perform some operation, and push the 31663result back on the stack for the next instruction to consume. Each 31664element of the stack may contain either a integer or a floating point 31665value; these values are as many bits wide as the largest integer that 31666can be directly manipulated in the source language. Stack elements 31667carry no record of their type; bytecode could push a value as an 31668integer, then pop it as a floating point value. However, GDB will not 31669generate code which does this. In C, one might define the type of a 31670stack element as follows: 31671 union agent_val { 31672 LONGEST l; 31673 DOUBLEST d; 31674 }; 31675 where `LONGEST' and `DOUBLEST' are `typedef' names for the largest 31676integer and floating point types on the machine. 31677 31678 By the time the bytecode interpreter reaches the end of the 31679expression, the value of the expression should be the only value left 31680on the stack. For tracing applications, `trace' bytecodes in the 31681expression will have recorded the necessary data, and the value on the 31682stack may be discarded. For other applications, like conditional 31683breakpoints, the value may be useful. 31684 31685 Separate from the stack, the interpreter has two registers: 31686`pc' 31687 The address of the next bytecode to execute. 31688 31689`start' 31690 The address of the start of the bytecode expression, necessary for 31691 interpreting the `goto' and `if_goto' instructions. 31692 31693 Neither of these registers is directly visible to the bytecode 31694language itself, but they are useful for defining the meanings of the 31695bytecode operations. 31696 31697 There are no instructions to perform side effects on the running 31698program, or call the program's functions; we assume that these 31699expressions are only used for unobtrusive debugging, not for patching 31700the running code. 31701 31702 Most bytecode instructions do not distinguish between the various 31703sizes of values, and operate on full-width values; the upper bits of the 31704values are simply ignored, since they do not usually make a difference 31705to the value computed. The exceptions to this rule are: 31706memory reference instructions (`ref'N) 31707 There are distinct instructions to fetch different word sizes from 31708 memory. Once on the stack, however, the values are treated as 31709 full-size integers. They may need to be sign-extended; the `ext' 31710 instruction exists for this purpose. 31711 31712the sign-extension instruction (`ext' N) 31713 These clearly need to know which portion of their operand is to be 31714 extended to occupy the full length of the word. 31715 31716 31717 If the interpreter is unable to evaluate an expression completely for 31718some reason (a memory location is inaccessible, or a divisor is zero, 31719for example), we say that interpretation "terminates with an error". 31720This means that the problem is reported back to the interpreter's caller 31721in some helpful way. In general, code using agent expressions should 31722assume that they may attempt to divide by zero, fetch arbitrary memory 31723locations, and misbehave in other ways. 31724 31725 Even complicated C expressions compile to a few bytecode 31726instructions; for example, the expression `x + y * z' would typically 31727produce code like the following, assuming that `x' and `y' live in 31728registers, and `z' is a global variable holding a 32-bit `int': 31729 reg 1 31730 reg 2 31731 const32 address of z 31732 ref32 31733 ext 32 31734 mul 31735 add 31736 end 31737 31738 In detail, these mean: 31739`reg 1' 31740 Push the value of register 1 (presumably holding `x') onto the 31741 stack. 31742 31743`reg 2' 31744 Push the value of register 2 (holding `y'). 31745 31746`const32 address of z' 31747 Push the address of `z' onto the stack. 31748 31749`ref32' 31750 Fetch a 32-bit word from the address at the top of the stack; 31751 replace the address on the stack with the value. Thus, we replace 31752 the address of `z' with `z''s value. 31753 31754`ext 32' 31755 Sign-extend the value on the top of the stack from 32 bits to full 31756 length. This is necessary because `z' is a signed integer. 31757 31758`mul' 31759 Pop the top two numbers on the stack, multiply them, and push their 31760 product. Now the top of the stack contains the value of the 31761 expression `y * z'. 31762 31763`add' 31764 Pop the top two numbers, add them, and push the sum. Now the top 31765 of the stack contains the value of `x + y * z'. 31766 31767`end' 31768 Stop executing; the value left on the stack top is the value to be 31769 recorded. 31770 31771 31772 31773File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions 31774 31775E.2 Bytecode Descriptions 31776========================= 31777 31778Each bytecode description has the following form: 31779 31780`add' (0x02): A B => A+B 31781 Pop the top two stack items, A and B, as integers; push their sum, 31782 as an integer. 31783 31784 31785 In this example, `add' is the name of the bytecode, and `(0x02)' is 31786the one-byte value used to encode the bytecode, in hexadecimal. The 31787phrase "A B => A+B" shows the stack before and after the bytecode 31788executes. Beforehand, the stack must contain at least two values, A 31789and B; since the top of the stack is to the right, B is on the top of 31790the stack, and A is underneath it. After execution, the bytecode will 31791have popped A and B from the stack, and replaced them with a single 31792value, A+B. There may be other values on the stack below those shown, 31793but the bytecode affects only those shown. 31794 31795 Here is another example: 31796 31797`const8' (0x22) N: => N 31798 Push the 8-bit integer constant N on the stack, without sign 31799 extension. 31800 31801 31802 In this example, the bytecode `const8' takes an operand N directly 31803from the bytecode stream; the operand follows the `const8' bytecode 31804itself. We write any such operands immediately after the name of the 31805bytecode, before the colon, and describe the exact encoding of the 31806operand in the bytecode stream in the body of the bytecode description. 31807 31808 For the `const8' bytecode, there are no stack items given before the 31809=>; this simply means that the bytecode consumes no values from the 31810stack. If a bytecode consumes no values, or produces no values, the 31811list on either side of the => may be empty. 31812 31813 If a value is written as A, B, or N, then the bytecode treats it as 31814an integer. If a value is written is ADDR, then the bytecode treats it 31815as an address. 31816 31817 We do not fully describe the floating point operations here; although 31818this design can be extended in a clean way to handle floating point 31819values, they are not of immediate interest to the customer, so we avoid 31820describing them, to save time. 31821 31822`float' (0x01): => 31823 Prefix for floating-point bytecodes. Not implemented yet. 31824 31825`add' (0x02): A B => A+B 31826 Pop two integers from the stack, and push their sum, as an integer. 31827 31828`sub' (0x03): A B => A-B 31829 Pop two integers from the stack, subtract the top value from the 31830 next-to-top value, and push the difference. 31831 31832`mul' (0x04): A B => A*B 31833 Pop two integers from the stack, multiply them, and push the 31834 product on the stack. Note that, when one multiplies two N-bit 31835 numbers yielding another N-bit number, it is irrelevant whether the 31836 numbers are signed or not; the results are the same. 31837 31838`div_signed' (0x05): A B => A/B 31839 Pop two signed integers from the stack; divide the next-to-top 31840 value by the top value, and push the quotient. If the divisor is 31841 zero, terminate with an error. 31842 31843`div_unsigned' (0x06): A B => A/B 31844 Pop two unsigned integers from the stack; divide the next-to-top 31845 value by the top value, and push the quotient. If the divisor is 31846 zero, terminate with an error. 31847 31848`rem_signed' (0x07): A B => A MODULO B 31849 Pop two signed integers from the stack; divide the next-to-top 31850 value by the top value, and push the remainder. If the divisor is 31851 zero, terminate with an error. 31852 31853`rem_unsigned' (0x08): A B => A MODULO B 31854 Pop two unsigned integers from the stack; divide the next-to-top 31855 value by the top value, and push the remainder. If the divisor is 31856 zero, terminate with an error. 31857 31858`lsh' (0x09): A B => A<<B 31859 Pop two integers from the stack; let A be the next-to-top value, 31860 and B be the top value. Shift A left by B bits, and push the 31861 result. 31862 31863`rsh_signed' (0x0a): A B => `(signed)'A>>B 31864 Pop two integers from the stack; let A be the next-to-top value, 31865 and B be the top value. Shift A right by B bits, inserting copies 31866 of the top bit at the high end, and push the result. 31867 31868`rsh_unsigned' (0x0b): A B => A>>B 31869 Pop two integers from the stack; let A be the next-to-top value, 31870 and B be the top value. Shift A right by B bits, inserting zero 31871 bits at the high end, and push the result. 31872 31873`log_not' (0x0e): A => !A 31874 Pop an integer from the stack; if it is zero, push the value one; 31875 otherwise, push the value zero. 31876 31877`bit_and' (0x0f): A B => A&B 31878 Pop two integers from the stack, and push their bitwise `and'. 31879 31880`bit_or' (0x10): A B => A|B 31881 Pop two integers from the stack, and push their bitwise `or'. 31882 31883`bit_xor' (0x11): A B => A^B 31884 Pop two integers from the stack, and push their bitwise 31885 exclusive-`or'. 31886 31887`bit_not' (0x12): A => ~A 31888 Pop an integer from the stack, and push its bitwise complement. 31889 31890`equal' (0x13): A B => A=B 31891 Pop two integers from the stack; if they are equal, push the value 31892 one; otherwise, push the value zero. 31893 31894`less_signed' (0x14): A B => A<B 31895 Pop two signed integers from the stack; if the next-to-top value 31896 is less than the top value, push the value one; otherwise, push 31897 the value zero. 31898 31899`less_unsigned' (0x15): A B => A<B 31900 Pop two unsigned integers from the stack; if the next-to-top value 31901 is less than the top value, push the value one; otherwise, push 31902 the value zero. 31903 31904`ext' (0x16) N: A => A, sign-extended from N bits 31905 Pop an unsigned value from the stack; treating it as an N-bit 31906 twos-complement value, extend it to full length. This means that 31907 all bits to the left of bit N-1 (where the least significant bit 31908 is bit 0) are set to the value of bit N-1. Note that N may be 31909 larger than or equal to the width of the stack elements of the 31910 bytecode engine; in this case, the bytecode should have no effect. 31911 31912 The number of source bits to preserve, N, is encoded as a single 31913 byte unsigned integer following the `ext' bytecode. 31914 31915`zero_ext' (0x2a) N: A => A, zero-extended from N bits 31916 Pop an unsigned value from the stack; zero all but the bottom N 31917 bits. This means that all bits to the left of bit N-1 (where the 31918 least significant bit is bit 0) are set to the value of bit N-1. 31919 31920 The number of source bits to preserve, N, is encoded as a single 31921 byte unsigned integer following the `zero_ext' bytecode. 31922 31923`ref8' (0x17): ADDR => A 31924`ref16' (0x18): ADDR => A 31925`ref32' (0x19): ADDR => A 31926`ref64' (0x1a): ADDR => A 31927 Pop an address ADDR from the stack. For bytecode `ref'N, fetch an 31928 N-bit value from ADDR, using the natural target endianness. Push 31929 the fetched value as an unsigned integer. 31930 31931 Note that ADDR may not be aligned in any particular way; the 31932 `refN' bytecodes should operate correctly for any address. 31933 31934 If attempting to access memory at ADDR would cause a processor 31935 exception of some sort, terminate with an error. 31936 31937`ref_float' (0x1b): ADDR => D 31938`ref_double' (0x1c): ADDR => D 31939`ref_long_double' (0x1d): ADDR => D 31940`l_to_d' (0x1e): A => D 31941`d_to_l' (0x1f): D => A 31942 Not implemented yet. 31943 31944`dup' (0x28): A => A A 31945 Push another copy of the stack's top element. 31946 31947`swap' (0x2b): A B => B A 31948 Exchange the top two items on the stack. 31949 31950`pop' (0x29): A => 31951 Discard the top value on the stack. 31952 31953`if_goto' (0x20) OFFSET: A => 31954 Pop an integer off the stack; if it is non-zero, branch to the 31955 given offset in the bytecode string. Otherwise, continue to the 31956 next instruction in the bytecode stream. In other words, if A is 31957 non-zero, set the `pc' register to `start' + OFFSET. Thus, an 31958 offset of zero denotes the beginning of the expression. 31959 31960 The OFFSET is stored as a sixteen-bit unsigned value, stored 31961 immediately following the `if_goto' bytecode. It is always stored 31962 most significant byte first, regardless of the target's normal 31963 endianness. The offset is not guaranteed to fall at any particular 31964 alignment within the bytecode stream; thus, on machines where 31965 fetching a 16-bit on an unaligned address raises an exception, you 31966 should fetch the offset one byte at a time. 31967 31968`goto' (0x21) OFFSET: => 31969 Branch unconditionally to OFFSET; in other words, set the `pc' 31970 register to `start' + OFFSET. 31971 31972 The offset is stored in the same way as for the `if_goto' bytecode. 31973 31974`const8' (0x22) N: => N 31975`const16' (0x23) N: => N 31976`const32' (0x24) N: => N 31977`const64' (0x25) N: => N 31978 Push the integer constant N on the stack, without sign extension. 31979 To produce a small negative value, push a small twos-complement 31980 value, and then sign-extend it using the `ext' bytecode. 31981 31982 The constant N is stored in the appropriate number of bytes 31983 following the `const'B bytecode. The constant N is always stored 31984 most significant byte first, regardless of the target's normal 31985 endianness. The constant is not guaranteed to fall at any 31986 particular alignment within the bytecode stream; thus, on machines 31987 where fetching a 16-bit on an unaligned address raises an 31988 exception, you should fetch N one byte at a time. 31989 31990`reg' (0x26) N: => A 31991 Push the value of register number N, without sign extension. The 31992 registers are numbered following GDB's conventions. 31993 31994 The register number N is encoded as a 16-bit unsigned integer 31995 immediately following the `reg' bytecode. It is always stored most 31996 significant byte first, regardless of the target's normal 31997 endianness. The register number is not guaranteed to fall at any 31998 particular alignment within the bytecode stream; thus, on machines 31999 where fetching a 16-bit on an unaligned address raises an 32000 exception, you should fetch the register number one byte at a time. 32001 32002`getv' (0x2c) N: => V 32003 Push the value of trace state variable number N, without sign 32004 extension. 32005 32006 The variable number N is encoded as a 16-bit unsigned integer 32007 immediately following the `getv' bytecode. It is always stored 32008 most significant byte first, regardless of the target's normal 32009 endianness. The variable number is not guaranteed to fall at any 32010 particular alignment within the bytecode stream; thus, on machines 32011 where fetching a 16-bit on an unaligned address raises an 32012 exception, you should fetch the register number one byte at a time. 32013 32014`setv' (0x2d) N: => V 32015 Set trace state variable number N to the value found on the top of 32016 the stack. The stack is unchanged, so that the value is readily 32017 available if the assignment is part of a larger expression. The 32018 handling of N is as described for `getv'. 32019 32020`trace' (0x0c): ADDR SIZE => 32021 Record the contents of the SIZE bytes at ADDR in a trace buffer, 32022 for later retrieval by GDB. 32023 32024`trace_quick' (0x0d) SIZE: ADDR => ADDR 32025 Record the contents of the SIZE bytes at ADDR in a trace buffer, 32026 for later retrieval by GDB. SIZE is a single byte unsigned 32027 integer following the `trace' opcode. 32028 32029 This bytecode is equivalent to the sequence `dup const8 SIZE 32030 trace', but we provide it anyway to save space in bytecode strings. 32031 32032`trace16' (0x30) SIZE: ADDR => ADDR 32033 Identical to trace_quick, except that SIZE is a 16-bit big-endian 32034 unsigned integer, not a single byte. This should probably have 32035 been named `trace_quick16', for consistency. 32036 32037`tracev' (0x2e) N: => A 32038 Record the value of trace state variable number N in the trace 32039 buffer. The handling of N is as described for `getv'. 32040 32041`end' (0x27): => 32042 Stop executing bytecode; the result should be the top element of 32043 the stack. If the purpose of the expression was to compute an 32044 lvalue or a range of memory, then the next-to-top of the stack is 32045 the lvalue's address, and the top of the stack is the lvalue's 32046 size, in bytes. 32047 32048 32049 32050File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions 32051 32052E.3 Using Agent Expressions 32053=========================== 32054 32055Agent expressions can be used in several different ways by GDB, and the 32056debugger can generate different bytecode sequences as appropriate. 32057 32058 One possibility is to do expression evaluation on the target rather 32059than the host, such as for the conditional of a conditional tracepoint. 32060In such a case, GDB compiles the source expression into a bytecode 32061sequence that simply gets values from registers or memory, does 32062arithmetic, and returns a result. 32063 32064 Another way to use agent expressions is for tracepoint data 32065collection. GDB generates a different bytecode sequence for 32066collection; in addition to bytecodes that do the calculation, GDB adds 32067`trace' bytecodes to save the pieces of memory that were used. 32068 32069 * The user selects trace points in the program's code at which GDB 32070 should collect data. 32071 32072 * The user specifies expressions to evaluate at each trace point. 32073 These expressions may denote objects in memory, in which case 32074 those objects' contents are recorded as the program runs, or 32075 computed values, in which case the values themselves are recorded. 32076 32077 * GDB transmits the tracepoints and their associated expressions to 32078 the GDB agent, running on the debugging target. 32079 32080 * The agent arranges to be notified when a trace point is hit. 32081 32082 * When execution on the target reaches a trace point, the agent 32083 evaluates the expressions associated with that trace point, and 32084 records the resulting values and memory ranges. 32085 32086 * Later, when the user selects a given trace event and inspects the 32087 objects and expression values recorded, GDB talks to the agent to 32088 retrieve recorded data as necessary to meet the user's requests. 32089 If the user asks to see an object whose contents have not been 32090 recorded, GDB reports an error. 32091 32092 32093 32094File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions 32095 32096E.4 Varying Target Capabilities 32097=============================== 32098 32099Some targets don't support floating-point, and some would rather not 32100have to deal with `long long' operations. Also, different targets will 32101have different stack sizes, and different bytecode buffer lengths. 32102 32103 Thus, GDB needs a way to ask the target about itself. We haven't 32104worked out the details yet, but in general, GDB should be able to send 32105the target a packet asking it to describe itself. The reply should be a 32106packet whose length is explicit, so we can add new information to the 32107packet in future revisions of the agent, without confusing old versions 32108of GDB, and it should contain a version number. It should contain at 32109least the following information: 32110 32111 * whether floating point is supported 32112 32113 * whether `long long' is supported 32114 32115 * maximum acceptable size of bytecode stack 32116 32117 * maximum acceptable length of bytecode expressions 32118 32119 * which registers are actually available for collection 32120 32121 * whether the target supports disabled tracepoints 32122 32123 32124 32125File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions 32126 32127E.5 Rationale 32128============= 32129 32130Some of the design decisions apparent above are arguable. 32131 32132What about stack overflow/underflow? 32133 GDB should be able to query the target to discover its stack size. 32134 Given that information, GDB can determine at translation time 32135 whether a given expression will overflow the stack. But this spec 32136 isn't about what kinds of error-checking GDB ought to do. 32137 32138Why are you doing everything in LONGEST? 32139 Speed isn't important, but agent code size is; using LONGEST 32140 brings in a bunch of support code to do things like division, etc. 32141 So this is a serious concern. 32142 32143 First, note that you don't need different bytecodes for different 32144 operand sizes. You can generate code without _knowing_ how big the 32145 stack elements actually are on the target. If the target only 32146 supports 32-bit ints, and you don't send any 64-bit bytecodes, 32147 everything just works. The observation here is that the MIPS and 32148 the Alpha have only fixed-size registers, and you can still get 32149 C's semantics even though most instructions only operate on 32150 full-sized words. You just need to make sure everything is 32151 properly sign-extended at the right times. So there is no need 32152 for 32- and 64-bit variants of the bytecodes. Just implement 32153 everything using the largest size you support. 32154 32155 GDB should certainly check to see what sizes the target supports, 32156 so the user can get an error earlier, rather than later. But this 32157 information is not necessary for correctness. 32158 32159Why don't you have `>' or `<=' operators? 32160 I want to keep the interpreter small, and we don't need them. We 32161 can combine the `less_' opcodes with `log_not', and swap the order 32162 of the operands, yielding all four asymmetrical comparison 32163 operators. For example, `(x <= y)' is `! (x > y)', which is `! (y 32164 < x)'. 32165 32166Why do you have `log_not'? 32167Why do you have `ext'? 32168Why do you have `zero_ext'? 32169 These are all easily synthesized from other instructions, but I 32170 expect them to be used frequently, and they're simple, so I 32171 include them to keep bytecode strings short. 32172 32173 `log_not' is equivalent to `const8 0 equal'; it's used in half the 32174 relational operators. 32175 32176 `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed', 32177 where S is the size of the stack elements; it follows `refM' and 32178 REG bytecodes when the value should be signed. See the next 32179 bulleted item. 32180 32181 `zero_ext N' is equivalent to `constM MASK log_and'; it's used 32182 whenever we push the value of a register, because we can't assume 32183 the upper bits of the register aren't garbage. 32184 32185Why not have sign-extending variants of the `ref' operators? 32186 Because that would double the number of `ref' operators, and we 32187 need the `ext' bytecode anyway for accessing bitfields. 32188 32189Why not have constant-address variants of the `ref' operators? 32190 Because that would double the number of `ref' operators again, and 32191 `const32 ADDRESS ref32' is only one byte longer. 32192 32193Why do the `refN' operators have to support unaligned fetches? 32194 GDB will generate bytecode that fetches multi-byte values at 32195 unaligned addresses whenever the executable's debugging 32196 information tells it to. Furthermore, GDB does not know the value 32197 the pointer will have when GDB generates the bytecode, so it 32198 cannot determine whether a particular fetch will be aligned or not. 32199 32200 In particular, structure bitfields may be several bytes long, but 32201 follow no alignment rules; members of packed structures are not 32202 necessarily aligned either. 32203 32204 In general, there are many cases where unaligned references occur 32205 in correct C code, either at the programmer's explicit request, or 32206 at the compiler's discretion. Thus, it is simpler to make the GDB 32207 agent bytecodes work correctly in all circumstances than to make 32208 GDB guess in each case whether the compiler did the usual thing. 32209 32210Why are there no side-effecting operators? 32211 Because our current client doesn't want them? That's a cheap 32212 answer. I think the real answer is that I'm afraid of 32213 implementing function calls. We should re-visit this issue after 32214 the present contract is delivered. 32215 32216Why aren't the `goto' ops PC-relative? 32217 The interpreter has the base address around anyway for PC bounds 32218 checking, and it seemed simpler. 32219 32220Why is there only one offset size for the `goto' ops? 32221 Offsets are currently sixteen bits. I'm not happy with this 32222 situation either: 32223 32224 Suppose we have multiple branch ops with different offset sizes. 32225 As I generate code left-to-right, all my jumps are forward jumps 32226 (there are no loops in expressions), so I never know the target 32227 when I emit the jump opcode. Thus, I have to either always assume 32228 the largest offset size, or do jump relaxation on the code after I 32229 generate it, which seems like a big waste of time. 32230 32231 I can imagine a reasonable expression being longer than 256 bytes. 32232 I can't imagine one being longer than 64k. Thus, we need 16-bit 32233 offsets. This kind of reasoning is so bogus, but relaxation is 32234 pathetic. 32235 32236 The other approach would be to generate code right-to-left. Then 32237 I'd always know my offset size. That might be fun. 32238 32239Where is the function call bytecode? 32240 When we add side-effects, we should add this. 32241 32242Why does the `reg' bytecode take a 16-bit register number? 32243 Intel's IA-64 architecture has 128 general-purpose registers, and 32244 128 floating-point registers, and I'm sure it has some random 32245 control registers. 32246 32247Why do we need `trace' and `trace_quick'? 32248 Because GDB needs to record all the memory contents and registers 32249 an expression touches. If the user wants to evaluate an expression 32250 `x->y->z', the agent must record the values of `x' and `x->y' as 32251 well as the value of `x->y->z'. 32252 32253Don't the `trace' bytecodes make the interpreter less general? 32254 They do mean that the interpreter contains special-purpose code, 32255 but that doesn't mean the interpreter can only be used for that 32256 purpose. If an expression doesn't use the `trace' bytecodes, they 32257 don't get in its way. 32258 32259Why doesn't `trace_quick' consume its arguments the way everything else does? 32260 In general, you do want your operators to consume their arguments; 32261 it's consistent, and generally reduces the amount of stack 32262 rearrangement necessary. However, `trace_quick' is a kludge to 32263 save space; it only exists so we needn't write `dup const8 SIZE 32264 trace' before every memory reference. Therefore, it's okay for it 32265 not to consume its arguments; it's meant for a specific context in 32266 which we know exactly what it should do with the stack. If we're 32267 going to have a kludge, it should be an effective kludge. 32268 32269Why does `trace16' exist? 32270 That opcode was added by the customer that contracted Cygnus for 32271 the data tracing work. I personally think it is unnecessary; 32272 objects that large will be quite rare, so it is okay to use `dup 32273 const16 SIZE trace' in those cases. 32274 32275 Whatever we decide to do with `trace16', we should at least leave 32276 opcode 0x30 reserved, to remain compatible with the customer who 32277 added it. 32278 32279 32280 32281File: gdb.info, Node: Trace File Format, Next: Copying, Prev: Operating System Information, Up: Top 32282 32283Appendix F Trace File Format 32284**************************** 32285 32286The trace file comes in three parts: a header, a textual description 32287section, and a trace frame section with binary data. 32288 32289 The header has the form `\x7fTRACE0\n'. The first byte is `0x7f' so 32290as to indicate that the file contains binary data, while the `0' is a 32291version number that may have different values in the future. 32292 32293 The description section consists of multiple lines of ASCII text 32294separated by newline characters (`0xa'). The lines may include a 32295variety of optional descriptive or context-setting information, such as 32296tracepoint definitions or register set size. GDB will ignore any line 32297that it does not recognize. An empty line marks the end of this 32298section. 32299 32300 The trace frame section consists of a number of consecutive frames. 32301Each frame begins with a two-byte tracepoint number, followed by a 32302four-byte size giving the amount of data in the frame. The data in the 32303frame consists of a number of blocks, each introduced by a character 32304indicating its type (at least register, memory, and trace state 32305variable). The data in this section is raw binary, not a hexadecimal 32306or other encoding; its endianness matches the target's endianness. 32307 32308`R BYTES' 32309 Register block. The number and ordering of bytes matches that of a 32310 `g' packet in the remote protocol. Note that these are the actual 32311 bytes, in target order and GDB register order, not a hexadecimal 32312 encoding. 32313 32314`M ADDRESS LENGTH BYTES...' 32315 Memory block. This is a contiguous block of memory, at the 8-byte 32316 address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH 32317 bytes. 32318 32319`V NUMBER VALUE' 32320 Trace state variable block. This records the 8-byte signed value 32321 VALUE of trace state variable numbered NUMBER. 32322 32323 32324 Future enhancements of the trace file format may include additional 32325types of blocks. 32326 32327 32328File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top 32329 32330Appendix G Target Descriptions 32331****************************** 32332 32333*Warning:* target descriptions are still under active development, and 32334the contents and format may change between GDB releases. The format is 32335expected to stabilize in the future. 32336 32337 One of the challenges of using GDB to debug embedded systems is that 32338there are so many minor variants of each processor architecture in use. 32339It is common practice for vendors to start with a standard processor 32340core -- ARM, PowerPC, or MIPS, for example -- and then make changes to 32341adapt it to a particular market niche. Some architectures have 32342hundreds of variants, available from dozens of vendors. This leads to 32343a number of problems: 32344 32345 * With so many different customized processors, it is difficult for 32346 the GDB maintainers to keep up with the changes. 32347 32348 * Since individual variants may have short lifetimes or limited 32349 audiences, it may not be worthwhile to carry information about 32350 every variant in the GDB source tree. 32351 32352 * When GDB does support the architecture of the embedded system at 32353 hand, the task of finding the correct architecture name to give the 32354 `set architecture' command can be error-prone. 32355 32356 To address these problems, the GDB remote protocol allows a target 32357system to not only identify itself to GDB, but to actually describe its 32358own features. This lets GDB support processor variants it has never 32359seen before -- to the extent that the descriptions are accurate, and 32360that GDB understands them. 32361 32362 GDB must be linked with the Expat library to support XML target 32363descriptions. *Note Expat::. 32364 32365* Menu: 32366 32367* Retrieving Descriptions:: How descriptions are fetched from a target. 32368* Target Description Format:: The contents of a target description. 32369* Predefined Target Types:: Standard types available for target 32370 descriptions. 32371* Standard Target Features:: Features GDB knows about. 32372 32373 32374File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions 32375 32376G.1 Retrieving Descriptions 32377=========================== 32378 32379Target descriptions can be read from the target automatically, or 32380specified by the user manually. The default behavior is to read the 32381description from the target. GDB retrieves it via the remote protocol 32382using `qXfer' requests (*note qXfer: General Query Packets.). The 32383ANNEX in the `qXfer' packet will be `target.xml'. The contents of the 32384`target.xml' annex are an XML document, of the form described in *note 32385Target Description Format::. 32386 32387 Alternatively, you can specify a file to read for the target 32388description. If a file is set, the target will not be queried. The 32389commands to specify a file are: 32390 32391`set tdesc filename PATH' 32392 Read the target description from PATH. 32393 32394`unset tdesc filename' 32395 Do not read the XML target description from a file. GDB will use 32396 the description supplied by the current target. 32397 32398`show tdesc filename' 32399 Show the filename to read for a target description, if any. 32400 32401 32402File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions 32403 32404G.2 Target Description Format 32405============================= 32406 32407A target description annex is an XML (http://www.w3.org/XML/) document 32408which complies with the Document Type Definition provided in the GDB 32409sources in `gdb/features/gdb-target.dtd'. This means you can use 32410generally available tools like `xmllint' to check that your feature 32411descriptions are well-formed and valid. However, to help people 32412unfamiliar with XML write descriptions for their targets, we also 32413describe the grammar here. 32414 32415 Target descriptions can identify the architecture of the remote 32416target and (for some architectures) provide information about custom 32417register sets. They can also identify the OS ABI of the remote target. 32418GDB can use this information to autoconfigure for your target, or to 32419warn you if you connect to an unsupported target. 32420 32421 Here is a simple target description: 32422 32423 <target version="1.0"> 32424 <architecture>i386:x86-64</architecture> 32425 </target> 32426 32427This minimal description only says that the target uses the x86-64 32428architecture. 32429 32430 A target description has the following overall form, with [ ] marking 32431optional elements and ... marking repeatable elements. The elements 32432are explained further below. 32433 32434 <?xml version="1.0"?> 32435 <!DOCTYPE target SYSTEM "gdb-target.dtd"> 32436 <target version="1.0"> 32437 [ARCHITECTURE] 32438 [OSABI] 32439 [COMPATIBLE] 32440 [FEATURE...] 32441 </target> 32442 32443The description is generally insensitive to whitespace and line breaks, 32444under the usual common-sense rules. The XML version declaration and 32445document type declaration can generally be omitted (GDB does not 32446require them), but specifying them may be useful for XML validation 32447tools. The `version' attribute for `<target>' may also be omitted, but 32448we recommend including it; if future versions of GDB use an incompatible 32449revision of `gdb-target.dtd', they will detect and report the version 32450mismatch. 32451 32452G.2.1 Inclusion 32453--------------- 32454 32455It can sometimes be valuable to split a target description up into 32456several different annexes, either for organizational purposes, or to 32457share files between different possible target descriptions. You can 32458divide a description into multiple files by replacing any element of 32459the target description with an inclusion directive of the form: 32460 32461 <xi:include href="DOCUMENT"/> 32462 32463When GDB encounters an element of this form, it will retrieve the named 32464XML DOCUMENT, and replace the inclusion directive with the contents of 32465that document. If the current description was read using `qXfer', then 32466so will be the included document; DOCUMENT will be interpreted as the 32467name of an annex. If the current description was read from a file, GDB 32468will look for DOCUMENT as a file in the same directory where it found 32469the original description. 32470 32471G.2.2 Architecture 32472------------------ 32473 32474An `<architecture>' element has this form: 32475 32476 <architecture>ARCH</architecture> 32477 32478 ARCH is one of the architectures from the set accepted by `set 32479architecture' (*note Specifying a Debugging Target: Targets.). 32480 32481G.2.3 OS ABI 32482------------ 32483 32484This optional field was introduced in GDB version 7.0. Previous 32485versions of GDB ignore it. 32486 32487 An `<osabi>' element has this form: 32488 32489 <osabi>ABI-NAME</osabi> 32490 32491 ABI-NAME is an OS ABI name from the same selection accepted by 32492`set osabi' (*note Configuring the Current ABI: ABI.). 32493 32494G.2.4 Compatible Architecture 32495----------------------------- 32496 32497This optional field was introduced in GDB version 7.0. Previous 32498versions of GDB ignore it. 32499 32500 A `<compatible>' element has this form: 32501 32502 <compatible>ARCH</compatible> 32503 32504 ARCH is one of the architectures from the set accepted by `set 32505architecture' (*note Specifying a Debugging Target: Targets.). 32506 32507 A `<compatible>' element is used to specify that the target is able 32508to run binaries in some other than the main target architecture given 32509by the `<architecture>' element. For example, on the Cell Broadband 32510Engine, the main architecture is `powerpc:common' or 32511`powerpc:common64', but the system is able to run binaries in the `spu' 32512architecture as well. The way to describe this capability with 32513`<compatible>' is as follows: 32514 32515 <architecture>powerpc:common</architecture> 32516 <compatible>spu</compatible> 32517 32518G.2.5 Features 32519-------------- 32520 32521Each `<feature>' describes some logical portion of the target system. 32522Features are currently used to describe available CPU registers and the 32523types of their contents. A `<feature>' element has this form: 32524 32525 <feature name="NAME"> 32526 [TYPE...] 32527 REG... 32528 </feature> 32529 32530Each feature's name should be unique within the description. The name 32531of a feature does not matter unless GDB has some special knowledge of 32532the contents of that feature; if it does, the feature should have its 32533standard name. *Note Standard Target Features::. 32534 32535G.2.6 Types 32536----------- 32537 32538Any register's value is a collection of bits which GDB must interpret. 32539The default interpretation is a two's complement integer, but other 32540types can be requested by name in the register description. Some 32541predefined types are provided by GDB (*note Predefined Target Types::), 32542and the description can define additional composite types. 32543 32544 Each type element must have an `id' attribute, which gives a unique 32545(within the containing `<feature>') name to the type. Types must be 32546defined before they are used. 32547 32548 Some targets offer vector registers, which can be treated as arrays 32549of scalar elements. These types are written as `<vector>' elements, 32550specifying the array element type, TYPE, and the number of elements, 32551COUNT: 32552 32553 <vector id="ID" type="TYPE" count="COUNT"/> 32554 32555 If a register's value is usefully viewed in multiple ways, define it 32556with a union type containing the useful representations. The `<union>' 32557element contains one or more `<field>' elements, each of which has a 32558NAME and a TYPE: 32559 32560 <union id="ID"> 32561 <field name="NAME" type="TYPE"/> 32562 ... 32563 </union> 32564 32565 If a register's value is composed from several separate values, 32566define it with a structure type. There are two forms of the `<struct>' 32567element; a `<struct>' element must either contain only bitfields or 32568contain no bitfields. If the structure contains only bitfields, its 32569total size in bytes must be specified, each bitfield must have an 32570explicit start and end, and bitfields are automatically assigned an 32571integer type. The field's START should be less than or equal to its 32572END, and zero represents the least significant bit. 32573 32574 <struct id="ID" size="SIZE"> 32575 <field name="NAME" start="START" end="END"/> 32576 ... 32577 </struct> 32578 32579 If the structure contains no bitfields, then each field has an 32580explicit type, and no implicit padding is added. 32581 32582 <struct id="ID"> 32583 <field name="NAME" type="TYPE"/> 32584 ... 32585 </struct> 32586 32587 If a register's value is a series of single-bit flags, define it with 32588a flags type. The `<flags>' element has an explicit SIZE and contains 32589one or more `<field>' elements. Each field has a NAME, a START, and an 32590END. Only single-bit flags are supported. 32591 32592 <flags id="ID" size="SIZE"> 32593 <field name="NAME" start="START" end="END"/> 32594 ... 32595 </flags> 32596 32597G.2.7 Registers 32598--------------- 32599 32600Each register is represented as an element with this form: 32601 32602 <reg name="NAME" 32603 bitsize="SIZE" 32604 [regnum="NUM"] 32605 [save-restore="SAVE-RESTORE"] 32606 [type="TYPE"] 32607 [group="GROUP"]/> 32608 32609The components are as follows: 32610 32611NAME 32612 The register's name; it must be unique within the target 32613 description. 32614 32615BITSIZE 32616 The register's size, in bits. 32617 32618REGNUM 32619 The register's number. If omitted, a register's number is one 32620 greater than that of the previous register (either in the current 32621 feature or in a preceeding feature); the first register in the 32622 target description defaults to zero. This register number is used 32623 to read or write the register; e.g. it is used in the remote `p' 32624 and `P' packets, and registers appear in the `g' and `G' packets 32625 in order of increasing register number. 32626 32627SAVE-RESTORE 32628 Whether the register should be preserved across inferior function 32629 calls; this must be either `yes' or `no'. The default is `yes', 32630 which is appropriate for most registers except for some system 32631 control registers; this is not related to the target's ABI. 32632 32633TYPE 32634 The type of the register. TYPE may be a predefined type, a type 32635 defined in the current feature, or one of the special types `int' 32636 and `float'. `int' is an integer type of the correct size for 32637 BITSIZE, and `float' is a floating point type (in the 32638 architecture's normal floating point format) of the correct size 32639 for BITSIZE. The default is `int'. 32640 32641GROUP 32642 The register group to which this register belongs. GROUP must be 32643 either `general', `float', or `vector'. If no GROUP is specified, 32644 GDB will not display the register in `info registers'. 32645 32646 32647 32648File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions 32649 32650G.3 Predefined Target Types 32651=========================== 32652 32653Type definitions in the self-description can build up composite types 32654from basic building blocks, but can not define fundamental types. 32655Instead, standard identifiers are provided by GDB for the fundamental 32656types. The currently supported types are: 32657 32658`int8' 32659`int16' 32660`int32' 32661`int64' 32662`int128' 32663 Signed integer types holding the specified number of bits. 32664 32665`uint8' 32666`uint16' 32667`uint32' 32668`uint64' 32669`uint128' 32670 Unsigned integer types holding the specified number of bits. 32671 32672`code_ptr' 32673`data_ptr' 32674 Pointers to unspecified code and data. The program counter and 32675 any dedicated return address register may be marked as code 32676 pointers; printing a code pointer converts it into a symbolic 32677 address. The stack pointer and any dedicated address registers 32678 may be marked as data pointers. 32679 32680`ieee_single' 32681 Single precision IEEE floating point. 32682 32683`ieee_double' 32684 Double precision IEEE floating point. 32685 32686`arm_fpa_ext' 32687 The 12-byte extended precision format used by ARM FPA registers. 32688 32689`i387_ext' 32690 The 10-byte extended precision format used by x87 registers. 32691 32692`i386_eflags' 32693 32bit EFLAGS register used by x86. 32694 32695`i386_mxcsr' 32696 32bit MXCSR register used by x86. 32697 32698 32699 32700File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions 32701 32702G.4 Standard Target Features 32703============================ 32704 32705A target description must contain either no registers or all the 32706target's registers. If the description contains no registers, then GDB 32707will assume a default register layout, selected based on the 32708architecture. If the description contains any registers, the default 32709layout will not be used; the standard registers must be described in 32710the target description, in such a way that GDB can recognize them. 32711 32712 This is accomplished by giving specific names to feature elements 32713which contain standard registers. GDB will look for features with 32714those names and verify that they contain the expected registers; if any 32715known feature is missing required registers, or if any required feature 32716is missing, GDB will reject the target description. You can add 32717additional registers to any of the standard features -- GDB will 32718display them just as if they were added to an unrecognized feature. 32719 32720 This section lists the known features and their expected contents. 32721Sample XML documents for these features are included in the GDB source 32722tree, in the directory `gdb/features'. 32723 32724 Names recognized by GDB should include the name of the company or 32725organization which selected the name, and the overall architecture to 32726which the feature applies; so e.g. the feature containing ARM core 32727registers is named `org.gnu.gdb.arm.core'. 32728 32729 The names of registers are not case sensitive for the purpose of 32730recognizing standard features, but GDB will only display registers 32731using the capitalization used in the description. 32732 32733* Menu: 32734 32735* ARM Features:: 32736* i386 Features:: 32737* MIPS Features:: 32738* M68K Features:: 32739* PowerPC Features:: 32740 32741 32742File: gdb.info, Node: ARM Features, Next: i386 Features, Up: Standard Target Features 32743 32744G.4.1 ARM Features 32745------------------ 32746 32747The `org.gnu.gdb.arm.core' feature is required for non-M-profile ARM 32748targets. It should contain registers `r0' through `r13', `sp', `lr', 32749`pc', and `cpsr'. 32750 32751 For M-profile targets (e.g. Cortex-M3), the `org.gnu.gdb.arm.core' 32752feature is replaced by `org.gnu.gdb.arm.m-profile'. It should contain 32753registers `r0' through `r13', `sp', `lr', `pc', and `xpsr'. 32754 32755 The `org.gnu.gdb.arm.fpa' feature is optional. If present, it 32756should contain registers `f0' through `f7' and `fps'. 32757 32758 The `org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it 32759should contain at least registers `wR0' through `wR15' and `wCGR0' 32760through `wCGR3'. The `wCID', `wCon', `wCSSF', and `wCASF' registers 32761are optional. 32762 32763 The `org.gnu.gdb.arm.vfp' feature is optional. If present, it 32764should contain at least registers `d0' through `d15'. If they are 32765present, `d16' through `d31' should also be included. GDB will 32766synthesize the single-precision registers from halves of the 32767double-precision registers. 32768 32769 The `org.gnu.gdb.arm.neon' feature is optional. It does not need to 32770contain registers; it instructs GDB to display the VFP double-precision 32771registers as vectors and to synthesize the quad-precision registers 32772from pairs of double-precision registers. If this feature is present, 32773`org.gnu.gdb.arm.vfp' must also be present and include 32 32774double-precision registers. 32775 32776 32777File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features 32778 32779G.4.2 i386 Features 32780------------------- 32781 32782The `org.gnu.gdb.i386.core' feature is required for i386/amd64 targets. 32783It should describe the following registers: 32784 32785 - `eax' through `edi' plus `eip' for i386 32786 32787 - `rax' through `r15' plus `rip' for amd64 32788 32789 - `eflags', `cs', `ss', `ds', `es', `fs', `gs' 32790 32791 - `st0' through `st7' 32792 32793 - `fctrl', `fstat', `ftag', `fiseg', `fioff', `foseg', `fooff' and 32794 `fop' 32795 32796 The register sets may be different, depending on the target. 32797 32798 The `org.gnu.gdb.i386.sse' feature is optional. It should describe 32799registers: 32800 32801 - `xmm0' through `xmm7' for i386 32802 32803 - `xmm0' through `xmm15' for amd64 32804 32805 - `mxcsr' 32806 32807 The `org.gnu.gdb.i386.avx' feature is optional and requires the 32808`org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits 32809of YMM registers: 32810 32811 - `ymm0h' through `ymm7h' for i386 32812 32813 - `ymm0h' through `ymm15h' for amd64 32814 32815 The `org.gnu.gdb.i386.linux' feature is optional. It should 32816describe a single register, `orig_eax'. 32817 32818 32819File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features 32820 32821G.4.3 MIPS Features 32822------------------- 32823 32824The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It 32825should contain registers `r0' through `r31', `lo', `hi', and `pc'. 32826They may be 32-bit or 64-bit depending on the target. 32827 32828 The `org.gnu.gdb.mips.cp0' feature is also required. It should 32829contain at least the `status', `badvaddr', and `cause' registers. They 32830may be 32-bit or 64-bit depending on the target. 32831 32832 The `org.gnu.gdb.mips.fpu' feature is currently required, though it 32833may be optional in a future version of GDB. It should contain 32834registers `f0' through `f31', `fcsr', and `fir'. They may be 32-bit or 3283564-bit depending on the target. 32836 32837 The `org.gnu.gdb.mips.linux' feature is optional. It should contain 32838a single register, `restart', which is used by the Linux kernel to 32839control restartable syscalls. 32840 32841 32842File: gdb.info, Node: M68K Features, Next: PowerPC Features, Prev: MIPS Features, Up: Standard Target Features 32843 32844G.4.4 M68K Features 32845------------------- 32846 32847``org.gnu.gdb.m68k.core'' 32848``org.gnu.gdb.coldfire.core'' 32849``org.gnu.gdb.fido.core'' 32850 One of those features must be always present. The feature that is 32851 present determines which flavor of m68k is used. The feature that 32852 is present should contain registers `d0' through `d7', `a0' 32853 through `a5', `fp', `sp', `ps' and `pc'. 32854 32855``org.gnu.gdb.coldfire.fp'' 32856 This feature is optional. If present, it should contain registers 32857 `fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'. 32858 32859 32860File: gdb.info, Node: PowerPC Features, Prev: M68K Features, Up: Standard Target Features 32861 32862G.4.5 PowerPC Features 32863---------------------- 32864 32865The `org.gnu.gdb.power.core' feature is required for PowerPC targets. 32866It should contain registers `r0' through `r31', `pc', `msr', `cr', 32867`lr', `ctr', and `xer'. They may be 32-bit or 64-bit depending on the 32868target. 32869 32870 The `org.gnu.gdb.power.fpu' feature is optional. It should contain 32871registers `f0' through `f31' and `fpscr'. 32872 32873 The `org.gnu.gdb.power.altivec' feature is optional. It should 32874contain registers `vr0' through `vr31', `vscr', and `vrsave'. 32875 32876 The `org.gnu.gdb.power.vsx' feature is optional. It should contain 32877registers `vs0h' through `vs31h'. GDB will combine these registers 32878with the floating point registers (`f0' through `f31') and the altivec 32879registers (`vr0' through `vr31') to present the 128-bit wide registers 32880`vs0' through `vs63', the set of vector registers for POWER7. 32881 32882 The `org.gnu.gdb.power.spe' feature is optional. It should contain 32883registers `ev0h' through `ev31h', `acc', and `spefscr'. SPE targets 32884should provide 32-bit registers in `org.gnu.gdb.power.core' and provide 32885the upper halves in `ev0h' through `ev31h'. GDB will combine these to 32886present registers `ev0' through `ev31' to the user. 32887 32888 32889File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top 32890 32891Appendix H Operating System Information 32892*************************************** 32893 32894* Menu: 32895 32896* Process list:: 32897 32898 Users of GDB often wish to obtain information about the state of the 32899operating system running on the target--for example the list of 32900processes, or the list of open files. This section describes the 32901mechanism that makes it possible. This mechanism is similar to the 32902target features mechanism (*note Target Descriptions::), but focuses on 32903a different aspect of target. 32904 32905 Operating system information is retrived from the target via the 32906remote protocol, using `qXfer' requests (*note qXfer osdata read::). 32907The object name in the request should be `osdata', and the ANNEX 32908identifies the data to be fetched. 32909 32910 32911File: gdb.info, Node: Process list, Up: Operating System Information 32912 32913H.1 Process list 32914================ 32915 32916When requesting the process list, the ANNEX field in the `qXfer' 32917request should be `processes'. The returned data is an XML document. 32918The formal syntax of this document is defined in 32919`gdb/features/osdata.dtd'. 32920 32921 An example document is: 32922 32923 <?xml version="1.0"?> 32924 <!DOCTYPE target SYSTEM "osdata.dtd"> 32925 <osdata type="processes"> 32926 <item> 32927 <column name="pid">1</column> 32928 <column name="user">root</column> 32929 <column name="command">/sbin/init</column> 32930 <column name="cores">1,2,3</column> 32931 </item> 32932 </osdata> 32933 32934 Each item should include a column whose name is `pid'. The value of 32935that column should identify the process on the target. The `user' and 32936`command' columns are optional, and will be displayed by GDB. The 32937`cores' column, if present, should contain a comma-separated list of 32938cores that this process is running on. Target may provide additional 32939columns, which GDB currently ignores. 32940 32941 32942File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Trace File Format, Up: Top 32943 32944Appendix I GNU GENERAL PUBLIC LICENSE 32945************************************* 32946 32947 Version 3, 29 June 2007 32948 32949 Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/' 32950 32951 Everyone is permitted to copy and distribute verbatim copies of this 32952 license document, but changing it is not allowed. 32953 32954Preamble 32955======== 32956 32957The GNU General Public License is a free, copyleft license for software 32958and other kinds of works. 32959 32960 The licenses for most software and other practical works are designed 32961to take away your freedom to share and change the works. By contrast, 32962the GNU General Public License is intended to guarantee your freedom to 32963share and change all versions of a program--to make sure it remains 32964free software for all its users. We, the Free Software Foundation, use 32965the GNU General Public License for most of our software; it applies 32966also to any other work released this way by its authors. You can apply 32967it to your programs, too. 32968 32969 When we speak of free software, we are referring to freedom, not 32970price. Our General Public Licenses are designed to make sure that you 32971have the freedom to distribute copies of free software (and charge for 32972them if you wish), that you receive source code or can get it if you 32973want it, that you can change the software or use pieces of it in new 32974free programs, and that you know you can do these things. 32975 32976 To protect your rights, we need to prevent others from denying you 32977these rights or asking you to surrender the rights. Therefore, you 32978have certain responsibilities if you distribute copies of the software, 32979or if you modify it: responsibilities to respect the freedom of others. 32980 32981 For example, if you distribute copies of such a program, whether 32982gratis or for a fee, you must pass on to the recipients the same 32983freedoms that you received. You must make sure that they, too, receive 32984or can get the source code. And you must show them these terms so they 32985know their rights. 32986 32987 Developers that use the GNU GPL protect your rights with two steps: 32988(1) assert copyright on the software, and (2) offer you this License 32989giving you legal permission to copy, distribute and/or modify it. 32990 32991 For the developers' and authors' protection, the GPL clearly explains 32992that there is no warranty for this free software. For both users' and 32993authors' sake, the GPL requires that modified versions be marked as 32994changed, so that their problems will not be attributed erroneously to 32995authors of previous versions. 32996 32997 Some devices are designed to deny users access to install or run 32998modified versions of the software inside them, although the 32999manufacturer can do so. This is fundamentally incompatible with the 33000aim of protecting users' freedom to change the software. The 33001systematic pattern of such abuse occurs in the area of products for 33002individuals to use, which is precisely where it is most unacceptable. 33003Therefore, we have designed this version of the GPL to prohibit the 33004practice for those products. If such problems arise substantially in 33005other domains, we stand ready to extend this provision to those domains 33006in future versions of the GPL, as needed to protect the freedom of 33007users. 33008 33009 Finally, every program is threatened constantly by software patents. 33010States should not allow patents to restrict development and use of 33011software on general-purpose computers, but in those that do, we wish to 33012avoid the special danger that patents applied to a free program could 33013make it effectively proprietary. To prevent this, the GPL assures that 33014patents cannot be used to render the program non-free. 33015 33016 The precise terms and conditions for copying, distribution and 33017modification follow. 33018 33019TERMS AND CONDITIONS 33020==================== 33021 33022 0. Definitions. 33023 33024 "This License" refers to version 3 of the GNU General Public 33025 License. 33026 33027 "Copyright" also means copyright-like laws that apply to other 33028 kinds of works, such as semiconductor masks. 33029 33030 "The Program" refers to any copyrightable work licensed under this 33031 License. Each licensee is addressed as "you". "Licensees" and 33032 "recipients" may be individuals or organizations. 33033 33034 To "modify" a work means to copy from or adapt all or part of the 33035 work in a fashion requiring copyright permission, other than the 33036 making of an exact copy. The resulting work is called a "modified 33037 version" of the earlier work or a work "based on" the earlier work. 33038 33039 A "covered work" means either the unmodified Program or a work 33040 based on the Program. 33041 33042 To "propagate" a work means to do anything with it that, without 33043 permission, would make you directly or secondarily liable for 33044 infringement under applicable copyright law, except executing it 33045 on a computer or modifying a private copy. Propagation includes 33046 copying, distribution (with or without modification), making 33047 available to the public, and in some countries other activities as 33048 well. 33049 33050 To "convey" a work means any kind of propagation that enables other 33051 parties to make or receive copies. Mere interaction with a user 33052 through a computer network, with no transfer of a copy, is not 33053 conveying. 33054 33055 An interactive user interface displays "Appropriate Legal Notices" 33056 to the extent that it includes a convenient and prominently visible 33057 feature that (1) displays an appropriate copyright notice, and (2) 33058 tells the user that there is no warranty for the work (except to 33059 the extent that warranties are provided), that licensees may 33060 convey the work under this License, and how to view a copy of this 33061 License. If the interface presents a list of user commands or 33062 options, such as a menu, a prominent item in the list meets this 33063 criterion. 33064 33065 1. Source Code. 33066 33067 The "source code" for a work means the preferred form of the work 33068 for making modifications to it. "Object code" means any 33069 non-source form of a work. 33070 33071 A "Standard Interface" means an interface that either is an 33072 official standard defined by a recognized standards body, or, in 33073 the case of interfaces specified for a particular programming 33074 language, one that is widely used among developers working in that 33075 language. 33076 33077 The "System Libraries" of an executable work include anything, 33078 other than the work as a whole, that (a) is included in the normal 33079 form of packaging a Major Component, but which is not part of that 33080 Major Component, and (b) serves only to enable use of the work 33081 with that Major Component, or to implement a Standard Interface 33082 for which an implementation is available to the public in source 33083 code form. A "Major Component", in this context, means a major 33084 essential component (kernel, window system, and so on) of the 33085 specific operating system (if any) on which the executable work 33086 runs, or a compiler used to produce the work, or an object code 33087 interpreter used to run it. 33088 33089 The "Corresponding Source" for a work in object code form means all 33090 the source code needed to generate, install, and (for an executable 33091 work) run the object code and to modify the work, including 33092 scripts to control those activities. However, it does not include 33093 the work's System Libraries, or general-purpose tools or generally 33094 available free programs which are used unmodified in performing 33095 those activities but which are not part of the work. For example, 33096 Corresponding Source includes interface definition files 33097 associated with source files for the work, and the source code for 33098 shared libraries and dynamically linked subprograms that the work 33099 is specifically designed to require, such as by intimate data 33100 communication or control flow between those subprograms and other 33101 parts of the work. 33102 33103 The Corresponding Source need not include anything that users can 33104 regenerate automatically from other parts of the Corresponding 33105 Source. 33106 33107 The Corresponding Source for a work in source code form is that 33108 same work. 33109 33110 2. Basic Permissions. 33111 33112 All rights granted under this License are granted for the term of 33113 copyright on the Program, and are irrevocable provided the stated 33114 conditions are met. This License explicitly affirms your unlimited 33115 permission to run the unmodified Program. The output from running 33116 a covered work is covered by this License only if the output, 33117 given its content, constitutes a covered work. This License 33118 acknowledges your rights of fair use or other equivalent, as 33119 provided by copyright law. 33120 33121 You may make, run and propagate covered works that you do not 33122 convey, without conditions so long as your license otherwise 33123 remains in force. You may convey covered works to others for the 33124 sole purpose of having them make modifications exclusively for 33125 you, or provide you with facilities for running those works, 33126 provided that you comply with the terms of this License in 33127 conveying all material for which you do not control copyright. 33128 Those thus making or running the covered works for you must do so 33129 exclusively on your behalf, under your direction and control, on 33130 terms that prohibit them from making any copies of your 33131 copyrighted material outside their relationship with you. 33132 33133 Conveying under any other circumstances is permitted solely under 33134 the conditions stated below. Sublicensing is not allowed; section 33135 10 makes it unnecessary. 33136 33137 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 33138 33139 No covered work shall be deemed part of an effective technological 33140 measure under any applicable law fulfilling obligations under 33141 article 11 of the WIPO copyright treaty adopted on 20 December 33142 1996, or similar laws prohibiting or restricting circumvention of 33143 such measures. 33144 33145 When you convey a covered work, you waive any legal power to forbid 33146 circumvention of technological measures to the extent such 33147 circumvention is effected by exercising rights under this License 33148 with respect to the covered work, and you disclaim any intention 33149 to limit operation or modification of the work as a means of 33150 enforcing, against the work's users, your or third parties' legal 33151 rights to forbid circumvention of technological measures. 33152 33153 4. Conveying Verbatim Copies. 33154 33155 You may convey verbatim copies of the Program's source code as you 33156 receive it, in any medium, provided that you conspicuously and 33157 appropriately publish on each copy an appropriate copyright notice; 33158 keep intact all notices stating that this License and any 33159 non-permissive terms added in accord with section 7 apply to the 33160 code; keep intact all notices of the absence of any warranty; and 33161 give all recipients a copy of this License along with the Program. 33162 33163 You may charge any price or no price for each copy that you convey, 33164 and you may offer support or warranty protection for a fee. 33165 33166 5. Conveying Modified Source Versions. 33167 33168 You may convey a work based on the Program, or the modifications to 33169 produce it from the Program, in the form of source code under the 33170 terms of section 4, provided that you also meet all of these 33171 conditions: 33172 33173 a. The work must carry prominent notices stating that you 33174 modified it, and giving a relevant date. 33175 33176 b. The work must carry prominent notices stating that it is 33177 released under this License and any conditions added under 33178 section 7. This requirement modifies the requirement in 33179 section 4 to "keep intact all notices". 33180 33181 c. You must license the entire work, as a whole, under this 33182 License to anyone who comes into possession of a copy. This 33183 License will therefore apply, along with any applicable 33184 section 7 additional terms, to the whole of the work, and all 33185 its parts, regardless of how they are packaged. This License 33186 gives no permission to license the work in any other way, but 33187 it does not invalidate such permission if you have separately 33188 received it. 33189 33190 d. If the work has interactive user interfaces, each must display 33191 Appropriate Legal Notices; however, if the Program has 33192 interactive interfaces that do not display Appropriate Legal 33193 Notices, your work need not make them do so. 33194 33195 A compilation of a covered work with other separate and independent 33196 works, which are not by their nature extensions of the covered 33197 work, and which are not combined with it such as to form a larger 33198 program, in or on a volume of a storage or distribution medium, is 33199 called an "aggregate" if the compilation and its resulting 33200 copyright are not used to limit the access or legal rights of the 33201 compilation's users beyond what the individual works permit. 33202 Inclusion of a covered work in an aggregate does not cause this 33203 License to apply to the other parts of the aggregate. 33204 33205 6. Conveying Non-Source Forms. 33206 33207 You may convey a covered work in object code form under the terms 33208 of sections 4 and 5, provided that you also convey the 33209 machine-readable Corresponding Source under the terms of this 33210 License, in one of these ways: 33211 33212 a. Convey the object code in, or embodied in, a physical product 33213 (including a physical distribution medium), accompanied by the 33214 Corresponding Source fixed on a durable physical medium 33215 customarily used for software interchange. 33216 33217 b. Convey the object code in, or embodied in, a physical product 33218 (including a physical distribution medium), accompanied by a 33219 written offer, valid for at least three years and valid for 33220 as long as you offer spare parts or customer support for that 33221 product model, to give anyone who possesses the object code 33222 either (1) a copy of the Corresponding Source for all the 33223 software in the product that is covered by this License, on a 33224 durable physical medium customarily used for software 33225 interchange, for a price no more than your reasonable cost of 33226 physically performing this conveying of source, or (2) access 33227 to copy the Corresponding Source from a network server at no 33228 charge. 33229 33230 c. Convey individual copies of the object code with a copy of 33231 the written offer to provide the Corresponding Source. This 33232 alternative is allowed only occasionally and noncommercially, 33233 and only if you received the object code with such an offer, 33234 in accord with subsection 6b. 33235 33236 d. Convey the object code by offering access from a designated 33237 place (gratis or for a charge), and offer equivalent access 33238 to the Corresponding Source in the same way through the same 33239 place at no further charge. You need not require recipients 33240 to copy the Corresponding Source along with the object code. 33241 If the place to copy the object code is a network server, the 33242 Corresponding Source may be on a different server (operated 33243 by you or a third party) that supports equivalent copying 33244 facilities, provided you maintain clear directions next to 33245 the object code saying where to find the Corresponding Source. 33246 Regardless of what server hosts the Corresponding Source, you 33247 remain obligated to ensure that it is available for as long 33248 as needed to satisfy these requirements. 33249 33250 e. Convey the object code using peer-to-peer transmission, 33251 provided you inform other peers where the object code and 33252 Corresponding Source of the work are being offered to the 33253 general public at no charge under subsection 6d. 33254 33255 33256 A separable portion of the object code, whose source code is 33257 excluded from the Corresponding Source as a System Library, need 33258 not be included in conveying the object code work. 33259 33260 A "User Product" is either (1) a "consumer product", which means 33261 any tangible personal property which is normally used for personal, 33262 family, or household purposes, or (2) anything designed or sold for 33263 incorporation into a dwelling. In determining whether a product 33264 is a consumer product, doubtful cases shall be resolved in favor of 33265 coverage. For a particular product received by a particular user, 33266 "normally used" refers to a typical or common use of that class of 33267 product, regardless of the status of the particular user or of the 33268 way in which the particular user actually uses, or expects or is 33269 expected to use, the product. A product is a consumer product 33270 regardless of whether the product has substantial commercial, 33271 industrial or non-consumer uses, unless such uses represent the 33272 only significant mode of use of the product. 33273 33274 "Installation Information" for a User Product means any methods, 33275 procedures, authorization keys, or other information required to 33276 install and execute modified versions of a covered work in that 33277 User Product from a modified version of its Corresponding Source. 33278 The information must suffice to ensure that the continued 33279 functioning of the modified object code is in no case prevented or 33280 interfered with solely because modification has been made. 33281 33282 If you convey an object code work under this section in, or with, 33283 or specifically for use in, a User Product, and the conveying 33284 occurs as part of a transaction in which the right of possession 33285 and use of the User Product is transferred to the recipient in 33286 perpetuity or for a fixed term (regardless of how the transaction 33287 is characterized), the Corresponding Source conveyed under this 33288 section must be accompanied by the Installation Information. But 33289 this requirement does not apply if neither you nor any third party 33290 retains the ability to install modified object code on the User 33291 Product (for example, the work has been installed in ROM). 33292 33293 The requirement to provide Installation Information does not 33294 include a requirement to continue to provide support service, 33295 warranty, or updates for a work that has been modified or 33296 installed by the recipient, or for the User Product in which it 33297 has been modified or installed. Access to a network may be denied 33298 when the modification itself materially and adversely affects the 33299 operation of the network or violates the rules and protocols for 33300 communication across the network. 33301 33302 Corresponding Source conveyed, and Installation Information 33303 provided, in accord with this section must be in a format that is 33304 publicly documented (and with an implementation available to the 33305 public in source code form), and must require no special password 33306 or key for unpacking, reading or copying. 33307 33308 7. Additional Terms. 33309 33310 "Additional permissions" are terms that supplement the terms of 33311 this License by making exceptions from one or more of its 33312 conditions. Additional permissions that are applicable to the 33313 entire Program shall be treated as though they were included in 33314 this License, to the extent that they are valid under applicable 33315 law. If additional permissions apply only to part of the Program, 33316 that part may be used separately under those permissions, but the 33317 entire Program remains governed by this License without regard to 33318 the additional permissions. 33319 33320 When you convey a copy of a covered work, you may at your option 33321 remove any additional permissions from that copy, or from any part 33322 of it. (Additional permissions may be written to require their own 33323 removal in certain cases when you modify the work.) You may place 33324 additional permissions on material, added by you to a covered work, 33325 for which you have or can give appropriate copyright permission. 33326 33327 Notwithstanding any other provision of this License, for material 33328 you add to a covered work, you may (if authorized by the copyright 33329 holders of that material) supplement the terms of this License 33330 with terms: 33331 33332 a. Disclaiming warranty or limiting liability differently from 33333 the terms of sections 15 and 16 of this License; or 33334 33335 b. Requiring preservation of specified reasonable legal notices 33336 or author attributions in that material or in the Appropriate 33337 Legal Notices displayed by works containing it; or 33338 33339 c. Prohibiting misrepresentation of the origin of that material, 33340 or requiring that modified versions of such material be 33341 marked in reasonable ways as different from the original 33342 version; or 33343 33344 d. Limiting the use for publicity purposes of names of licensors 33345 or authors of the material; or 33346 33347 e. Declining to grant rights under trademark law for use of some 33348 trade names, trademarks, or service marks; or 33349 33350 f. Requiring indemnification of licensors and authors of that 33351 material by anyone who conveys the material (or modified 33352 versions of it) with contractual assumptions of liability to 33353 the recipient, for any liability that these contractual 33354 assumptions directly impose on those licensors and authors. 33355 33356 All other non-permissive additional terms are considered "further 33357 restrictions" within the meaning of section 10. If the Program as 33358 you received it, or any part of it, contains a notice stating that 33359 it is governed by this License along with a term that is a further 33360 restriction, you may remove that term. If a license document 33361 contains a further restriction but permits relicensing or 33362 conveying under this License, you may add to a covered work 33363 material governed by the terms of that license document, provided 33364 that the further restriction does not survive such relicensing or 33365 conveying. 33366 33367 If you add terms to a covered work in accord with this section, you 33368 must place, in the relevant source files, a statement of the 33369 additional terms that apply to those files, or a notice indicating 33370 where to find the applicable terms. 33371 33372 Additional terms, permissive or non-permissive, may be stated in 33373 the form of a separately written license, or stated as exceptions; 33374 the above requirements apply either way. 33375 33376 8. Termination. 33377 33378 You may not propagate or modify a covered work except as expressly 33379 provided under this License. Any attempt otherwise to propagate or 33380 modify it is void, and will automatically terminate your rights 33381 under this License (including any patent licenses granted under 33382 the third paragraph of section 11). 33383 33384 However, if you cease all violation of this License, then your 33385 license from a particular copyright holder is reinstated (a) 33386 provisionally, unless and until the copyright holder explicitly 33387 and finally terminates your license, and (b) permanently, if the 33388 copyright holder fails to notify you of the violation by some 33389 reasonable means prior to 60 days after the cessation. 33390 33391 Moreover, your license from a particular copyright holder is 33392 reinstated permanently if the copyright holder notifies you of the 33393 violation by some reasonable means, this is the first time you have 33394 received notice of violation of this License (for any work) from 33395 that copyright holder, and you cure the violation prior to 30 days 33396 after your receipt of the notice. 33397 33398 Termination of your rights under this section does not terminate 33399 the licenses of parties who have received copies or rights from 33400 you under this License. If your rights have been terminated and 33401 not permanently reinstated, you do not qualify to receive new 33402 licenses for the same material under section 10. 33403 33404 9. Acceptance Not Required for Having Copies. 33405 33406 You are not required to accept this License in order to receive or 33407 run a copy of the Program. Ancillary propagation of a covered work 33408 occurring solely as a consequence of using peer-to-peer 33409 transmission to receive a copy likewise does not require 33410 acceptance. However, nothing other than this License grants you 33411 permission to propagate or modify any covered work. These actions 33412 infringe copyright if you do not accept this License. Therefore, 33413 by modifying or propagating a covered work, you indicate your 33414 acceptance of this License to do so. 33415 33416 10. Automatic Licensing of Downstream Recipients. 33417 33418 Each time you convey a covered work, the recipient automatically 33419 receives a license from the original licensors, to run, modify and 33420 propagate that work, subject to this License. You are not 33421 responsible for enforcing compliance by third parties with this 33422 License. 33423 33424 An "entity transaction" is a transaction transferring control of an 33425 organization, or substantially all assets of one, or subdividing an 33426 organization, or merging organizations. If propagation of a 33427 covered work results from an entity transaction, each party to that 33428 transaction who receives a copy of the work also receives whatever 33429 licenses to the work the party's predecessor in interest had or 33430 could give under the previous paragraph, plus a right to 33431 possession of the Corresponding Source of the work from the 33432 predecessor in interest, if the predecessor has it or can get it 33433 with reasonable efforts. 33434 33435 You may not impose any further restrictions on the exercise of the 33436 rights granted or affirmed under this License. For example, you 33437 may not impose a license fee, royalty, or other charge for 33438 exercise of rights granted under this License, and you may not 33439 initiate litigation (including a cross-claim or counterclaim in a 33440 lawsuit) alleging that any patent claim is infringed by making, 33441 using, selling, offering for sale, or importing the Program or any 33442 portion of it. 33443 33444 11. Patents. 33445 33446 A "contributor" is a copyright holder who authorizes use under this 33447 License of the Program or a work on which the Program is based. 33448 The work thus licensed is called the contributor's "contributor 33449 version". 33450 33451 A contributor's "essential patent claims" are all patent claims 33452 owned or controlled by the contributor, whether already acquired or 33453 hereafter acquired, that would be infringed by some manner, 33454 permitted by this License, of making, using, or selling its 33455 contributor version, but do not include claims that would be 33456 infringed only as a consequence of further modification of the 33457 contributor version. For purposes of this definition, "control" 33458 includes the right to grant patent sublicenses in a manner 33459 consistent with the requirements of this License. 33460 33461 Each contributor grants you a non-exclusive, worldwide, 33462 royalty-free patent license under the contributor's essential 33463 patent claims, to make, use, sell, offer for sale, import and 33464 otherwise run, modify and propagate the contents of its 33465 contributor version. 33466 33467 In the following three paragraphs, a "patent license" is any 33468 express agreement or commitment, however denominated, not to 33469 enforce a patent (such as an express permission to practice a 33470 patent or covenant not to sue for patent infringement). To 33471 "grant" such a patent license to a party means to make such an 33472 agreement or commitment not to enforce a patent against the party. 33473 33474 If you convey a covered work, knowingly relying on a patent 33475 license, and the Corresponding Source of the work is not available 33476 for anyone to copy, free of charge and under the terms of this 33477 License, through a publicly available network server or other 33478 readily accessible means, then you must either (1) cause the 33479 Corresponding Source to be so available, or (2) arrange to deprive 33480 yourself of the benefit of the patent license for this particular 33481 work, or (3) arrange, in a manner consistent with the requirements 33482 of this License, to extend the patent license to downstream 33483 recipients. "Knowingly relying" means you have actual knowledge 33484 that, but for the patent license, your conveying the covered work 33485 in a country, or your recipient's use of the covered work in a 33486 country, would infringe one or more identifiable patents in that 33487 country that you have reason to believe are valid. 33488 33489 If, pursuant to or in connection with a single transaction or 33490 arrangement, you convey, or propagate by procuring conveyance of, a 33491 covered work, and grant a patent license to some of the parties 33492 receiving the covered work authorizing them to use, propagate, 33493 modify or convey a specific copy of the covered work, then the 33494 patent license you grant is automatically extended to all 33495 recipients of the covered work and works based on it. 33496 33497 A patent license is "discriminatory" if it does not include within 33498 the scope of its coverage, prohibits the exercise of, or is 33499 conditioned on the non-exercise of one or more of the rights that 33500 are specifically granted under this License. You may not convey a 33501 covered work if you are a party to an arrangement with a third 33502 party that is in the business of distributing software, under 33503 which you make payment to the third party based on the extent of 33504 your activity of conveying the work, and under which the third 33505 party grants, to any of the parties who would receive the covered 33506 work from you, a discriminatory patent license (a) in connection 33507 with copies of the covered work conveyed by you (or copies made 33508 from those copies), or (b) primarily for and in connection with 33509 specific products or compilations that contain the covered work, 33510 unless you entered into that arrangement, or that patent license 33511 was granted, prior to 28 March 2007. 33512 33513 Nothing in this License shall be construed as excluding or limiting 33514 any implied license or other defenses to infringement that may 33515 otherwise be available to you under applicable patent law. 33516 33517 12. No Surrender of Others' Freedom. 33518 33519 If conditions are imposed on you (whether by court order, 33520 agreement or otherwise) that contradict the conditions of this 33521 License, they do not excuse you from the conditions of this 33522 License. If you cannot convey a covered work so as to satisfy 33523 simultaneously your obligations under this License and any other 33524 pertinent obligations, then as a consequence you may not convey it 33525 at all. For example, if you agree to terms that obligate you to 33526 collect a royalty for further conveying from those to whom you 33527 convey the Program, the only way you could satisfy both those 33528 terms and this License would be to refrain entirely from conveying 33529 the Program. 33530 33531 13. Use with the GNU Affero General Public License. 33532 33533 Notwithstanding any other provision of this License, you have 33534 permission to link or combine any covered work with a work licensed 33535 under version 3 of the GNU Affero General Public License into a 33536 single combined work, and to convey the resulting work. The terms 33537 of this License will continue to apply to the part which is the 33538 covered work, but the special requirements of the GNU Affero 33539 General Public License, section 13, concerning interaction through 33540 a network will apply to the combination as such. 33541 33542 14. Revised Versions of this License. 33543 33544 The Free Software Foundation may publish revised and/or new 33545 versions of the GNU General Public License from time to time. 33546 Such new versions will be similar in spirit to the present 33547 version, but may differ in detail to address new problems or 33548 concerns. 33549 33550 Each version is given a distinguishing version number. If the 33551 Program specifies that a certain numbered version of the GNU 33552 General Public License "or any later version" applies to it, you 33553 have the option of following the terms and conditions either of 33554 that numbered version or of any later version published by the 33555 Free Software Foundation. If the Program does not specify a 33556 version number of the GNU General Public License, you may choose 33557 any version ever published by the Free Software Foundation. 33558 33559 If the Program specifies that a proxy can decide which future 33560 versions of the GNU General Public License can be used, that 33561 proxy's public statement of acceptance of a version permanently 33562 authorizes you to choose that version for the Program. 33563 33564 Later license versions may give you additional or different 33565 permissions. However, no additional obligations are imposed on any 33566 author or copyright holder as a result of your choosing to follow a 33567 later version. 33568 33569 15. Disclaimer of Warranty. 33570 33571 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 33572 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE 33573 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" 33574 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 33575 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 33576 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE 33577 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. 33578 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 33579 NECESSARY SERVICING, REPAIR OR CORRECTION. 33580 33581 16. Limitation of Liability. 33582 33583 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 33584 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES 33585 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU 33586 FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR 33587 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE 33588 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA 33589 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 33590 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 33591 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF 33592 THE POSSIBILITY OF SUCH DAMAGES. 33593 33594 17. Interpretation of Sections 15 and 16. 33595 33596 If the disclaimer of warranty and limitation of liability provided 33597 above cannot be given local legal effect according to their terms, 33598 reviewing courts shall apply local law that most closely 33599 approximates an absolute waiver of all civil liability in 33600 connection with the Program, unless a warranty or assumption of 33601 liability accompanies a copy of the Program in return for a fee. 33602 33603 33604END OF TERMS AND CONDITIONS 33605=========================== 33606 33607How to Apply These Terms to Your New Programs 33608============================================= 33609 33610If you develop a new program, and you want it to be of the greatest 33611possible use to the public, the best way to achieve this is to make it 33612free software which everyone can redistribute and change under these 33613terms. 33614 33615 To do so, attach the following notices to the program. It is safest 33616to attach them to the start of each source file to most effectively 33617state the exclusion of warranty; and each file should have at least the 33618"copyright" line and a pointer to where the full notice is found. 33619 33620 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. 33621 Copyright (C) YEAR NAME OF AUTHOR 33622 33623 This program is free software: you can redistribute it and/or modify 33624 it under the terms of the GNU General Public License as published by 33625 the Free Software Foundation, either version 3 of the License, or (at 33626 your option) any later version. 33627 33628 This program is distributed in the hope that it will be useful, but 33629 WITHOUT ANY WARRANTY; without even the implied warranty of 33630 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 33631 General Public License for more details. 33632 33633 You should have received a copy of the GNU General Public License 33634 along with this program. If not, see `http://www.gnu.org/licenses/'. 33635 33636 Also add information on how to contact you by electronic and paper 33637mail. 33638 33639 If the program does terminal interaction, make it output a short 33640notice like this when it starts in an interactive mode: 33641 33642 PROGRAM Copyright (C) YEAR NAME OF AUTHOR 33643 This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 33644 This is free software, and you are welcome to redistribute it 33645 under certain conditions; type `show c' for details. 33646 33647 The hypothetical commands `show w' and `show c' should show the 33648appropriate parts of the General Public License. Of course, your 33649program's commands might be different; for a GUI interface, you would 33650use an "about box". 33651 33652 You should also get your employer (if you work as a programmer) or 33653school, if any, to sign a "copyright disclaimer" for the program, if 33654necessary. For more information on this, and how to apply and follow 33655the GNU GPL, see `http://www.gnu.org/licenses/'. 33656 33657 The GNU General Public License does not permit incorporating your 33658program into proprietary programs. If your program is a subroutine 33659library, you may consider it more useful to permit linking proprietary 33660applications with the library. If this is what you want to do, use the 33661GNU Lesser General Public License instead of this License. But first, 33662please read `http://www.gnu.org/philosophy/why-not-lgpl.html'. 33663 33664 33665File: gdb.info, Node: GNU Free Documentation License, Next: GDB Index, Prev: Copying, Up: Top 33666 33667Appendix J GNU Free Documentation License 33668***************************************** 33669 33670 Version 1.3, 3 November 2008 33671 33672 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 33673 `http://fsf.org/' 33674 33675 Everyone is permitted to copy and distribute verbatim copies 33676 of this license document, but changing it is not allowed. 33677 33678 0. PREAMBLE 33679 33680 The purpose of this License is to make a manual, textbook, or other 33681 functional and useful document "free" in the sense of freedom: to 33682 assure everyone the effective freedom to copy and redistribute it, 33683 with or without modifying it, either commercially or 33684 noncommercially. Secondarily, this License preserves for the 33685 author and publisher a way to get credit for their work, while not 33686 being considered responsible for modifications made by others. 33687 33688 This License is a kind of "copyleft", which means that derivative 33689 works of the document must themselves be free in the same sense. 33690 It complements the GNU General Public License, which is a copyleft 33691 license designed for free software. 33692 33693 We have designed this License in order to use it for manuals for 33694 free software, because free software needs free documentation: a 33695 free program should come with manuals providing the same freedoms 33696 that the software does. But this License is not limited to 33697 software manuals; it can be used for any textual work, regardless 33698 of subject matter or whether it is published as a printed book. 33699 We recommend this License principally for works whose purpose is 33700 instruction or reference. 33701 33702 1. APPLICABILITY AND DEFINITIONS 33703 33704 This License applies to any manual or other work, in any medium, 33705 that contains a notice placed by the copyright holder saying it 33706 can be distributed under the terms of this License. Such a notice 33707 grants a world-wide, royalty-free license, unlimited in duration, 33708 to use that work under the conditions stated herein. The 33709 "Document", below, refers to any such manual or work. Any member 33710 of the public is a licensee, and is addressed as "you". You 33711 accept the license if you copy, modify or distribute the work in a 33712 way requiring permission under copyright law. 33713 33714 A "Modified Version" of the Document means any work containing the 33715 Document or a portion of it, either copied verbatim, or with 33716 modifications and/or translated into another language. 33717 33718 A "Secondary Section" is a named appendix or a front-matter section 33719 of the Document that deals exclusively with the relationship of the 33720 publishers or authors of the Document to the Document's overall 33721 subject (or to related matters) and contains nothing that could 33722 fall directly within that overall subject. (Thus, if the Document 33723 is in part a textbook of mathematics, a Secondary Section may not 33724 explain any mathematics.) The relationship could be a matter of 33725 historical connection with the subject or with related matters, or 33726 of legal, commercial, philosophical, ethical or political position 33727 regarding them. 33728 33729 The "Invariant Sections" are certain Secondary Sections whose 33730 titles are designated, as being those of Invariant Sections, in 33731 the notice that says that the Document is released under this 33732 License. If a section does not fit the above definition of 33733 Secondary then it is not allowed to be designated as Invariant. 33734 The Document may contain zero Invariant Sections. If the Document 33735 does not identify any Invariant Sections then there are none. 33736 33737 The "Cover Texts" are certain short passages of text that are 33738 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 33739 that says that the Document is released under this License. A 33740 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 33741 be at most 25 words. 33742 33743 A "Transparent" copy of the Document means a machine-readable copy, 33744 represented in a format whose specification is available to the 33745 general public, that is suitable for revising the document 33746 straightforwardly with generic text editors or (for images 33747 composed of pixels) generic paint programs or (for drawings) some 33748 widely available drawing editor, and that is suitable for input to 33749 text formatters or for automatic translation to a variety of 33750 formats suitable for input to text formatters. A copy made in an 33751 otherwise Transparent file format whose markup, or absence of 33752 markup, has been arranged to thwart or discourage subsequent 33753 modification by readers is not Transparent. An image format is 33754 not Transparent if used for any substantial amount of text. A 33755 copy that is not "Transparent" is called "Opaque". 33756 33757 Examples of suitable formats for Transparent copies include plain 33758 ASCII without markup, Texinfo input format, LaTeX input format, 33759 SGML or XML using a publicly available DTD, and 33760 standard-conforming simple HTML, PostScript or PDF designed for 33761 human modification. Examples of transparent image formats include 33762 PNG, XCF and JPG. Opaque formats include proprietary formats that 33763 can be read and edited only by proprietary word processors, SGML or 33764 XML for which the DTD and/or processing tools are not generally 33765 available, and the machine-generated HTML, PostScript or PDF 33766 produced by some word processors for output purposes only. 33767 33768 The "Title Page" means, for a printed book, the title page itself, 33769 plus such following pages as are needed to hold, legibly, the 33770 material this License requires to appear in the title page. For 33771 works in formats which do not have any title page as such, "Title 33772 Page" means the text near the most prominent appearance of the 33773 work's title, preceding the beginning of the body of the text. 33774 33775 The "publisher" means any person or entity that distributes copies 33776 of the Document to the public. 33777 33778 A section "Entitled XYZ" means a named subunit of the Document 33779 whose title either is precisely XYZ or contains XYZ in parentheses 33780 following text that translates XYZ in another language. (Here XYZ 33781 stands for a specific section name mentioned below, such as 33782 "Acknowledgements", "Dedications", "Endorsements", or "History".) 33783 To "Preserve the Title" of such a section when you modify the 33784 Document means that it remains a section "Entitled XYZ" according 33785 to this definition. 33786 33787 The Document may include Warranty Disclaimers next to the notice 33788 which states that this License applies to the Document. These 33789 Warranty Disclaimers are considered to be included by reference in 33790 this License, but only as regards disclaiming warranties: any other 33791 implication that these Warranty Disclaimers may have is void and 33792 has no effect on the meaning of this License. 33793 33794 2. VERBATIM COPYING 33795 33796 You may copy and distribute the Document in any medium, either 33797 commercially or noncommercially, provided that this License, the 33798 copyright notices, and the license notice saying this License 33799 applies to the Document are reproduced in all copies, and that you 33800 add no other conditions whatsoever to those of this License. You 33801 may not use technical measures to obstruct or control the reading 33802 or further copying of the copies you make or distribute. However, 33803 you may accept compensation in exchange for copies. If you 33804 distribute a large enough number of copies you must also follow 33805 the conditions in section 3. 33806 33807 You may also lend copies, under the same conditions stated above, 33808 and you may publicly display copies. 33809 33810 3. COPYING IN QUANTITY 33811 33812 If you publish printed copies (or copies in media that commonly 33813 have printed covers) of the Document, numbering more than 100, and 33814 the Document's license notice requires Cover Texts, you must 33815 enclose the copies in covers that carry, clearly and legibly, all 33816 these Cover Texts: Front-Cover Texts on the front cover, and 33817 Back-Cover Texts on the back cover. Both covers must also clearly 33818 and legibly identify you as the publisher of these copies. The 33819 front cover must present the full title with all words of the 33820 title equally prominent and visible. You may add other material 33821 on the covers in addition. Copying with changes limited to the 33822 covers, as long as they preserve the title of the Document and 33823 satisfy these conditions, can be treated as verbatim copying in 33824 other respects. 33825 33826 If the required texts for either cover are too voluminous to fit 33827 legibly, you should put the first ones listed (as many as fit 33828 reasonably) on the actual cover, and continue the rest onto 33829 adjacent pages. 33830 33831 If you publish or distribute Opaque copies of the Document 33832 numbering more than 100, you must either include a 33833 machine-readable Transparent copy along with each Opaque copy, or 33834 state in or with each Opaque copy a computer-network location from 33835 which the general network-using public has access to download 33836 using public-standard network protocols a complete Transparent 33837 copy of the Document, free of added material. If you use the 33838 latter option, you must take reasonably prudent steps, when you 33839 begin distribution of Opaque copies in quantity, to ensure that 33840 this Transparent copy will remain thus accessible at the stated 33841 location until at least one year after the last time you 33842 distribute an Opaque copy (directly or through your agents or 33843 retailers) of that edition to the public. 33844 33845 It is requested, but not required, that you contact the authors of 33846 the Document well before redistributing any large number of 33847 copies, to give them a chance to provide you with an updated 33848 version of the Document. 33849 33850 4. MODIFICATIONS 33851 33852 You may copy and distribute a Modified Version of the Document 33853 under the conditions of sections 2 and 3 above, provided that you 33854 release the Modified Version under precisely this License, with 33855 the Modified Version filling the role of the Document, thus 33856 licensing distribution and modification of the Modified Version to 33857 whoever possesses a copy of it. In addition, you must do these 33858 things in the Modified Version: 33859 33860 A. Use in the Title Page (and on the covers, if any) a title 33861 distinct from that of the Document, and from those of 33862 previous versions (which should, if there were any, be listed 33863 in the History section of the Document). You may use the 33864 same title as a previous version if the original publisher of 33865 that version gives permission. 33866 33867 B. List on the Title Page, as authors, one or more persons or 33868 entities responsible for authorship of the modifications in 33869 the Modified Version, together with at least five of the 33870 principal authors of the Document (all of its principal 33871 authors, if it has fewer than five), unless they release you 33872 from this requirement. 33873 33874 C. State on the Title page the name of the publisher of the 33875 Modified Version, as the publisher. 33876 33877 D. Preserve all the copyright notices of the Document. 33878 33879 E. Add an appropriate copyright notice for your modifications 33880 adjacent to the other copyright notices. 33881 33882 F. Include, immediately after the copyright notices, a license 33883 notice giving the public permission to use the Modified 33884 Version under the terms of this License, in the form shown in 33885 the Addendum below. 33886 33887 G. Preserve in that license notice the full lists of Invariant 33888 Sections and required Cover Texts given in the Document's 33889 license notice. 33890 33891 H. Include an unaltered copy of this License. 33892 33893 I. Preserve the section Entitled "History", Preserve its Title, 33894 and add to it an item stating at least the title, year, new 33895 authors, and publisher of the Modified Version as given on 33896 the Title Page. If there is no section Entitled "History" in 33897 the Document, create one stating the title, year, authors, 33898 and publisher of the Document as given on its Title Page, 33899 then add an item describing the Modified Version as stated in 33900 the previous sentence. 33901 33902 J. Preserve the network location, if any, given in the Document 33903 for public access to a Transparent copy of the Document, and 33904 likewise the network locations given in the Document for 33905 previous versions it was based on. These may be placed in 33906 the "History" section. You may omit a network location for a 33907 work that was published at least four years before the 33908 Document itself, or if the original publisher of the version 33909 it refers to gives permission. 33910 33911 K. For any section Entitled "Acknowledgements" or "Dedications", 33912 Preserve the Title of the section, and preserve in the 33913 section all the substance and tone of each of the contributor 33914 acknowledgements and/or dedications given therein. 33915 33916 L. Preserve all the Invariant Sections of the Document, 33917 unaltered in their text and in their titles. Section numbers 33918 or the equivalent are not considered part of the section 33919 titles. 33920 33921 M. Delete any section Entitled "Endorsements". Such a section 33922 may not be included in the Modified Version. 33923 33924 N. Do not retitle any existing section to be Entitled 33925 "Endorsements" or to conflict in title with any Invariant 33926 Section. 33927 33928 O. Preserve any Warranty Disclaimers. 33929 33930 If the Modified Version includes new front-matter sections or 33931 appendices that qualify as Secondary Sections and contain no 33932 material copied from the Document, you may at your option 33933 designate some or all of these sections as invariant. To do this, 33934 add their titles to the list of Invariant Sections in the Modified 33935 Version's license notice. These titles must be distinct from any 33936 other section titles. 33937 33938 You may add a section Entitled "Endorsements", provided it contains 33939 nothing but endorsements of your Modified Version by various 33940 parties--for example, statements of peer review or that the text 33941 has been approved by an organization as the authoritative 33942 definition of a standard. 33943 33944 You may add a passage of up to five words as a Front-Cover Text, 33945 and a passage of up to 25 words as a Back-Cover Text, to the end 33946 of the list of Cover Texts in the Modified Version. Only one 33947 passage of Front-Cover Text and one of Back-Cover Text may be 33948 added by (or through arrangements made by) any one entity. If the 33949 Document already includes a cover text for the same cover, 33950 previously added by you or by arrangement made by the same entity 33951 you are acting on behalf of, you may not add another; but you may 33952 replace the old one, on explicit permission from the previous 33953 publisher that added the old one. 33954 33955 The author(s) and publisher(s) of the Document do not by this 33956 License give permission to use their names for publicity for or to 33957 assert or imply endorsement of any Modified Version. 33958 33959 5. COMBINING DOCUMENTS 33960 33961 You may combine the Document with other documents released under 33962 this License, under the terms defined in section 4 above for 33963 modified versions, provided that you include in the combination 33964 all of the Invariant Sections of all of the original documents, 33965 unmodified, and list them all as Invariant Sections of your 33966 combined work in its license notice, and that you preserve all 33967 their Warranty Disclaimers. 33968 33969 The combined work need only contain one copy of this License, and 33970 multiple identical Invariant Sections may be replaced with a single 33971 copy. If there are multiple Invariant Sections with the same name 33972 but different contents, make the title of each such section unique 33973 by adding at the end of it, in parentheses, the name of the 33974 original author or publisher of that section if known, or else a 33975 unique number. Make the same adjustment to the section titles in 33976 the list of Invariant Sections in the license notice of the 33977 combined work. 33978 33979 In the combination, you must combine any sections Entitled 33980 "History" in the various original documents, forming one section 33981 Entitled "History"; likewise combine any sections Entitled 33982 "Acknowledgements", and any sections Entitled "Dedications". You 33983 must delete all sections Entitled "Endorsements." 33984 33985 6. COLLECTIONS OF DOCUMENTS 33986 33987 You may make a collection consisting of the Document and other 33988 documents released under this License, and replace the individual 33989 copies of this License in the various documents with a single copy 33990 that is included in the collection, provided that you follow the 33991 rules of this License for verbatim copying of each of the 33992 documents in all other respects. 33993 33994 You may extract a single document from such a collection, and 33995 distribute it individually under this License, provided you insert 33996 a copy of this License into the extracted document, and follow 33997 this License in all other respects regarding verbatim copying of 33998 that document. 33999 34000 7. AGGREGATION WITH INDEPENDENT WORKS 34001 34002 A compilation of the Document or its derivatives with other 34003 separate and independent documents or works, in or on a volume of 34004 a storage or distribution medium, is called an "aggregate" if the 34005 copyright resulting from the compilation is not used to limit the 34006 legal rights of the compilation's users beyond what the individual 34007 works permit. When the Document is included in an aggregate, this 34008 License does not apply to the other works in the aggregate which 34009 are not themselves derivative works of the Document. 34010 34011 If the Cover Text requirement of section 3 is applicable to these 34012 copies of the Document, then if the Document is less than one half 34013 of the entire aggregate, the Document's Cover Texts may be placed 34014 on covers that bracket the Document within the aggregate, or the 34015 electronic equivalent of covers if the Document is in electronic 34016 form. Otherwise they must appear on printed covers that bracket 34017 the whole aggregate. 34018 34019 8. TRANSLATION 34020 34021 Translation is considered a kind of modification, so you may 34022 distribute translations of the Document under the terms of section 34023 4. Replacing Invariant Sections with translations requires special 34024 permission from their copyright holders, but you may include 34025 translations of some or all Invariant Sections in addition to the 34026 original versions of these Invariant Sections. You may include a 34027 translation of this License, and all the license notices in the 34028 Document, and any Warranty Disclaimers, provided that you also 34029 include the original English version of this License and the 34030 original versions of those notices and disclaimers. In case of a 34031 disagreement between the translation and the original version of 34032 this License or a notice or disclaimer, the original version will 34033 prevail. 34034 34035 If a section in the Document is Entitled "Acknowledgements", 34036 "Dedications", or "History", the requirement (section 4) to 34037 Preserve its Title (section 1) will typically require changing the 34038 actual title. 34039 34040 9. TERMINATION 34041 34042 You may not copy, modify, sublicense, or distribute the Document 34043 except as expressly provided under this License. Any attempt 34044 otherwise to copy, modify, sublicense, or distribute it is void, 34045 and will automatically terminate your rights under this License. 34046 34047 However, if you cease all violation of this License, then your 34048 license from a particular copyright holder is reinstated (a) 34049 provisionally, unless and until the copyright holder explicitly 34050 and finally terminates your license, and (b) permanently, if the 34051 copyright holder fails to notify you of the violation by some 34052 reasonable means prior to 60 days after the cessation. 34053 34054 Moreover, your license from a particular copyright holder is 34055 reinstated permanently if the copyright holder notifies you of the 34056 violation by some reasonable means, this is the first time you have 34057 received notice of violation of this License (for any work) from 34058 that copyright holder, and you cure the violation prior to 30 days 34059 after your receipt of the notice. 34060 34061 Termination of your rights under this section does not terminate 34062 the licenses of parties who have received copies or rights from 34063 you under this License. If your rights have been terminated and 34064 not permanently reinstated, receipt of a copy of some or all of 34065 the same material does not give you any rights to use it. 34066 34067 10. FUTURE REVISIONS OF THIS LICENSE 34068 34069 The Free Software Foundation may publish new, revised versions of 34070 the GNU Free Documentation License from time to time. Such new 34071 versions will be similar in spirit to the present version, but may 34072 differ in detail to address new problems or concerns. See 34073 `http://www.gnu.org/copyleft/'. 34074 34075 Each version of the License is given a distinguishing version 34076 number. If the Document specifies that a particular numbered 34077 version of this License "or any later version" applies to it, you 34078 have the option of following the terms and conditions either of 34079 that specified version or of any later version that has been 34080 published (not as a draft) by the Free Software Foundation. If 34081 the Document does not specify a version number of this License, 34082 you may choose any version ever published (not as a draft) by the 34083 Free Software Foundation. If the Document specifies that a proxy 34084 can decide which future versions of this License can be used, that 34085 proxy's public statement of acceptance of a version permanently 34086 authorizes you to choose that version for the Document. 34087 34088 11. RELICENSING 34089 34090 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 34091 World Wide Web server that publishes copyrightable works and also 34092 provides prominent facilities for anybody to edit those works. A 34093 public wiki that anybody can edit is an example of such a server. 34094 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 34095 site means any set of copyrightable works thus published on the MMC 34096 site. 34097 34098 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 34099 license published by Creative Commons Corporation, a not-for-profit 34100 corporation with a principal place of business in San Francisco, 34101 California, as well as future copyleft versions of that license 34102 published by that same organization. 34103 34104 "Incorporate" means to publish or republish a Document, in whole or 34105 in part, as part of another Document. 34106 34107 An MMC is "eligible for relicensing" if it is licensed under this 34108 License, and if all works that were first published under this 34109 License somewhere other than this MMC, and subsequently 34110 incorporated in whole or in part into the MMC, (1) had no cover 34111 texts or invariant sections, and (2) were thus incorporated prior 34112 to November 1, 2008. 34113 34114 The operator of an MMC Site may republish an MMC contained in the 34115 site under CC-BY-SA on the same site at any time before August 1, 34116 2009, provided the MMC is eligible for relicensing. 34117 34118 34119ADDENDUM: How to use this License for your documents 34120==================================================== 34121 34122To use this License in a document you have written, include a copy of 34123the License in the document and put the following copyright and license 34124notices just after the title page: 34125 34126 Copyright (C) YEAR YOUR NAME. 34127 Permission is granted to copy, distribute and/or modify this document 34128 under the terms of the GNU Free Documentation License, Version 1.3 34129 or any later version published by the Free Software Foundation; 34130 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 34131 Texts. A copy of the license is included in the section entitled ``GNU 34132 Free Documentation License''. 34133 34134 If you have Invariant Sections, Front-Cover Texts and Back-Cover 34135Texts, replace the "with...Texts." line with this: 34136 34137 with the Invariant Sections being LIST THEIR TITLES, with 34138 the Front-Cover Texts being LIST, and with the Back-Cover Texts 34139 being LIST. 34140 34141 If you have Invariant Sections without Cover Texts, or some other 34142combination of the three, merge those two alternatives to suit the 34143situation. 34144 34145 If your document contains nontrivial examples of program code, we 34146recommend releasing these examples in parallel under your choice of 34147free software license, such as the GNU General Public License, to 34148permit their use in free software. 34149 34150 34151File: gdb.info, Node: GDB Index, Prev: GNU Free Documentation License, Up: Top 34152 34153GDB Index 34154********* 34155 34156[index] 34157* Menu: 34158 34159* ! packet: Packets. (line 52) 34160* "No symbol "foo" in current context": Variables. (line 74) 34161* # (a comment): Command Syntax. (line 38) 34162* # in Modula-2: GDB/M2. (line 18) 34163* $: Value History. (line 13) 34164* $$: Value History. (line 13) 34165* $_ and info breakpoints: Set Breaks. (line 128) 34166* $_ and info line: Machine Code. (line 30) 34167* $_, $__, and value history: Memory. (line 109) 34168* $_, convenience variable: Convenience Vars. (line 64) 34169* $__, convenience variable: Convenience Vars. (line 73) 34170* $_exitcode, convenience variable: Convenience Vars. (line 79) 34171* $_sdata, collect: Tracepoint Actions. (line 65) 34172* $_sdata, inspect, convenience variable: Convenience Vars. (line 83) 34173* $_siginfo, convenience variable: Convenience Vars. (line 89) 34174* $_thread, convenience variable: Threads. (line 150) 34175* $_tlb, convenience variable: Convenience Vars. (line 95) 34176* $bpnum, convenience variable: Set Breaks. (line 6) 34177* $cdir, convenience variable: Source Path. (line 108) 34178* $cwd, convenience variable: Source Path. (line 108) 34179* $tpnum: Create and Delete Tracepoints. 34180 (line 98) 34181* $trace_file: Tracepoint Variables. 34182 (line 16) 34183* $trace_frame: Tracepoint Variables. 34184 (line 6) 34185* $trace_func: Tracepoint Variables. 34186 (line 19) 34187* $trace_line: Tracepoint Variables. 34188 (line 13) 34189* $tracepoint: Tracepoint Variables. 34190 (line 10) 34191* --annotate: Mode Options. (line 103) 34192* --args: Mode Options. (line 116) 34193* --batch: Mode Options. (line 23) 34194* --batch-silent: Mode Options. (line 41) 34195* --baud: Mode Options. (line 122) 34196* --cd: Mode Options. (line 82) 34197* --command: File Options. (line 51) 34198* --core: File Options. (line 43) 34199* --directory: File Options. (line 67) 34200* --epoch: Mode Options. (line 98) 34201* --eval-command: File Options. (line 57) 34202* --exec: File Options. (line 35) 34203* --fullname: Mode Options. (line 87) 34204* --interpreter: Mode Options. (line 143) 34205* --nowindows: Mode Options. (line 72) 34206* --nx: Mode Options. (line 11) 34207* --pid: File Options. (line 47) 34208* --quiet: Mode Options. (line 19) 34209* --readnow: File Options. (line 71) 34210* --return-child-result: Mode Options. (line 53) 34211* --se: File Options. (line 39) 34212* --silent: Mode Options. (line 19) 34213* --statistics: Mode Options. (line 160) 34214* --symbols: File Options. (line 31) 34215* --tty: Mode Options. (line 131) 34216* --tui: Mode Options. (line 134) 34217* --version: Mode Options. (line 164) 34218* --windows: Mode Options. (line 78) 34219* --with-gdb-datadir: Data Files. (line 19) 34220* --with-relocated-sources: Source Path. (line 89) 34221* --with-sysroot: Files. (line 434) 34222* --write: Mode Options. (line 155) 34223* -add-inferior: GDB/MI Miscellaneous Commands. 34224 (line 288) 34225* -b: Mode Options. (line 122) 34226* -break-after: GDB/MI Breakpoint Commands. 34227 (line 11) 34228* -break-commands: GDB/MI Breakpoint Commands. 34229 (line 55) 34230* -break-condition: GDB/MI Breakpoint Commands. 34231 (line 88) 34232* -break-delete: GDB/MI Breakpoint Commands. 34233 (line 125) 34234* -break-disable: GDB/MI Breakpoint Commands. 34235 (line 159) 34236* -break-enable: GDB/MI Breakpoint Commands. 34237 (line 195) 34238* -break-info: GDB/MI Breakpoint Commands. 34239 (line 230) 34240* -break-insert: GDB/MI Breakpoint Commands. 34241 (line 250) 34242* -break-list: GDB/MI Breakpoint Commands. 34243 (line 355) 34244* -break-passcount: GDB/MI Breakpoint Commands. 34245 (line 430) 34246* -break-watch: GDB/MI Breakpoint Commands. 34247 (line 442) 34248* -c: File Options. (line 43) 34249* -d: File Options. (line 67) 34250* -data-disassemble: GDB/MI Data Manipulation. 34251 (line 12) 34252* -data-evaluate-expression: GDB/MI Data Manipulation. 34253 (line 140) 34254* -data-list-changed-registers: GDB/MI Data Manipulation. 34255 (line 178) 34256* -data-list-register-names: GDB/MI Data Manipulation. 34257 (line 214) 34258* -data-list-register-values: GDB/MI Data Manipulation. 34259 (line 254) 34260* -data-read-memory: GDB/MI Data Manipulation. 34261 (line 344) 34262* -data-read-memory-bytes: GDB/MI Data Manipulation. 34263 (line 451) 34264* -data-write-memory-bytes: GDB/MI Data Manipulation. 34265 (line 526) 34266* -e: File Options. (line 35) 34267* -enable-pretty-printing: GDB/MI Variable Objects. 34268 (line 116) 34269* -enable-timings: GDB/MI Miscellaneous Commands. 34270 (line 384) 34271* -environment-cd: GDB/MI Program Context. 34272 (line 33) 34273* -environment-directory: GDB/MI Program Context. 34274 (line 56) 34275* -environment-path: GDB/MI Program Context. 34276 (line 100) 34277* -environment-pwd: GDB/MI Program Context. 34278 (line 141) 34279* -ex: File Options. (line 57) 34280* -exec-arguments: GDB/MI Program Context. 34281 (line 9) 34282* -exec-continue: GDB/MI Program Execution. 34283 (line 13) 34284* -exec-finish: GDB/MI Program Execution. 34285 (line 56) 34286* -exec-interrupt: GDB/MI Program Execution. 34287 (line 99) 34288* -exec-jump: GDB/MI Program Execution. 34289 (line 149) 34290* -exec-next: GDB/MI Program Execution. 34291 (line 173) 34292* -exec-next-instruction: GDB/MI Program Execution. 34293 (line 204) 34294* -exec-return: GDB/MI Program Execution. 34295 (line 240) 34296* -exec-run: GDB/MI Program Execution. 34297 (line 283) 34298* -exec-step: GDB/MI Program Execution. 34299 (line 348) 34300* -exec-step-instruction: GDB/MI Program Execution. 34301 (line 390) 34302* -exec-until: GDB/MI Program Execution. 34303 (line 431) 34304* -f: Mode Options. (line 87) 34305* -file-exec-and-symbols: GDB/MI File Commands. 34306 (line 12) 34307* -file-exec-file: GDB/MI File Commands. 34308 (line 40) 34309* -file-list-exec-source-file: GDB/MI File Commands. 34310 (line 67) 34311* -file-list-exec-source-files: GDB/MI File Commands. 34312 (line 93) 34313* -file-symbol-file: GDB/MI File Commands. 34314 (line 123) 34315* -gdb-exit: GDB/MI Miscellaneous Commands. 34316 (line 9) 34317* -gdb-set: GDB/MI Miscellaneous Commands. 34318 (line 31) 34319* -gdb-show: GDB/MI Miscellaneous Commands. 34320 (line 54) 34321* -gdb-version: GDB/MI Miscellaneous Commands. 34322 (line 77) 34323* -inferior-tty-set: GDB/MI Miscellaneous Commands. 34324 (line 335) 34325* -inferior-tty-show: GDB/MI Miscellaneous Commands. 34326 (line 358) 34327* -interpreter-exec: GDB/MI Miscellaneous Commands. 34328 (line 310) 34329* -l: Mode Options. (line 126) 34330* -list-features: GDB/MI Miscellaneous Commands. 34331 (line 111) 34332* -list-target-features: GDB/MI Miscellaneous Commands. 34333 (line 154) 34334* -list-thread-groups: GDB/MI Miscellaneous Commands. 34335 (line 180) 34336* -n: Mode Options. (line 11) 34337* -nw: Mode Options. (line 72) 34338* -p: File Options. (line 47) 34339* -q: Mode Options. (line 19) 34340* -r: File Options. (line 71) 34341* -s: File Options. (line 31) 34342* -stack-info-depth: GDB/MI Stack Manipulation. 34343 (line 35) 34344* -stack-info-frame: GDB/MI Stack Manipulation. 34345 (line 9) 34346* -stack-list-arguments: GDB/MI Stack Manipulation. 34347 (line 73) 34348* -stack-list-frames: GDB/MI Stack Manipulation. 34349 (line 162) 34350* -stack-list-locals: GDB/MI Stack Manipulation. 34351 (line 258) 34352* -stack-list-variables: GDB/MI Stack Manipulation. 34353 (line 298) 34354* -stack-select-frame: GDB/MI Stack Manipulation. 34355 (line 321) 34356* -symbol-list-lines: GDB/MI Symbol Query. (line 9) 34357* -t: Mode Options. (line 131) 34358* -target-attach: GDB/MI Target Manipulation. 34359 (line 9) 34360* -target-detach: GDB/MI Target Manipulation. 34361 (line 36) 34362* -target-disconnect: GDB/MI Target Manipulation. 34363 (line 61) 34364* -target-download: GDB/MI Target Manipulation. 34365 (line 85) 34366* -target-file-delete: GDB/MI File Transfer Commands. 34367 (line 57) 34368* -target-file-get: GDB/MI File Transfer Commands. 34369 (line 33) 34370* -target-file-put: GDB/MI File Transfer Commands. 34371 (line 9) 34372* -target-select: GDB/MI Target Manipulation. 34373 (line 198) 34374* -thread-info: GDB/MI Thread Commands. 34375 (line 9) 34376* -thread-list-ids: GDB/MI Thread Commands. 34377 (line 50) 34378* -thread-select: GDB/MI Thread Commands. 34379 (line 78) 34380* -trace-define-variable: GDB/MI Tracepoint Commands. 34381 (line 83) 34382* -trace-find: GDB/MI Tracepoint Commands. 34383 (line 12) 34384* -trace-list-variables: GDB/MI Tracepoint Commands. 34385 (line 100) 34386* -trace-save: GDB/MI Tracepoint Commands. 34387 (line 143) 34388* -trace-start: GDB/MI Tracepoint Commands. 34389 (line 160) 34390* -trace-status: GDB/MI Tracepoint Commands. 34391 (line 176) 34392* -trace-stop: GDB/MI Tracepoint Commands. 34393 (line 244) 34394* -var-assign: GDB/MI Variable Objects. 34395 (line 484) 34396* -var-create: GDB/MI Variable Objects. 34397 (line 134) 34398* -var-delete: GDB/MI Variable Objects. 34399 (line 230) 34400* -var-evaluate-expression: GDB/MI Variable Objects. 34401 (line 463) 34402* -var-info-expression: GDB/MI Variable Objects. 34403 (line 401) 34404* -var-info-num-children: GDB/MI Variable Objects. 34405 (line 279) 34406* -var-info-path-expression: GDB/MI Variable Objects. 34407 (line 425) 34408* -var-info-type: GDB/MI Variable Objects. 34409 (line 388) 34410* -var-list-children: GDB/MI Variable Objects. 34411 (line 295) 34412* -var-set-format: GDB/MI Variable Objects. 34413 (line 243) 34414* -var-set-frozen: GDB/MI Variable Objects. 34415 (line 622) 34416* -var-set-update-range: GDB/MI Variable Objects. 34417 (line 648) 34418* -var-set-visualizer: GDB/MI Variable Objects. 34419 (line 671) 34420* -var-show-attributes: GDB/MI Variable Objects. 34421 (line 449) 34422* -var-show-format: GDB/MI Variable Objects. 34423 (line 266) 34424* -var-update: GDB/MI Variable Objects. 34425 (line 508) 34426* -w: Mode Options. (line 78) 34427* -x: File Options. (line 51) 34428* ., Modula-2 scope operator: M2 Scope. (line 6) 34429* .build-id directory: Separate Debug Files. 34430 (line 6) 34431* .debug subdirectories: Separate Debug Files. 34432 (line 6) 34433* .debug_gdb_scripts section: .debug_gdb_scripts section. 34434 (line 6) 34435* .gdb_index section: Index Files. (line 6) 34436* .gdbinit: Startup. (line 45) 34437* .gnu_debuglink sections: Separate Debug Files. 34438 (line 78) 34439* .note.gnu.build-id sections: Separate Debug Files. 34440 (line 96) 34441* .o files, reading symbols from: Files. (line 132) 34442* /proc: SVR4 Process Information. 34443 (line 6) 34444* <architecture>: Target Description Format. 34445 (line 73) 34446* <compatible>: Target Description Format. 34447 (line 96) 34448* <feature>: Target Description Format. 34449 (line 120) 34450* <flags>: Target Description Format. 34451 (line 186) 34452* <osabi>: Target Description Format. 34453 (line 83) 34454* <reg>: Target Description Format. 34455 (line 199) 34456* <struct>: Target Description Format. 34457 (line 164) 34458* <union>: Target Description Format. 34459 (line 154) 34460* <vector>: Target Description Format. 34461 (line 147) 34462* ? packet: Packets. (line 61) 34463* @, referencing memory as an array: Arrays. (line 6) 34464* ^connected: GDB/MI Result Records. 34465 (line 22) 34466* ^done: GDB/MI Result Records. 34467 (line 9) 34468* ^error: GDB/MI Result Records. 34469 (line 25) 34470* ^exit: GDB/MI Result Records. 34471 (line 29) 34472* ^running: GDB/MI Result Records. 34473 (line 14) 34474* __init__ on Breakpoint: Breakpoints In Python. 34475 (line 9) 34476* __init__ on Command: Commands In Python. (line 12) 34477* __init__ on Function: Functions In Python. (line 11) 34478* __init__ on Parameter: Parameters In Python. 34479 (line 20) 34480* _NSPrintForDebugger, and printing Objective-C objects: The Print Command with Objective-C. 34481 (line 11) 34482* A packet: Packets. (line 68) 34483* abbreviation: Command Syntax. (line 13) 34484* abort (C-g): Miscellaneous Commands. 34485 (line 10) 34486* accept-line (Newline or Return): Commands For History. 34487 (line 6) 34488* acknowledgment, for GDB remote: Packet Acknowledgment. 34489 (line 6) 34490* actions: Tracepoint Actions. (line 6) 34491* active targets: Active Targets. (line 6) 34492* Ada: Ada. (line 6) 34493* Ada exception catching: Set Catchpoints. (line 19) 34494* Ada mode, general: Ada Mode Intro. (line 6) 34495* Ada task switching: Ada Tasks. (line 115) 34496* Ada tasking and core file debugging: Ada Tasks and Core Files. 34497 (line 6) 34498* Ada, deviations from: Additions to Ada. (line 6) 34499* Ada, omissions from: Omissions from Ada. (line 6) 34500* Ada, problems: Ada Glitches. (line 6) 34501* Ada, tasking: Ada Tasks. (line 6) 34502* add new commands for external monitor: Connecting. (line 105) 34503* add-inferior: Inferiors and Programs. 34504 (line 60) 34505* add-shared-symbol-files: Files. (line 172) 34506* add-symbol-file: Files. (line 113) 34507* add-symbol-file-from-memory: Files. (line 162) 34508* addr_class: Symbols In Python. (line 46) 34509* address <1>: Lazy Strings In Python. 34510 (line 27) 34511* address: Values From Inferior. 34512 (line 45) 34513* address of a symbol: Symbols. (line 44) 34514* address size for remote targets: Remote Configuration. 34515 (line 12) 34516* ADP (Angel Debugger Protocol) logging: ARM. (line 89) 34517* advance LOCATION: Continuing and Stepping. 34518 (line 181) 34519* aggregates (Ada): Omissions from Ada. (line 44) 34520* AIX threads: Debugging Output. (line 28) 34521* alignment of remote memory accesses: Packets. (line 203) 34522* all-stop mode: All-Stop Mode. (line 6) 34523* Alpha stack: MIPS. (line 6) 34524* ambiguous expressions: Ambiguous Expressions. 34525 (line 6) 34526* AMD 29K register stack: A29K. (line 6) 34527* annotations: Annotations Overview. 34528 (line 6) 34529* annotations for errors, warnings and interrupts: Errors. (line 6) 34530* annotations for invalidation messages: Invalidation. (line 6) 34531* annotations for prompts: Prompting. (line 6) 34532* annotations for running programs: Annotations for Running. 34533 (line 6) 34534* annotations for source display: Source Annotations. (line 6) 34535* append: Dump/Restore Files. (line 35) 34536* append data to a file: Dump/Restore Files. (line 6) 34537* apply command to several threads: Threads. (line 156) 34538* apropos: Help. (line 62) 34539* architecture debugging info: Debugging Output. (line 18) 34540* argument count in user-defined commands: Define. (line 25) 34541* arguments (to your program): Arguments. (line 6) 34542* arguments, to gdbserver: Server. (line 34) 34543* arguments, to user-defined commands: Define. (line 6) 34544* ARM 32-bit mode: ARM. (line 25) 34545* ARM RDI: ARM. (line 6) 34546* array aggregates (Ada): Omissions from Ada. (line 44) 34547* array on Type: Types In Python. (line 82) 34548* arrays: Arrays. (line 6) 34549* arrays in expressions: Expressions. (line 14) 34550* artificial array: Arrays. (line 6) 34551* assembly instructions: Machine Code. (line 36) 34552* assf: Files. (line 172) 34553* assignment: Assignment. (line 6) 34554* async output in GDB/MI: GDB/MI Output Syntax. 34555 (line 98) 34556* async records in GDB/MI: GDB/MI Async Records. 34557 (line 6) 34558* asynchronous execution: Background Execution. 34559 (line 6) 34560* asynchronous execution, and process record and replay: Process Record and Replay. 34561 (line 52) 34562* AT&T disassembly flavor: Machine Code. (line 127) 34563* attach: Attach. (line 6) 34564* attach to a program by name: Server. (line 79) 34565* attach&: Background Execution. 34566 (line 38) 34567* auto-loading, Python: Auto-loading. (line 6) 34568* auto-retry, for remote TCP target: Remote Configuration. 34569 (line 119) 34570* automatic display: Auto Display. (line 6) 34571* automatic hardware breakpoints: Set Breaks. (line 283) 34572* automatic overlay debugging: Automatic Overlay Debugging. 34573 (line 6) 34574* automatic thread selection: All-Stop Mode. (line 28) 34575* auxiliary vector: OS Information. (line 21) 34576* AVR: AVR. (line 6) 34577* awatch: Set Watchpoints. (line 68) 34578* b (break): Set Breaks. (line 6) 34579* B packet: Packets. (line 92) 34580* b packet: Packets. (line 77) 34581* background execution: Background Execution. 34582 (line 6) 34583* backtrace: Backtrace. (line 11) 34584* backtrace beyond main function: Backtrace. (line 93) 34585* backtrace limit: Backtrace. (line 129) 34586* backward-char (C-b): Commands For Moving. (line 15) 34587* backward-delete-char (Rubout): Commands For Text. (line 11) 34588* backward-kill-line (C-x Rubout): Commands For Killing. 34589 (line 9) 34590* backward-kill-word (M-<DEL>): Commands For Killing. 34591 (line 24) 34592* backward-word (M-b): Commands For Moving. (line 22) 34593* baud rate for remote targets: Remote Configuration. 34594 (line 21) 34595* bc packet: Packets. (line 97) 34596* bcache statistics: Maintenance Commands. 34597 (line 223) 34598* beginning-of-history (M-<): Commands For History. 34599 (line 19) 34600* beginning-of-line (C-a): Commands For Moving. (line 6) 34601* bell-style: Readline Init File Syntax. 34602 (line 35) 34603* bind-tty-special-chars: Readline Init File Syntax. 34604 (line 42) 34605* bits in remote address: Remote Configuration. 34606 (line 12) 34607* block on Frame: Frames In Python. (line 58) 34608* block_for_pc: Blocks In Python. (line 17) 34609* blocks in python: Blocks In Python. (line 6) 34610* bookmark: Checkpoint/Restart. (line 6) 34611* BP_ACCESS_WATCHPOINT: Breakpoints In Python. 34612 (line 92) 34613* BP_BREAKPOINT: Breakpoints In Python. 34614 (line 80) 34615* BP_HARDWARE_WATCHPOINT: Breakpoints In Python. 34616 (line 86) 34617* BP_READ_WATCHPOINT: Breakpoints In Python. 34618 (line 89) 34619* BP_WATCHPOINT: Breakpoints In Python. 34620 (line 83) 34621* break: Set Breaks. (line 6) 34622* break ... task TASKNO (Ada): Ada Tasks. (line 135) 34623* break ... thread THREADNO: Thread-Specific Breakpoints. 34624 (line 10) 34625* break in overloaded functions: Debugging C Plus Plus. 34626 (line 9) 34627* break on a system call.: Set Catchpoints. (line 48) 34628* break on fork/exec: Set Catchpoints. (line 43) 34629* BREAK signal instead of Ctrl-C: Remote Configuration. 34630 (line 29) 34631* break, and Objective-C: Method Names in Commands. 34632 (line 9) 34633* breakpoint address adjusted: Breakpoint-related Warnings. 34634 (line 6) 34635* breakpoint annotation: Annotations for Running. 34636 (line 47) 34637* breakpoint commands: Break Commands. (line 6) 34638* breakpoint commands for GDB/MI: GDB/MI Breakpoint Commands. 34639 (line 6) 34640* breakpoint conditions: Conditions. (line 6) 34641* breakpoint numbers: Breakpoints. (line 41) 34642* breakpoint on events: Breakpoints. (line 33) 34643* breakpoint on memory address: Breakpoints. (line 20) 34644* breakpoint on variable modification: Breakpoints. (line 20) 34645* breakpoint ranges: Breakpoints. (line 48) 34646* breakpoint subroutine, remote: Stub Contents. (line 31) 34647* breakpointing Ada elaboration code: Stopping Before Main Program. 34648 (line 6) 34649* breakpoints <1>: Basic Python. (line 32) 34650* breakpoints: Breakpoints. (line 6) 34651* breakpoints and tasks, in Ada: Ada Tasks. (line 135) 34652* breakpoints and threads: Thread-Specific Breakpoints. 34653 (line 10) 34654* breakpoints at functions matching a regexp: Set Breaks. (line 92) 34655* breakpoints in overlays: Overlay Commands. (line 93) 34656* breakpoints in python: Breakpoints In Python. 34657 (line 6) 34658* breakpoints, multiple locations: Set Breaks. (line 189) 34659* breakpoints-invalid annotation: Invalidation. (line 13) 34660* bs packet: Packets. (line 103) 34661* bt (backtrace): Backtrace. (line 11) 34662* bug criteria: Bug Criteria. (line 6) 34663* bug reports: Bug Reporting. (line 6) 34664* bugs in GDB: GDB Bugs. (line 6) 34665* build ID sections: Separate Debug Files. 34666 (line 96) 34667* build ID, and separate debugging files: Separate Debug Files. 34668 (line 6) 34669* building GDB, requirements for: Requirements. (line 6) 34670* built-in simulator target: Target Commands. (line 73) 34671* c (continue): Continuing and Stepping. 34672 (line 15) 34673* c (SingleKey TUI key): TUI Single Key Mode. (line 10) 34674* C and C++: C. (line 6) 34675* C and C++ checks: C Checks. (line 6) 34676* C and C++ constants: C Constants. (line 6) 34677* C and C++ defaults: C Defaults. (line 6) 34678* C and C++ operators: C Operators. (line 6) 34679* C packet: Packets. (line 116) 34680* c packet: Packets. (line 110) 34681* C++: C. (line 10) 34682* C++ compilers: C Plus Plus Expressions. 34683 (line 8) 34684* C++ exception handling: Debugging C Plus Plus. 34685 (line 20) 34686* C++ overload debugging info: Debugging Output. (line 108) 34687* C++ scope resolution: Variables. (line 54) 34688* C++ symbol decoding style: Print Settings. (line 296) 34689* C++ symbol display: Debugging C Plus Plus. 34690 (line 29) 34691* C-L: TUI Keys. (line 65) 34692* C-x 1: TUI Keys. (line 19) 34693* C-x 2: TUI Keys. (line 26) 34694* C-x A: TUI Keys. (line 12) 34695* C-x a: TUI Keys. (line 11) 34696* C-x C-a: TUI Keys. (line 10) 34697* C-x o: TUI Keys. (line 34) 34698* C-x s: TUI Keys. (line 41) 34699* caching data of remote targets: Caching Remote Data. (line 6) 34700* call: Calling. (line 10) 34701* call dummy stack unwinding: Calling. (line 35) 34702* call dummy stack unwinding on unhandled exception.: Calling. 34703 (line 46) 34704* call overloaded functions: C Plus Plus Expressions. 34705 (line 27) 34706* call stack: Stack. (line 9) 34707* call stack traces: Backtrace. (line 6) 34708* call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) 34709* calling functions: Calling. (line 6) 34710* calling make: Shell Commands. (line 19) 34711* capitalize-word (M-c): Commands For Text. (line 49) 34712* case sensitivity in symbol names: Symbols. (line 27) 34713* case-insensitive symbol names: Symbols. (line 27) 34714* cast on Value: Values From Inferior. 34715 (line 71) 34716* casts, in expressions: Expressions. (line 28) 34717* casts, to view memory: Expressions. (line 43) 34718* catch: Set Catchpoints. (line 10) 34719* catch Ada exceptions: Set Catchpoints. (line 19) 34720* catch exceptions, list active handlers: Frame Info. (line 60) 34721* catchpoints: Breakpoints. (line 33) 34722* catchpoints, setting: Set Catchpoints. (line 6) 34723* cd: Working Directory. (line 16) 34724* cdir: Source Path. (line 108) 34725* Cell Broadband Engine: SPU. (line 6) 34726* change working directory: Working Directory. (line 16) 34727* character sets: Character Sets. (line 6) 34728* character-search (C-]): Miscellaneous Commands. 34729 (line 41) 34730* character-search-backward (M-C-]): Miscellaneous Commands. 34731 (line 46) 34732* charset: Character Sets. (line 6) 34733* checkpoint: Checkpoint/Restart. (line 6) 34734* checkpoints and process id: Checkpoint/Restart. (line 80) 34735* checks, range: Type Checking. (line 65) 34736* checks, type: Checks. (line 31) 34737* checksum, for GDB remote: Overview. (line 20) 34738* children on pretty printer: Pretty Printing API. (line 12) 34739* choosing target byte order: Byte Order. (line 6) 34740* circular trace buffer: Starting and Stopping Trace Experiments. 34741 (line 74) 34742* clear: Delete Breaks. (line 21) 34743* clear, and Objective-C: Method Names in Commands. 34744 (line 9) 34745* clear-screen (C-l): Commands For Moving. (line 26) 34746* clearing breakpoints, watchpoints, catchpoints: Delete Breaks. 34747 (line 6) 34748* clone-inferior: Inferiors and Programs. 34749 (line 67) 34750* close, file-i/o system call: close. (line 6) 34751* closest symbol and offset for an address: Symbols. (line 54) 34752* code: Types In Python. (line 24) 34753* code address and its source line: Machine Code. (line 25) 34754* collect (tracepoints): Tracepoint Actions. (line 49) 34755* collected data discarded: Starting and Stopping Trace Experiments. 34756 (line 6) 34757* colon, doubled as scope operator: M2 Scope. (line 6) 34758* colon-colon, context for variables/functions: Variables. (line 44) 34759* colon-colon, in Modula-2: M2 Scope. (line 6) 34760* command editing: Readline Bare Essentials. 34761 (line 6) 34762* command files: Command Files. (line 6) 34763* command history: Command History. (line 6) 34764* command hooks: Hooks. (line 6) 34765* command interpreters: Interpreters. (line 6) 34766* command line editing: Editing. (line 6) 34767* command scripts, debugging: Messages/Warnings. (line 67) 34768* command tracing: Messages/Warnings. (line 62) 34769* COMMAND_BREAKPOINTS: Commands In Python. (line 145) 34770* COMMAND_DATA: Commands In Python. (line 115) 34771* COMMAND_FILES: Commands In Python. (line 126) 34772* COMMAND_MAINTENANCE: Commands In Python. (line 163) 34773* COMMAND_NONE: Commands In Python. (line 105) 34774* COMMAND_OBSCURE: Commands In Python. (line 157) 34775* COMMAND_RUNNING: Commands In Python. (line 109) 34776* COMMAND_STACK: Commands In Python. (line 120) 34777* COMMAND_STATUS: Commands In Python. (line 139) 34778* COMMAND_SUPPORT: Commands In Python. (line 132) 34779* COMMAND_TRACEPOINTS: Commands In Python. (line 151) 34780* commands <1>: Breakpoints In Python. 34781 (line 118) 34782* commands: Break Commands. (line 11) 34783* commands annotation: Prompting. (line 27) 34784* commands for C++: Debugging C Plus Plus. 34785 (line 6) 34786* commands in python: Commands In Python. (line 6) 34787* commands to access python: Python Commands. (line 6) 34788* comment: Command Syntax. (line 38) 34789* comment-begin: Readline Init File Syntax. 34790 (line 47) 34791* COMMON blocks, Fortran: Special Fortran Commands. 34792 (line 9) 34793* common targets: Target Commands. (line 46) 34794* compare-sections: Memory. (line 129) 34795* compatibility, GDB/MI and CLI: GDB/MI Compatibility with CLI. 34796 (line 6) 34797* compilation directory: Source Path. (line 108) 34798* compiling, on Sparclet: Sparclet. (line 16) 34799* complete: Help. (line 76) 34800* complete (<TAB>): Commands For Completion. 34801 (line 6) 34802* complete on Command: Commands In Python. (line 73) 34803* COMPLETE_COMMAND: Commands In Python. (line 184) 34804* COMPLETE_FILENAME: Commands In Python. (line 177) 34805* COMPLETE_LOCATION: Commands In Python. (line 180) 34806* COMPLETE_NONE: Commands In Python. (line 174) 34807* COMPLETE_SYMBOL: Commands In Python. (line 188) 34808* completion: Completion. (line 6) 34809* completion of Python commands: Commands In Python. (line 72) 34810* completion of quoted strings: Completion. (line 57) 34811* completion of structure field names: Completion. (line 96) 34812* completion of union field names: Completion. (line 96) 34813* completion-query-items: Readline Init File Syntax. 34814 (line 57) 34815* compressed debug sections: Requirements. (line 39) 34816* condition <1>: Breakpoints In Python. 34817 (line 113) 34818* condition: Conditions. (line 45) 34819* conditional breakpoints: Conditions. (line 6) 34820* conditional tracepoints: Tracepoint Conditions. 34821 (line 6) 34822* configuring GDB: Running Configure. (line 6) 34823* confirmation: Messages/Warnings. (line 50) 34824* connection timeout, for remote TCP target: Remote Configuration. 34825 (line 134) 34826* console i/o as part of file-i/o: Console I/O. (line 6) 34827* console interpreter: Interpreters. (line 21) 34828* console output in GDB/MI: GDB/MI Output Syntax. 34829 (line 106) 34830* const on Type: Types In Python. (line 91) 34831* constants, in file-i/o protocol: Constants. (line 6) 34832* continue: Continuing and Stepping. 34833 (line 15) 34834* continue&: Background Execution. 34835 (line 53) 34836* continuing: Continuing and Stepping. 34837 (line 6) 34838* continuing threads: Thread Stops. (line 6) 34839* control C, and remote debugging: Bootstrapping. (line 25) 34840* controlling terminal: Input/Output. (line 23) 34841* convenience functions: Convenience Vars. (line 106) 34842* convenience functions in python: Functions In Python. (line 6) 34843* convenience variables: Convenience Vars. (line 6) 34844* convenience variables for tracepoints: Tracepoint Variables. 34845 (line 6) 34846* convenience variables, and trace state variables: Trace State Variables. 34847 (line 17) 34848* convenience variables, initializing: Convenience Vars. (line 41) 34849* convert-meta: Readline Init File Syntax. 34850 (line 67) 34851* copy-backward-word (): Commands For Killing. 34852 (line 49) 34853* copy-forward-word (): Commands For Killing. 34854 (line 54) 34855* copy-region-as-kill (): Commands For Killing. 34856 (line 45) 34857* core dump file: Files. (line 6) 34858* core dump file target: Target Commands. (line 54) 34859* core-file: Files. (line 97) 34860* crash of debugger: Bug Criteria. (line 9) 34861* CRC algorithm definition: Separate Debug Files. 34862 (line 140) 34863* CRC of memory block, remote request: General Query Packets. 34864 (line 73) 34865* CRIS: CRIS. (line 6) 34866* CRIS mode: CRIS. (line 26) 34867* CRIS version: CRIS. (line 10) 34868* Ctrl-BREAK, MS-Windows: Cygwin Native. (line 9) 34869* ctrl-c message, in file-i/o protocol: The Ctrl-C Message. (line 6) 34870* Ctrl-o (operate-and-get-next): Command Syntax. (line 42) 34871* current Ada task ID: Ada Tasks. (line 105) 34872* current directory: Source Path. (line 108) 34873* current stack frame: Frames. (line 45) 34874* current thread: Threads. (line 45) 34875* current thread, remote request: General Query Packets. 34876 (line 62) 34877* current_objfile: Objfiles In Python. (line 16) 34878* current_progspace: Progspaces In Python. 34879 (line 15) 34880* cwd: Source Path. (line 108) 34881* Cygwin DLL, debugging: Cygwin Native. (line 42) 34882* Cygwin-specific commands: Cygwin Native. (line 6) 34883* D: D. (line 6) 34884* d (delete): Delete Breaks. (line 41) 34885* d (SingleKey TUI key): TUI Single Key Mode. (line 13) 34886* D packet: Packets. (line 129) 34887* d packet: Packets. (line 122) 34888* Darwin: Darwin. (line 6) 34889* data breakpoints: Breakpoints. (line 20) 34890* data manipulation, in GDB/MI: GDB/MI Data Manipulation. 34891 (line 6) 34892* dead names, GNU Hurd: Hurd Native. (line 85) 34893* debug expression parser: Debugging Output. (line 114) 34894* debug formats and C++: C Plus Plus Expressions. 34895 (line 8) 34896* debug link sections: Separate Debug Files. 34897 (line 78) 34898* debug remote protocol: Debugging Output. (line 123) 34899* debug_chaos: M32R/D. (line 50) 34900* debugger crash: Bug Criteria. (line 9) 34901* debugging C++ programs: C Plus Plus Expressions. 34902 (line 8) 34903* debugging information directory, global: Separate Debug Files. 34904 (line 6) 34905* debugging information in separate files: Separate Debug Files. 34906 (line 6) 34907* debugging libthread_db: Threads. (line 213) 34908* debugging multiple processes: Forks. (line 52) 34909* debugging multithreaded programs (on HP-UX): Threads. (line 89) 34910* debugging optimized code: Optimized Code. (line 6) 34911* debugging stub, example: Remote Stub. (line 6) 34912* debugging target: Targets. (line 6) 34913* debugging the Cygwin DLL: Cygwin Native. (line 42) 34914* decimal floating point format: Decimal Floating Point. 34915 (line 6) 34916* decode_line: Basic Python. (line 127) 34917* default collection action: Tracepoint Actions. (line 114) 34918* default data directory: Data Files. (line 19) 34919* default source path substitution: Source Path. (line 89) 34920* default system root: Files. (line 434) 34921* default_visualizer: Pretty Printing API. (line 86) 34922* define: Define. (line 37) 34923* define trace state variable, remote request: Tracepoint Packets. 34924 (line 121) 34925* defining macros interactively: Macros. (line 52) 34926* definition, showing a macro's: Macros. (line 47) 34927* delete: Delete Breaks. (line 41) 34928* delete breakpoints: Delete Breaks. (line 41) 34929* delete checkpoint CHECKPOINT-ID: Checkpoint/Restart. (line 56) 34930* delete display: Auto Display. (line 45) 34931* delete mem: Memory Region Attributes. 34932 (line 34) 34933* delete tracepoint: Create and Delete Tracepoints. 34934 (line 101) 34935* delete tvariable: Trace State Variables. 34936 (line 42) 34937* delete-char (C-d): Commands For Text. (line 6) 34938* delete-char-or-list (): Commands For Completion. 34939 (line 30) 34940* delete-horizontal-space (): Commands For Killing. 34941 (line 37) 34942* deleting breakpoints, watchpoints, catchpoints: Delete Breaks. 34943 (line 6) 34944* deliver a signal to a program: Signaling. (line 6) 34945* demangling C++ names: Print Settings. (line 277) 34946* deprecated commands: Maintenance Commands. 34947 (line 90) 34948* dereference on Value: Values From Inferior. 34949 (line 77) 34950* derived type of an object, printing: Print Settings. (line 329) 34951* descriptor tables display: DJGPP Native. (line 24) 34952* detach: Attach. (line 36) 34953* detach (remote): Connecting. (line 91) 34954* detach from task, GNU Hurd: Hurd Native. (line 60) 34955* detach from thread, GNU Hurd: Hurd Native. (line 110) 34956* detach inferior INFNO: Inferiors and Programs. 34957 (line 97) 34958* digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6) 34959* dir: Source Path. (line 39) 34960* direct memory access (DMA) on MS-DOS: DJGPP Native. (line 75) 34961* directories for source files: Source Path. (line 6) 34962* directory: Source Path. (line 39) 34963* directory, compilation: Source Path. (line 108) 34964* directory, current: Source Path. (line 108) 34965* dis (disable): Disabling. (line 38) 34966* disable: Disabling. (line 38) 34967* disable display: Auto Display. (line 52) 34968* disable mem: Memory Region Attributes. 34969 (line 38) 34970* disable tracepoint: Enable and Disable Tracepoints. 34971 (line 9) 34972* disable-completion: Readline Init File Syntax. 34973 (line 73) 34974* disabling pretty-printers: Disabling Pretty-Printers. 34975 (line 6) 34976* disassemble: Machine Code. (line 36) 34977* disconnect: Connecting. (line 98) 34978* disconnected tracing: Starting and Stopping Trace Experiments. 34979 (line 38) 34980* displaced stepping debugging info: Debugging Output. (line 42) 34981* displaced stepping support: Maintenance Commands. 34982 (line 56) 34983* displaced stepping, and process record and replay: Process Record and Replay. 34984 (line 47) 34985* display: Auto Display. (line 23) 34986* display command history: Command History. (line 78) 34987* display derived types: Print Settings. (line 329) 34988* display disabled out of scope: Auto Display. (line 74) 34989* display GDB copyright: Help. (line 136) 34990* display of expressions: Auto Display. (line 6) 34991* display remote monitor communications: Target Commands. (line 108) 34992* display remote packets: Debugging Output. (line 123) 34993* display_hint on pretty printer: Pretty Printing API. (line 25) 34994* DJGPP debugging: DJGPP Native. (line 6) 34995* dll-symbols: Cygwin Native. (line 38) 34996* DLLs with no debugging symbols: Non-debug DLL Symbols. 34997 (line 6) 34998* do (down): Selection. (line 34) 34999* do not print frame argument values: Print Settings. (line 135) 35000* do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. 35001 (line 14) 35002* document: Define. (line 49) 35003* documentation: Formatting Documentation. 35004 (line 22) 35005* don't repeat command: Define. (line 61) 35006* don't repeat Python command: Commands In Python. (line 43) 35007* dont-repeat: Define. (line 61) 35008* dont_repeat on Command: Commands In Python. (line 44) 35009* DOS file-name semantics of file names.: Files. (line 457) 35010* DOS serial data link, remote debugging: DJGPP Native. (line 121) 35011* DOS serial port status: DJGPP Native. (line 142) 35012* Down: TUI Keys. (line 56) 35013* down: Selection. (line 34) 35014* down-silently: Selection. (line 58) 35015* downcase-word (M-l): Commands For Text. (line 45) 35016* download server address (M32R): M32R/D. (line 27) 35017* download to Sparclet: Sparclet Download. (line 6) 35018* download to VxWorks: VxWorks Download. (line 6) 35019* DPMI: DJGPP Native. (line 6) 35020* dump: Dump/Restore Files. (line 13) 35021* dump all data collected at tracepoint: tdump. (line 6) 35022* dump core from inferior: Core File Generation. 35023 (line 6) 35024* dump data to a file: Dump/Restore Files. (line 6) 35025* dump-functions (): Miscellaneous Commands. 35026 (line 61) 35027* dump-macros (): Miscellaneous Commands. 35028 (line 73) 35029* dump-variables (): Miscellaneous Commands. 35030 (line 67) 35031* dump/restore files: Dump/Restore Files. (line 6) 35032* DVC register: PowerPC Embedded. (line 6) 35033* DWARF 2 compilation units cache: Maintenance Commands. 35034 (line 281) 35035* DWARF-2 CFI and CRIS: CRIS. (line 18) 35036* DWARF2 DIEs: Debugging Output. (line 35) 35037* dynamic linking: Files. (line 113) 35038* dynamic varobj: GDB/MI Variable Objects. 35039 (line 164) 35040* dynamic_cast on Value: Values From Inferior. 35041 (line 93) 35042* dynamic_type: Values From Inferior. 35043 (line 59) 35044* e (edit): Edit. (line 6) 35045* echo: Output. (line 12) 35046* edit: Edit. (line 6) 35047* editing: Editing. (line 15) 35048* editing command lines: Readline Bare Essentials. 35049 (line 6) 35050* editing source files: Edit. (line 6) 35051* editing-mode: Readline Init File Syntax. 35052 (line 78) 35053* eight-bit characters in strings: Print Settings. (line 222) 35054* elaboration phase: Starting. (line 90) 35055* else: Command Files. (line 75) 35056* Emacs: Emacs. (line 6) 35057* empty response, for unsupported packets: Standard Replies. (line 10) 35058* enable: Disabling. (line 45) 35059* enable display: Auto Display. (line 57) 35060* enable mem: Memory Region Attributes. 35061 (line 42) 35062* enable tracepoint: Enable and Disable Tracepoints. 35063 (line 15) 35064* enable-keypad: Readline Init File Syntax. 35065 (line 84) 35066* enable/disable a breakpoint: Disabling. (line 6) 35067* enabled: Breakpoints In Python. 35068 (line 41) 35069* encoding: Lazy Strings In Python. 35070 (line 37) 35071* end: Blocks In Python. (line 28) 35072* end (breakpoint commands): Break Commands. (line 11) 35073* end (if/else/while commands): Command Files. (line 104) 35074* end (user-defined commands): Define. (line 49) 35075* end-kbd-macro (C-x )): Keyboard Macros. (line 9) 35076* end-of-history (M->): Commands For History. 35077 (line 22) 35078* end-of-line (C-e): Commands For Moving. (line 9) 35079* entering numbers: Numbers. (line 6) 35080* environment (of your program): Environment. (line 6) 35081* errno values, in file-i/o protocol: Errno Values. (line 6) 35082* error annotation: Errors. (line 10) 35083* error on valid input: Bug Criteria. (line 12) 35084* error-begin annotation: Errors. (line 22) 35085* eval: Output. (line 117) 35086* event debugging info: Debugging Output. (line 50) 35087* event designators: Event Designators. (line 6) 35088* event handling: Set Catchpoints. (line 6) 35089* examine process image: SVR4 Process Information. 35090 (line 6) 35091* examining data: Data. (line 6) 35092* examining memory: Memory. (line 9) 35093* exception handlers: Set Catchpoints. (line 6) 35094* exception handlers, how to list: Frame Info. (line 60) 35095* exceptionHandler: Bootstrapping. (line 38) 35096* exceptions, python: Exception Handling. (line 6) 35097* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. 35098 (line 36) 35099* exec-file: Files. (line 39) 35100* executable file: Files. (line 16) 35101* executable file target: Target Commands. (line 50) 35102* executable file, for remote target: Remote Configuration. 35103 (line 79) 35104* execute: Basic Python. (line 15) 35105* execute commands from a file: Command Files. (line 17) 35106* execute forward or backward in time: Reverse Execution. (line 87) 35107* execute remote command, remote request: General Query Packets. 35108 (line 261) 35109* execution, foreground, background and asynchronous: Background Execution. 35110 (line 6) 35111* exited annotation: Annotations for Running. 35112 (line 18) 35113* exiting GDB: Quitting GDB. (line 6) 35114* expand macro once: Macros. (line 38) 35115* expand-tilde: Readline Init File Syntax. 35116 (line 89) 35117* expanding preprocessor macros: Macros. (line 29) 35118* expression: Breakpoints In Python. 35119 (line 107) 35120* expression debugging info: Debugging Output. (line 57) 35121* expression parser, debugging info: Debugging Output. (line 114) 35122* expressions: Expressions. (line 6) 35123* expressions in Ada: Ada. (line 11) 35124* expressions in C or C++: C. (line 6) 35125* expressions in C++: C Plus Plus Expressions. 35126 (line 6) 35127* expressions in Modula-2: Modula-2. (line 12) 35128* extend GDB for remote targets: Connecting. (line 105) 35129* extending GDB: Extending GDB. (line 6) 35130* extra signal information: Signals. (line 102) 35131* f (frame): Selection. (line 11) 35132* f (SingleKey TUI key): TUI Single Key Mode. (line 16) 35133* F packet: Packets. (line 143) 35134* F reply packet: The F Reply Packet. (line 6) 35135* F request packet: The F Request Packet. 35136 (line 6) 35137* fast tracepoints: Set Tracepoints. (line 24) 35138* fast tracepoints, setting: Create and Delete Tracepoints. 35139 (line 40) 35140* fatal signal: Bug Criteria. (line 9) 35141* fatal signals: Signals. (line 15) 35142* features of the remote protocol: General Query Packets. 35143 (line 315) 35144* fg (resume foreground execution): Continuing and Stepping. 35145 (line 15) 35146* fields on Type: Types In Python. (line 41) 35147* file: Files. (line 16) 35148* file transfer: File Transfer. (line 6) 35149* file transfer, remote protocol: Host I/O Packets. (line 6) 35150* file-i/o examples: File-I/O Examples. (line 6) 35151* file-i/o overview: File-I/O Overview. (line 6) 35152* File-I/O remote protocol extension: File-I/O Remote Protocol Extension. 35153 (line 6) 35154* file-i/o reply packet: The F Reply Packet. (line 6) 35155* file-i/o request packet: The F Request Packet. 35156 (line 6) 35157* filename <1>: Symbol Tables In Python. 35158 (line 31) 35159* filename <2>: Objfiles In Python. (line 29) 35160* filename: Progspaces In Python. 35161 (line 25) 35162* fin (finish): Continuing and Stepping. 35163 (line 110) 35164* find: Searching Memory. (line 9) 35165* find downloadable SREC files (M32R): M32R/D. (line 15) 35166* find trace snapshot: tfind. (line 6) 35167* find_sal on Frame: Frames In Python. (line 71) 35168* finish: Continuing and Stepping. 35169 (line 110) 35170* finish&: Background Execution. 35171 (line 56) 35172* flinching: Messages/Warnings. (line 50) 35173* float promotion: ABI. (line 29) 35174* floating point: Floating Point Hardware. 35175 (line 6) 35176* floating point registers: Registers. (line 15) 35177* floating point, MIPS remote: MIPS Embedded. (line 60) 35178* flush: Basic Python. (line 108) 35179* flush_i_cache: Bootstrapping. (line 60) 35180* flushregs: Maintenance Commands. 35181 (line 208) 35182* focus: TUI Commands. (line 40) 35183* focus of debugging: Threads. (line 45) 35184* foo: Symbol Errors. (line 50) 35185* foreground execution: Background Execution. 35186 (line 6) 35187* fork, debugging programs which call: Forks. (line 6) 35188* format options: Print Settings. (line 6) 35189* formatted output: Output Formats. (line 6) 35190* Fortran: Summary. (line 37) 35191* Fortran Defaults: Fortran Defaults. (line 6) 35192* Fortran operators and expressions: Fortran Operators. (line 6) 35193* Fortran-specific support in GDB: Fortran. (line 6) 35194* forward-backward-delete-char (): Commands For Text. (line 15) 35195* forward-char (C-f): Commands For Moving. (line 12) 35196* forward-search: Search. (line 9) 35197* forward-search-history (C-s): Commands For History. 35198 (line 30) 35199* forward-word (M-f): Commands For Moving. (line 18) 35200* FR-V shared-library debugging: Debugging Output. (line 141) 35201* frame debugging info: Debugging Output. (line 65) 35202* frame number: Frames. (line 28) 35203* frame pointer: Frames. (line 21) 35204* frame pointer register: Registers. (line 26) 35205* frame, command: Frames. (line 45) 35206* frame, definition: Frames. (line 6) 35207* frame, selecting: Selection. (line 11) 35208* frame_stop_reason_string: Frames In Python. (line 26) 35209* frameless execution: Frames. (line 34) 35210* frames in python: Frames In Python. (line 6) 35211* frames-invalid annotation: Invalidation. (line 9) 35212* free memory information (MS-DOS): DJGPP Native. (line 19) 35213* fstat, file-i/o system call: stat/fstat. (line 6) 35214* ftrace: Create and Delete Tracepoints. 35215 (line 40) 35216* Fujitsu: Remote Stub. (line 69) 35217* full symbol tables, listing GDB's internal: Symbols. (line 278) 35218* fullname on Symtab: Symbol Tables In Python. 35219 (line 41) 35220* function: Blocks In Python. (line 31) 35221* Function: Functions In Python. (line 6) 35222* function call arguments, optimized out: Backtrace. (line 71) 35223* function entry/exit, wrong values of variables: Variables. (line 58) 35224* function on Frame: Frames In Python. (line 61) 35225* functions without line info, and stepping: Continuing and Stepping. 35226 (line 93) 35227* G packet: Packets. (line 161) 35228* g packet: Packets. (line 148) 35229* g++, GNU C++ compiler: C. (line 10) 35230* garbled pointers: DJGPP Native. (line 42) 35231* GCC and C++: C Plus Plus Expressions. 35232 (line 8) 35233* gcore: Core File Generation. 35234 (line 18) 35235* GDB bugs, reporting: Bug Reporting. (line 6) 35236* GDB internal error: Maintenance Commands. 35237 (line 124) 35238* gdb module: Basic Python. (line 6) 35239* GDB reference card: Formatting Documentation. 35240 (line 6) 35241* GDB startup: Startup. (line 6) 35242* GDB version number: Help. (line 126) 35243* gdb.Block: Blocks In Python. (line 6) 35244* gdb.block_for_pc: Blocks In Python. (line 16) 35245* gdb.BP_ACCESS_WATCHPOINT: Breakpoints In Python. 35246 (line 92) 35247* gdb.BP_BREAKPOINT: Breakpoints In Python. 35248 (line 80) 35249* gdb.BP_HARDWARE_WATCHPOINT: Breakpoints In Python. 35250 (line 86) 35251* gdb.BP_READ_WATCHPOINT: Breakpoints In Python. 35252 (line 89) 35253* gdb.BP_WATCHPOINT: Breakpoints In Python. 35254 (line 83) 35255* gdb.Breakpoint: Breakpoints In Python. 35256 (line 6) 35257* gdb.breakpoints: Basic Python. (line 31) 35258* gdb.COMMAND_BREAKPOINTS: Commands In Python. (line 145) 35259* gdb.COMMAND_DATA: Commands In Python. (line 115) 35260* gdb.COMMAND_FILES: Commands In Python. (line 126) 35261* gdb.COMMAND_MAINTENANCE: Commands In Python. (line 163) 35262* gdb.COMMAND_NONE: Commands In Python. (line 105) 35263* gdb.COMMAND_OBSCURE: Commands In Python. (line 157) 35264* gdb.COMMAND_RUNNING: Commands In Python. (line 109) 35265* gdb.COMMAND_STACK: Commands In Python. (line 120) 35266* gdb.COMMAND_STATUS: Commands In Python. (line 139) 35267* gdb.COMMAND_SUPPORT: Commands In Python. (line 132) 35268* gdb.COMMAND_TRACEPOINTS: Commands In Python. (line 151) 35269* gdb.COMPLETE_COMMAND: Commands In Python. (line 184) 35270* gdb.COMPLETE_FILENAME: Commands In Python. (line 177) 35271* gdb.COMPLETE_LOCATION: Commands In Python. (line 180) 35272* gdb.COMPLETE_NONE: Commands In Python. (line 174) 35273* gdb.COMPLETE_SYMBOL: Commands In Python. (line 188) 35274* gdb.current_objfile: Objfiles In Python. (line 15) 35275* gdb.current_progspace: Progspaces In Python. 35276 (line 14) 35277* gdb.decode_line: Basic Python. (line 126) 35278* gdb.default_visualizer: Pretty Printing API. (line 85) 35279* gdb.execute: Basic Python. (line 14) 35280* gdb.flush: Basic Python. (line 107) 35281* gdb.Function: Functions In Python. (line 6) 35282* gdb.GdbError: Exception Handling. (line 27) 35283* gdb.history: Basic Python. (line 45) 35284* gdb.Inferior: Inferiors In Python. (line 6) 35285* gdb.InferiorThread: Threads In Python. (line 6) 35286* gdb.ini: Startup. (line 45) 35287* gdb.LazyString: Lazy Strings In Python. 35288 (line 6) 35289* gdb.lookup_symbol: Symbols In Python. (line 13) 35290* gdb.lookup_type: Types In Python. (line 11) 35291* gdb.Objfile: Objfiles In Python. (line 6) 35292* gdb.objfiles: Objfiles In Python. (line 21) 35293* gdb.PARAM_AUTO_BOOLEAN: Parameters In Python. 35294 (line 78) 35295* gdb.PARAM_BOOLEAN: Parameters In Python. 35296 (line 74) 35297* gdb.PARAM_ENUM: Parameters In Python. 35298 (line 112) 35299* gdb.PARAM_FILENAME: Parameters In Python. 35300 (line 104) 35301* gdb.PARAM_INTEGER: Parameters In Python. 35302 (line 87) 35303* gdb.PARAM_OPTIONAL_FILENAME: Parameters In Python. 35304 (line 101) 35305* gdb.PARAM_STRING: Parameters In Python. 35306 (line 91) 35307* gdb.PARAM_STRING_NOESCAPE: Parameters In Python. 35308 (line 97) 35309* gdb.PARAM_UINTEGER: Parameters In Python. 35310 (line 83) 35311* gdb.PARAM_ZINTEGER: Parameters In Python. 35312 (line 108) 35313* gdb.Parameter: Parameters In Python. 35314 (line 6) 35315* gdb.parameter: Basic Python. (line 35) 35316* gdb.parse_and_eval: Basic Python. (line 57) 35317* gdb.post_event: Basic Python. (line 68) 35318* gdb.Progspace: Progspaces In Python. 35319 (line 6) 35320* gdb.progspaces: Progspaces In Python. 35321 (line 18) 35322* gdb.PYTHONDIR: Basic Python. (line 11) 35323* gdb.read_memory: Inferiors In Python. (line 37) 35324* gdb.search_memory: Inferiors In Python. (line 50) 35325* gdb.selected_frame: Frames In Python. (line 21) 35326* gdb.selected_thread: Threads In Python. (line 13) 35327* gdb.solib_name: Basic Python. (line 122) 35328* gdb.string_to_argv: Commands In Python. (line 62) 35329* gdb.Symbol: Symbols In Python. (line 6) 35330* gdb.SYMBOL_FUNCTIONS_DOMAIN: Symbols In Python. (line 83) 35331* gdb.SYMBOL_LABEL_DOMAIN: Symbols In Python. (line 76) 35332* gdb.SYMBOL_LOC_ARG: Symbols In Python. (line 105) 35333* gdb.SYMBOL_LOC_BLOCK: Symbols In Python. (line 126) 35334* gdb.SYMBOL_LOC_COMPUTED: Symbols In Python. (line 140) 35335* gdb.SYMBOL_LOC_CONST: Symbols In Python. (line 96) 35336* gdb.SYMBOL_LOC_CONST_BYTES: Symbols In Python. (line 129) 35337* gdb.SYMBOL_LOC_LOCAL: Symbols In Python. (line 119) 35338* gdb.SYMBOL_LOC_OPTIMIZED_OUT: Symbols In Python. (line 137) 35339* gdb.SYMBOL_LOC_REF_ARG: Symbols In Python. (line 109) 35340* gdb.SYMBOL_LOC_REGISTER: Symbols In Python. (line 102) 35341* gdb.SYMBOL_LOC_REGPARM_ADDR: Symbols In Python. (line 114) 35342* gdb.SYMBOL_LOC_STATIC: Symbols In Python. (line 99) 35343* gdb.SYMBOL_LOC_TYPEDEF: Symbols In Python. (line 122) 35344* gdb.SYMBOL_LOC_UNDEF: Symbols In Python. (line 94) 35345* gdb.SYMBOL_LOC_UNRESOLVED: Symbols In Python. (line 132) 35346* gdb.SYMBOL_STRUCT_DOMAIN: Symbols In Python. (line 73) 35347* gdb.SYMBOL_TYPES_DOMAIN: Symbols In Python. (line 86) 35348* gdb.SYMBOL_UNDEF_DOMAIN: Symbols In Python. (line 66) 35349* gdb.SYMBOL_VAR_DOMAIN: Symbols In Python. (line 69) 35350* gdb.SYMBOL_VARIABLES_DOMAIN: Symbols In Python. (line 79) 35351* gdb.Symtab: Symbol Tables In Python. 35352 (line 6) 35353* gdb.Symtab_and_line: Symbol Tables In Python. 35354 (line 6) 35355* gdb.target_charset: Basic Python. (line 111) 35356* gdb.target_wide_charset: Basic Python. (line 116) 35357* gdb.Type: Types In Python. (line 6) 35358* gdb.TYPE_CODE_ARRAY: Types In Python. (line 155) 35359* gdb.TYPE_CODE_BITSTRING: Types In Python. (line 193) 35360* gdb.TYPE_CODE_BOOL: Types In Python. (line 214) 35361* gdb.TYPE_CODE_CHAR: Types In Python. (line 211) 35362* gdb.TYPE_CODE_COMPLEX: Types In Python. (line 217) 35363* gdb.TYPE_CODE_DECFLOAT: Types In Python. (line 226) 35364* gdb.TYPE_CODE_ENUM: Types In Python. (line 164) 35365* gdb.TYPE_CODE_ERROR: Types In Python. (line 196) 35366* gdb.TYPE_CODE_FLAGS: Types In Python. (line 167) 35367* gdb.TYPE_CODE_FLT: Types In Python. (line 176) 35368* gdb.TYPE_CODE_FUNC: Types In Python. (line 170) 35369* gdb.TYPE_CODE_INT: Types In Python. (line 173) 35370* gdb.TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 229) 35371* gdb.TYPE_CODE_MEMBERPTR: Types In Python. (line 205) 35372* gdb.TYPE_CODE_METHOD: Types In Python. (line 199) 35373* gdb.TYPE_CODE_METHODPTR: Types In Python. (line 202) 35374* gdb.TYPE_CODE_NAMESPACE: Types In Python. (line 223) 35375* gdb.TYPE_CODE_PTR: Types In Python. (line 152) 35376* gdb.TYPE_CODE_RANGE: Types In Python. (line 185) 35377* gdb.TYPE_CODE_REF: Types In Python. (line 208) 35378* gdb.TYPE_CODE_SET: Types In Python. (line 182) 35379* gdb.TYPE_CODE_STRING: Types In Python. (line 188) 35380* gdb.TYPE_CODE_STRUCT: Types In Python. (line 158) 35381* gdb.TYPE_CODE_TYPEDEF: Types In Python. (line 220) 35382* gdb.TYPE_CODE_UNION: Types In Python. (line 161) 35383* gdb.TYPE_CODE_VOID: Types In Python. (line 179) 35384* gdb.Value: Values From Inferior. 35385 (line 6) 35386* gdb.WP_ACCESS: Breakpoints In Python. 35387 (line 29) 35388* gdb.WP_READ: Breakpoints In Python. 35389 (line 23) 35390* gdb.WP_WRITE: Breakpoints In Python. 35391 (line 26) 35392* gdb.write: Basic Python. (line 102) 35393* gdb.write_memory: Inferiors In Python. (line 43) 35394* GDB/MI development: GDB/MI Development and Front Ends. 35395 (line 6) 35396* GDB/MI General Design: GDB/MI General Design. 35397 (line 6) 35398* GDB/MI, async records: GDB/MI Async Records. 35399 (line 6) 35400* GDB/MI, breakpoint commands: GDB/MI Breakpoint Commands. 35401 (line 6) 35402* GDB/MI, compatibility with CLI: GDB/MI Compatibility with CLI. 35403 (line 6) 35404* GDB/MI, data manipulation: GDB/MI Data Manipulation. 35405 (line 6) 35406* GDB/MI, input syntax: GDB/MI Input Syntax. (line 6) 35407* GDB/MI, its purpose: GDB/MI. (line 9) 35408* GDB/MI, output syntax: GDB/MI Output Syntax. 35409 (line 6) 35410* GDB/MI, result records: GDB/MI Result Records. 35411 (line 6) 35412* GDB/MI, simple examples: GDB/MI Simple Examples. 35413 (line 6) 35414* GDB/MI, stream records: GDB/MI Stream Records. 35415 (line 6) 35416* gdbarch debugging info: Debugging Output. (line 18) 35417* GDBHISTFILE, environment variable: Command History. (line 26) 35418* gdbserver: Server. (line 6) 35419* gdbserver, multiple processes: Server. (line 91) 35420* gdbserver, search path for libthread_db: Server. (line 188) 35421* GDT: DJGPP Native. (line 24) 35422* generate-core-file: Core File Generation. 35423 (line 18) 35424* get thread information block address: General Query Packets. 35425 (line 143) 35426* get thread-local storage address, remote request: General Query Packets. 35427 (line 119) 35428* getDebugChar: Bootstrapping. (line 14) 35429* gettimeofday, file-i/o system call: gettimeofday. (line 6) 35430* global debugging information directory: Separate Debug Files. 35431 (line 6) 35432* GNU C++: C. (line 10) 35433* GNU Emacs: Emacs. (line 6) 35434* GNU Hurd debugging: Hurd Native. (line 6) 35435* GNU/Hurd debug messages: Debugging Output. (line 72) 35436* GNU/Linux LWP async debug messages: Debugging Output. (line 94) 35437* GNU/Linux LWP debug messages: Debugging Output. (line 87) 35438* gnu_debuglink_crc32: Separate Debug Files. 35439 (line 164) 35440* h (help): Help. (line 9) 35441* H packet: Packets. (line 169) 35442* handle: Signals. (line 45) 35443* handle_exception: Stub Contents. (line 15) 35444* handling signals: Signals. (line 27) 35445* hardware breakpoints: Set Breaks. (line 62) 35446* hardware debug registers: Maintenance Commands. 35447 (line 307) 35448* hardware watchpoints: Set Watchpoints. (line 31) 35449* hash mark while downloading: Target Commands. (line 99) 35450* hbreak: Set Breaks. (line 62) 35451* help: Help. (line 6) 35452* help function: Convenience Vars. (line 112) 35453* help target: Target Commands. (line 19) 35454* help user-defined: Define. (line 66) 35455* heuristic-fence-post (Alpha, MIPS): MIPS. (line 14) 35456* history: Basic Python. (line 46) 35457* history events: Event Designators. (line 7) 35458* history expansion: History Interaction. (line 6) 35459* history expansion, turn on/off: Command History. (line 53) 35460* history file: Command History. (line 26) 35461* history number: Value History. (line 13) 35462* history of values printed by GDB: Value History. (line 6) 35463* history size: Command History. (line 45) 35464* history substitution: Command History. (line 26) 35465* history-preserve-point: Readline Init File Syntax. 35466 (line 93) 35467* history-search-backward (): Commands For History. 35468 (line 50) 35469* history-search-forward (): Commands For History. 35470 (line 45) 35471* HISTSIZE, environment variable: Command History. (line 45) 35472* hit_count: Breakpoints In Python. 35473 (line 96) 35474* hook: Hooks. (line 6) 35475* hookpost: Hooks. (line 11) 35476* hooks, for commands: Hooks. (line 6) 35477* hooks, post-command: Hooks. (line 11) 35478* hooks, pre-command: Hooks. (line 6) 35479* horizontal-scroll-mode: Readline Init File Syntax. 35480 (line 98) 35481* host character set: Character Sets. (line 6) 35482* Host I/O, remote protocol: Host I/O Packets. (line 6) 35483* how many arguments (user-defined commands): Define. (line 25) 35484* HPPA support: HPPA. (line 6) 35485* htrace: OpenRISC 1000. (line 69) 35486* hwatch: OpenRISC 1000. (line 59) 35487* i (info): Help. (line 99) 35488* I packet: Packets. (line 185) 35489* i packet: Packets. (line 180) 35490* i/o: Input/Output. (line 6) 35491* I/O registers (Atmel AVR): AVR. (line 10) 35492* i386: Remote Stub. (line 57) 35493* i386-stub.c: Remote Stub. (line 57) 35494* IDT: DJGPP Native. (line 24) 35495* if: Command Files. (line 75) 35496* ignore: Conditions. (line 77) 35497* ignore count (of breakpoint): Conditions. (line 66) 35498* ignore_count: Breakpoints In Python. 35499 (line 64) 35500* INCLUDE_RDB: VxWorks. (line 33) 35501* incomplete type: Symbols. (line 107) 35502* indentation in structure display: Print Settings. (line 198) 35503* index files: Index Files. (line 6) 35504* inferior: Inferiors and Programs. 35505 (line 13) 35506* inferior debugging info: Debugging Output. (line 78) 35507* inferior functions, calling: Calling. (line 6) 35508* inferior INFNO: Inferiors and Programs. 35509 (line 49) 35510* inferior tty: Input/Output. (line 44) 35511* inferiors: Inferiors In Python. (line 15) 35512* inferiors in python: Inferiors In Python. (line 6) 35513* infinite recursion in user-defined commands: Define. (line 76) 35514* info: Help. (line 99) 35515* info address: Symbols. (line 44) 35516* info all-registers: Registers. (line 15) 35517* info args: Frame Info. (line 51) 35518* info auxv: OS Information. (line 33) 35519* info breakpoints: Set Breaks. (line 128) 35520* info catch: Frame Info. (line 60) 35521* info checkpoints: Checkpoint/Restart. (line 31) 35522* info classes: Symbols. (line 205) 35523* info common: Special Fortran Commands. 35524 (line 9) 35525* info copying: Help. (line 136) 35526* info dcache: Caching Remote Data. (line 34) 35527* info display: Auto Display. (line 66) 35528* info dll: Cygwin Native. (line 35) 35529* info dos: DJGPP Native. (line 15) 35530* info extensions: Show. (line 34) 35531* info f (info frame): Frame Info. (line 17) 35532* info files: Files. (line 191) 35533* info float: Floating Point Hardware. 35534 (line 9) 35535* info for known .debug_gdb_scripts-loaded scripts: Maintenance Commands. 35536 (line 216) 35537* info for known object files: Maintenance Commands. 35538 (line 211) 35539* info frame: Frame Info. (line 17) 35540* info frame, show the source language: Show. (line 15) 35541* info functions: Symbols. (line 184) 35542* info handle: Signals. (line 33) 35543* info inferiors: Inferiors and Programs. 35544 (line 25) 35545* info io_registers, AVR: AVR. (line 10) 35546* info line: Machine Code. (line 14) 35547* info line, and Objective-C: Method Names in Commands. 35548 (line 9) 35549* info locals: Frame Info. (line 55) 35550* info macro: Macros. (line 47) 35551* info mem: Memory Region Attributes. 35552 (line 45) 35553* info meminfo: SVR4 Process Information. 35554 (line 78) 35555* info or1k spr: OpenRISC 1000. (line 20) 35556* info os: OS Information. (line 47) 35557* info os processes: OS Information. (line 52) 35558* info pidlist: SVR4 Process Information. 35559 (line 74) 35560* info proc: SVR4 Process Information. 35561 (line 16) 35562* info program: Stopping. (line 18) 35563* info record: Process Record and Replay. 35564 (line 137) 35565* info registers: Registers. (line 11) 35566* info scope: Symbols. (line 138) 35567* info selectors: Symbols. (line 211) 35568* info serial: DJGPP Native. (line 142) 35569* info set: Help. (line 119) 35570* info share: Files. (line 326) 35571* info sharedlibrary: Files. (line 326) 35572* info signals: Signals. (line 33) 35573* info source: Symbols. (line 159) 35574* info source, show the source language: Show. (line 21) 35575* info sources: Symbols. (line 178) 35576* info spu: SPU. (line 10) 35577* info stack: Backtrace. (line 34) 35578* info static-tracepoint-markers: Listing Static Tracepoint Markers. 35579 (line 6) 35580* info symbol: Symbols. (line 54) 35581* info target: Files. (line 191) 35582* info task TASKNO: Ada Tasks. (line 89) 35583* info tasks: Ada Tasks. (line 9) 35584* info terminal: Input/Output. (line 12) 35585* info threads: Threads. (line 66) 35586* info threads (HP-UX): Threads. (line 103) 35587* info tp: Listing Tracepoints. (line 6) 35588* info tracepoints: Listing Tracepoints. (line 6) 35589* info tvariables: Trace State Variables. 35590 (line 37) 35591* info types: Symbols. (line 124) 35592* info udot: OS Information. (line 16) 35593* info variables: Symbols. (line 196) 35594* info vector: Vector Unit. (line 9) 35595* info w32: Cygwin Native. (line 19) 35596* info warranty: Help. (line 140) 35597* info watchpoints [N]: Set Watchpoints. (line 72) 35598* info win: TUI Commands. (line 18) 35599* information about static tracepoint markers: Listing Static Tracepoint Markers. 35600 (line 6) 35601* information about tracepoints: Listing Tracepoints. (line 6) 35602* inheritance: Debugging C Plus Plus. 35603 (line 25) 35604* init file: Startup. (line 11) 35605* init file name: Startup. (line 45) 35606* init-if-undefined: Convenience Vars. (line 41) 35607* initial frame: Frames. (line 12) 35608* initialization file, readline: Readline Init File. (line 6) 35609* inline functions, debugging: Inline Functions. (line 6) 35610* innermost frame: Frames. (line 12) 35611* input syntax for GDB/MI: GDB/MI Input Syntax. (line 6) 35612* input-meta: Readline Init File Syntax. 35613 (line 105) 35614* insert-comment (M-#): Miscellaneous Commands. 35615 (line 51) 35616* insert-completions (M-*): Commands For Completion. 35617 (line 14) 35618* inspect: Data. (line 6) 35619* installation: Installing GDB. (line 6) 35620* instructions, assembly: Machine Code. (line 36) 35621* integral datatypes, in file-i/o protocol: Integral Datatypes. 35622 (line 6) 35623* Intel: Remote Stub. (line 57) 35624* Intel disassembly flavor: Machine Code. (line 127) 35625* interaction, readline: Readline Interaction. 35626 (line 6) 35627* internal commands: Maintenance Commands. 35628 (line 6) 35629* internal errors, control of GDB behavior: Maintenance Commands. 35630 (line 124) 35631* internal GDB breakpoints: Set Breaks. (line 332) 35632* interpreter-exec: Interpreters. (line 43) 35633* interrupt <1>: Background Execution. 35634 (line 73) 35635* interrupt: Quitting GDB. (line 13) 35636* interrupt debuggee on MS-Windows: Cygwin Native. (line 9) 35637* interrupt remote programs: Remote Configuration. 35638 (line 29) 35639* interrupting remote programs: Connecting. (line 78) 35640* interrupting remote targets: Bootstrapping. (line 25) 35641* interrupts (remote protocol): Interrupts. (line 6) 35642* invalid input: Bug Criteria. (line 16) 35643* invoke another interpreter: Interpreters. (line 37) 35644* invoke on Command: Commands In Python. (line 50) 35645* invoke on Function: Functions In Python. (line 21) 35646* is_argument: Symbols In Python. (line 52) 35647* is_constant: Symbols In Python. (line 55) 35648* is_exited on InferiorThread: Threads In Python. (line 43) 35649* is_function: Symbols In Python. (line 58) 35650* is_optimized_out: Values From Inferior. 35651 (line 50) 35652* is_running on InferiorThread: Threads In Python. (line 40) 35653* is_stopped on InferiorThread: Threads In Python. (line 37) 35654* is_valid on Breakpoint: Breakpoints In Python. 35655 (line 33) 35656* is_valid on Frame: Frames In Python. (line 33) 35657* is_variable: Symbols In Python. (line 61) 35658* isatty, file-i/o system call: isatty. (line 6) 35659* isearch-terminators: Readline Init File Syntax. 35660 (line 112) 35661* JIT compilation interface: JIT Interface. (line 6) 35662* jump: Jumping. (line 10) 35663* jump, and Objective-C: Method Names in Commands. 35664 (line 9) 35665* just-in-time compilation: JIT Interface. (line 6) 35666* k packet: Packets. (line 189) 35667* kernel crash dump: BSD libkvm Interface. 35668 (line 6) 35669* kernel memory image: BSD libkvm Interface. 35670 (line 6) 35671* keymap: Readline Init File Syntax. 35672 (line 119) 35673* kill: Kill Process. (line 6) 35674* kill inferior INFNO: Inferiors and Programs. 35675 (line 103) 35676* kill ring: Readline Killing Commands. 35677 (line 19) 35678* kill-line (C-k): Commands For Killing. 35679 (line 6) 35680* kill-region (): Commands For Killing. 35681 (line 41) 35682* kill-whole-line (): Commands For Killing. 35683 (line 15) 35684* kill-word (M-d): Commands For Killing. 35685 (line 19) 35686* killing text: Readline Killing Commands. 35687 (line 6) 35688* kvm: BSD libkvm Interface. 35689 (line 24) 35690* l (list): List. (line 6) 35691* languages: Languages. (line 6) 35692* last tracepoint number: Create and Delete Tracepoints. 35693 (line 98) 35694* latest breakpoint: Set Breaks. (line 6) 35695* layout: TUI Commands. (line 21) 35696* lazy strings in python: Lazy Strings In Python. 35697 (line 6) 35698* lazy_string on Value: Values From Inferior. 35699 (line 134) 35700* LDT: DJGPP Native. (line 24) 35701* leaving GDB: Quitting GDB. (line 6) 35702* Left: TUI Keys. (line 59) 35703* length: Lazy Strings In Python. 35704 (line 31) 35705* libkvm: BSD libkvm Interface. 35706 (line 6) 35707* library list format, remote protocol: Library List Format. (line 6) 35708* limit hardware breakpoints and watchpoints: Remote Configuration. 35709 (line 72) 35710* limit on number of printed array elements: Print Settings. (line 123) 35711* limits, in file-i/o protocol: Limits. (line 6) 35712* line: Symbol Tables In Python. 35713 (line 25) 35714* linespec: Specify Location. (line 6) 35715* linkage_name: Symbols In Python. (line 37) 35716* Linux lightweight processes: Debugging Output. (line 87) 35717* list: List. (line 6) 35718* list active threads, remote request: General Query Packets. 35719 (line 91) 35720* list of supported file-i/o calls: List of Supported Calls. 35721 (line 6) 35722* list output in GDB/MI: GDB/MI Output Syntax. 35723 (line 117) 35724* list, and Objective-C: Method Names in Commands. 35725 (line 9) 35726* list, how many lines to display: List. (line 30) 35727* listing GDB's internal symbol tables: Symbols. (line 278) 35728* listing machine instructions: Machine Code. (line 36) 35729* listing mapped overlays: Overlay Commands. (line 60) 35730* load address, overlay's: How Overlays Work. (line 6) 35731* load FILENAME: Target Commands. (line 115) 35732* load shared library: Files. (line 323) 35733* load symbols from memory: Files. (line 162) 35734* local variables: Symbols. (line 138) 35735* locate address: Output Formats. (line 35) 35736* location: Breakpoints In Python. 35737 (line 101) 35738* lock scheduler: All-Stop Mode. (line 37) 35739* log output in GDB/MI: GDB/MI Output Syntax. 35740 (line 113) 35741* logging file name: Logging Output. (line 13) 35742* logging GDB output: Logging Output. (line 6) 35743* lookup_symbol: Symbols In Python. (line 14) 35744* lookup_type: Types In Python. (line 12) 35745* loop_break: Command Files. (line 94) 35746* loop_continue: Command Files. (line 98) 35747* lseek flags, in file-i/o protocol: Lseek Flags. (line 6) 35748* lseek, file-i/o system call: lseek. (line 6) 35749* M packet: Packets. (line 213) 35750* m packet: Packets. (line 196) 35751* M32-EVA target board address: M32R/D. (line 21) 35752* M32R/Chaos debugging: M32R/D. (line 50) 35753* m680x0: Remote Stub. (line 60) 35754* m68k-stub.c: Remote Stub. (line 60) 35755* machine instructions: Machine Code. (line 36) 35756* macro define: Macros. (line 52) 35757* macro definition, showing: Macros. (line 47) 35758* macro exp1: Macros. (line 36) 35759* macro expand: Macros. (line 29) 35760* macro expansion, showing the results of preprocessor: Macros. 35761 (line 29) 35762* macro list: Macros. (line 73) 35763* macro undef: Macros. (line 67) 35764* macros, example of debugging with: Macros. (line 76) 35765* macros, user-defined: Macros. (line 52) 35766* mailing lists: GDB/MI Development and Front Ends. 35767 (line 35) 35768* maint agent: Maintenance Commands. 35769 (line 12) 35770* maint agent-eval: Maintenance Commands. 35771 (line 12) 35772* maint check-symtabs: Maintenance Commands. 35773 (line 78) 35774* maint cplus first_component: Maintenance Commands. 35775 (line 81) 35776* maint cplus namespace: Maintenance Commands. 35777 (line 84) 35778* maint demangle: Maintenance Commands. 35779 (line 87) 35780* maint deprecate: Maintenance Commands. 35781 (line 90) 35782* maint dump-me: Maintenance Commands. 35783 (line 98) 35784* maint info breakpoints: Maintenance Commands. 35785 (line 25) 35786* maint info program-spaces: Inferiors and Programs. 35787 (line 137) 35788* maint info psymtabs: Symbols. (line 278) 35789* maint info sections: Files. (line 200) 35790* maint info sol-threads: Threads. (line 133) 35791* maint info symtabs: Symbols. (line 278) 35792* maint internal-error: Maintenance Commands. 35793 (line 103) 35794* maint internal-warning: Maintenance Commands. 35795 (line 103) 35796* maint packet: Maintenance Commands. 35797 (line 143) 35798* maint print architecture: Maintenance Commands. 35799 (line 149) 35800* maint print c-tdesc: Maintenance Commands. 35801 (line 153) 35802* maint print cooked-registers: Maintenance Commands. 35803 (line 176) 35804* maint print dummy-frames: Maintenance Commands. 35805 (line 158) 35806* maint print objfiles: Maintenance Commands. 35807 (line 211) 35808* maint print psymbols: Symbols. (line 259) 35809* maint print raw-registers: Maintenance Commands. 35810 (line 176) 35811* maint print reggroups: Maintenance Commands. 35812 (line 192) 35813* maint print register-groups: Maintenance Commands. 35814 (line 176) 35815* maint print registers: Maintenance Commands. 35816 (line 176) 35817* maint print section-scripts: Maintenance Commands. 35818 (line 216) 35819* maint print statistics: Maintenance Commands. 35820 (line 223) 35821* maint print symbols: Symbols. (line 259) 35822* maint print target-stack: Maintenance Commands. 35823 (line 236) 35824* maint print type: Maintenance Commands. 35825 (line 248) 35826* maint print unwind, HPPA: HPPA. (line 17) 35827* maint set dwarf2 always-disassemble: Maintenance Commands. 35828 (line 255) 35829* maint set dwarf2 max-cache-age: Maintenance Commands. 35830 (line 277) 35831* maint set internal-error: Maintenance Commands. 35832 (line 124) 35833* maint set internal-warning: Maintenance Commands. 35834 (line 124) 35835* maint set profile: Maintenance Commands. 35836 (line 291) 35837* maint set python auto-load: Auto-loading. (line 22) 35838* maint set python print-stack: Python Commands. (line 31) 35839* maint set show-all-tib: Maintenance Commands. 35840 (line 315) 35841* maint set show-debug-regs: Maintenance Commands. 35842 (line 307) 35843* maint show dwarf2 always-disassemble: Maintenance Commands. 35844 (line 255) 35845* maint show dwarf2 max-cache-age: Maintenance Commands. 35846 (line 277) 35847* maint show internal-error: Maintenance Commands. 35848 (line 124) 35849* maint show internal-warning: Maintenance Commands. 35850 (line 124) 35851* maint show profile: Maintenance Commands. 35852 (line 291) 35853* maint show python auto-load: Auto-loading. (line 25) 35854* maint show show-all-tib: Maintenance Commands. 35855 (line 315) 35856* maint show show-debug-regs: Maintenance Commands. 35857 (line 307) 35858* maint space: Maintenance Commands. 35859 (line 321) 35860* maint time: Maintenance Commands. 35861 (line 328) 35862* maint translate-address: Maintenance Commands. 35863 (line 339) 35864* maint undeprecate: Maintenance Commands. 35865 (line 90) 35866* maintenance commands: Maintenance Commands. 35867 (line 6) 35868* make: Shell Commands. (line 19) 35869* manual overlay debugging: Overlay Commands. (line 23) 35870* map an overlay: Overlay Commands. (line 30) 35871* mapinfo list, QNX Neutrino: SVR4 Process Information. 35872 (line 78) 35873* mapped address: How Overlays Work. (line 6) 35874* mapped overlays: How Overlays Work. (line 6) 35875* mark-modified-lines: Readline Init File Syntax. 35876 (line 132) 35877* mark-symlinked-directories: Readline Init File Syntax. 35878 (line 137) 35879* markers, static tracepoints: Set Tracepoints. (line 28) 35880* match-hidden-files: Readline Init File Syntax. 35881 (line 142) 35882* maximum value for offset of closest symbol: Print Settings. (line 70) 35883* may-insert-breakpoints: Observer Mode. (line 50) 35884* may-insert-fast-tracepoints: Observer Mode. (line 69) 35885* may-insert-tracepoints: Observer Mode. (line 59) 35886* may-interrupt: Observer Mode. (line 79) 35887* may-write-memory: Observer Mode. (line 41) 35888* may-write-registers: Observer Mode. (line 32) 35889* mem: Memory Region Attributes. 35890 (line 22) 35891* member functions: C Plus Plus Expressions. 35892 (line 18) 35893* memory address space mappings: SVR4 Process Information. 35894 (line 32) 35895* memory map format: Memory Map Format. (line 6) 35896* memory region attributes: Memory Region Attributes. 35897 (line 6) 35898* memory tracing: Breakpoints. (line 20) 35899* memory transfer, in file-i/o protocol: Memory Transfer. (line 6) 35900* memory used by commands: Maintenance Commands. 35901 (line 321) 35902* memory used for symbol tables: Files. (line 311) 35903* memory, alignment and size of remote accesses: Packets. (line 203) 35904* memory, viewing as typed object: Expressions. (line 43) 35905* memset: Bootstrapping. (line 70) 35906* menu-complete (): Commands For Completion. 35907 (line 18) 35908* meta-flag: Readline Init File Syntax. 35909 (line 105) 35910* mi interpreter: Interpreters. (line 26) 35911* mi1 interpreter: Interpreters. (line 34) 35912* mi2 interpreter: Interpreters. (line 31) 35913* minimal language: Unsupported Languages. 35914 (line 6) 35915* Minimal symbols and DLLs: Non-debug DLL Symbols. 35916 (line 6) 35917* MIPS addresses, masking: MIPS. (line 86) 35918* MIPS boards: MIPS Embedded. (line 6) 35919* MIPS code compression: MIPS. (line 55) 35920* MIPS remote floating point: MIPS Embedded. (line 60) 35921* MIPS stack: MIPS. (line 6) 35922* miscellaneous settings: Other Misc Settings. (line 6) 35923* MMX registers (x86): Registers. (line 71) 35924* mode_t values, in file-i/o protocol: mode_t Values. (line 6) 35925* Modula-2: Summary. (line 29) 35926* Modula-2 built-ins: Built-In Func/Proc. (line 6) 35927* Modula-2 checks: M2 Checks. (line 6) 35928* Modula-2 constants: Built-In Func/Proc. (line 112) 35929* Modula-2 defaults: M2 Defaults. (line 6) 35930* Modula-2 operators: M2 Operators. (line 6) 35931* Modula-2 types: M2 Types. (line 6) 35932* Modula-2, deviations from: Deviations. (line 6) 35933* Modula-2, GDB support: Modula-2. (line 6) 35934* monitor: Connecting. (line 105) 35935* monitor commands, for gdbserver: Server. (line 171) 35936* Motorola 680x0: Remote Stub. (line 60) 35937* MS Windows debugging: Cygwin Native. (line 6) 35938* MS-DOS system info: DJGPP Native. (line 19) 35939* MS-DOS-specific commands: DJGPP Native. (line 6) 35940* multiple locations, breakpoints: Set Breaks. (line 189) 35941* multiple processes: Forks. (line 6) 35942* multiple processes with gdbserver: Server. (line 91) 35943* multiple targets: Active Targets. (line 6) 35944* multiple threads: Threads. (line 6) 35945* multiple threads, backtrace: Backtrace. (line 37) 35946* multiple-symbols menu: Ambiguous Expressions. 35947 (line 51) 35948* multiprocess extensions, in remote protocol: General Query Packets. 35949 (line 506) 35950* n (next): Continuing and Stepping. 35951 (line 78) 35952* n (SingleKey TUI key): TUI Single Key Mode. (line 19) 35953* name: Symbols In Python. (line 33) 35954* name on Frame: Frames In Python. (line 40) 35955* names of symbols: Symbols. (line 14) 35956* namespace in C++: C Plus Plus Expressions. 35957 (line 22) 35958* native Cygwin debugging: Cygwin Native. (line 6) 35959* native DJGPP debugging: DJGPP Native. (line 6) 35960* negative breakpoint numbers: Set Breaks. (line 332) 35961* NetROM ROM emulator target: Target Commands. (line 88) 35962* New SYSTAG message: Threads. (line 51) 35963* New SYSTAG message, on HP-UX: Threads. (line 93) 35964* newer on Frame: Frames In Python. (line 68) 35965* next: Continuing and Stepping. 35966 (line 78) 35967* next&: Background Execution. 35968 (line 47) 35969* next-history (C-n): Commands For History. 35970 (line 16) 35971* nexti: Continuing and Stepping. 35972 (line 203) 35973* nexti&: Background Execution. 35974 (line 50) 35975* ni (nexti): Continuing and Stepping. 35976 (line 203) 35977* non-incremental-forward-search-history (M-n): Commands For History. 35978 (line 40) 35979* non-incremental-reverse-search-history (M-p): Commands For History. 35980 (line 35) 35981* non-member C++ functions, set breakpoint in: Set Breaks. (line 108) 35982* non-stop mode: Non-Stop Mode. (line 6) 35983* non-stop mode, and breakpoint always-inserted: Set Breaks. (line 325) 35984* non-stop mode, and process record and replay: Process Record and Replay. 35985 (line 52) 35986* non-stop mode, and set displaced-stepping: Maintenance Commands. 35987 (line 73) 35988* non-stop mode, remote request: General Query Packets. 35989 (line 220) 35990* noninvasive task options: Hurd Native. (line 73) 35991* nosharedlibrary: Files. (line 341) 35992* notation, readline: Readline Bare Essentials. 35993 (line 6) 35994* notational conventions, for GDB/MI: GDB/MI. (line 25) 35995* notification packets: Notification Packets. 35996 (line 6) 35997* notify output in GDB/MI: GDB/MI Output Syntax. 35998 (line 102) 35999* NULL elements in arrays: Print Settings. (line 189) 36000* num <1>: Threads In Python. (line 20) 36001* num: Inferiors In Python. (line 20) 36002* number: Breakpoints In Python. 36003 (line 68) 36004* number of array elements to print: Print Settings. (line 123) 36005* number representation: Numbers. (line 6) 36006* numbers for breakpoints: Breakpoints. (line 41) 36007* object files, relocatable, reading symbols from: Files. (line 132) 36008* Objective-C: Objective-C. (line 6) 36009* Objective-C, classes and selectors: Symbols. (line 205) 36010* Objective-C, print objects: The Print Command with Objective-C. 36011 (line 6) 36012* objfile: Symbol Tables In Python. 36013 (line 35) 36014* Objfile: Objfiles In Python. (line 6) 36015* OBJFILE-gdb.py: objfile-gdb.py file. (line 6) 36016* objfiles: Objfiles In Python. (line 22) 36017* objfiles in python: Objfiles In Python. (line 6) 36018* observer: Observer Mode. (line 22) 36019* observer debugging info: Debugging Output. (line 101) 36020* octal escapes in strings: Print Settings. (line 222) 36021* older on Frame: Frames In Python. (line 65) 36022* online documentation: Help. (line 6) 36023* opaque data types: Symbols. (line 241) 36024* open flags, in file-i/o protocol: Open Flags. (line 6) 36025* open, file-i/o system call: open. (line 6) 36026* OpenRISC 1000: OpenRISC 1000. (line 6) 36027* OpenRISC 1000 htrace: OpenRISC 1000. (line 58) 36028* operating system information: Operating System Information. 36029 (line 6) 36030* operating system information, process list: Process list. (line 6) 36031* optimized code, debugging: Optimized Code. (line 6) 36032* optimized code, wrong values of variables: Variables. (line 58) 36033* optimized out value in Python: Values From Inferior. 36034 (line 49) 36035* optional debugging messages: Debugging Output. (line 6) 36036* optional warnings: Messages/Warnings. (line 6) 36037* or1k boards: OpenRISC 1000. (line 6) 36038* or1ksim: OpenRISC 1000. (line 16) 36039* OS ABI: ABI. (line 11) 36040* OS information: OS Information. (line 6) 36041* out-of-line single-stepping: Maintenance Commands. 36042 (line 56) 36043* outermost frame: Frames. (line 12) 36044* output: Output. (line 35) 36045* output formats: Output Formats. (line 6) 36046* output syntax of GDB/MI: GDB/MI Output Syntax. 36047 (line 6) 36048* output-meta: Readline Init File Syntax. 36049 (line 149) 36050* overlay: Overlay Commands. (line 17) 36051* overlay area: How Overlays Work. (line 6) 36052* overlay example program: Overlay Sample Program. 36053 (line 6) 36054* overlays: Overlays. (line 6) 36055* overlays, setting breakpoints in: Overlay Commands. (line 93) 36056* overload-choice annotation: Prompting. (line 32) 36057* overloaded functions, calling: C Plus Plus Expressions. 36058 (line 27) 36059* overloaded functions, overload resolution: Debugging C Plus Plus. 36060 (line 48) 36061* overloading in C++: Debugging C Plus Plus. 36062 (line 15) 36063* overwrite-mode (): Commands For Text. (line 53) 36064* P packet: Packets. (line 232) 36065* p packet: Packets. (line 223) 36066* packet acknowledgment, for GDB remote: Packet Acknowledgment. 36067 (line 6) 36068* packet size, remote protocol: General Query Packets. 36069 (line 441) 36070* packets, notification: Notification Packets. 36071 (line 6) 36072* packets, reporting on stdout: Debugging Output. (line 123) 36073* packets, tracepoint: Tracepoint Packets. (line 6) 36074* page tables display (MS-DOS): DJGPP Native. (line 56) 36075* page-completions: Readline Init File Syntax. 36076 (line 154) 36077* PARAM_AUTO_BOOLEAN: Parameters In Python. 36078 (line 78) 36079* PARAM_BOOLEAN: Parameters In Python. 36080 (line 74) 36081* PARAM_ENUM: Parameters In Python. 36082 (line 112) 36083* PARAM_FILENAME: Parameters In Python. 36084 (line 104) 36085* PARAM_INTEGER: Parameters In Python. 36086 (line 87) 36087* PARAM_OPTIONAL_FILENAME: Parameters In Python. 36088 (line 101) 36089* PARAM_STRING: Parameters In Python. 36090 (line 91) 36091* PARAM_STRING_NOESCAPE: Parameters In Python. 36092 (line 97) 36093* PARAM_UINTEGER: Parameters In Python. 36094 (line 83) 36095* PARAM_ZINTEGER: Parameters In Python. 36096 (line 108) 36097* Parameter: Parameters In Python. 36098 (line 6) 36099* parameter: Basic Python. (line 36) 36100* parameters in python: Parameters In Python. 36101 (line 6) 36102* parse_and_eval: Basic Python. (line 58) 36103* partial symbol dump: Symbols. (line 259) 36104* partial symbol tables, listing GDB's internal: Symbols. (line 278) 36105* Pascal: Summary. (line 32) 36106* Pascal objects, static members display: Print Settings. (line 353) 36107* Pascal support in GDB, limitations: Pascal. (line 6) 36108* pass signals to inferior, remote request: General Query Packets. 36109 (line 240) 36110* passcount: Tracepoint Passcounts. 36111 (line 6) 36112* patching binaries: Patching. (line 6) 36113* patching object files: Files. (line 26) 36114* path: Environment. (line 14) 36115* pause current task (GNU Hurd): Hurd Native. (line 49) 36116* pause current thread (GNU Hurd): Hurd Native. (line 91) 36117* pauses in output: Screen Size. (line 6) 36118* pc: Symbol Tables In Python. 36119 (line 21) 36120* pc on Frame: Frames In Python. (line 55) 36121* pending breakpoints: Set Breaks. (line 231) 36122* PgDn: TUI Keys. (line 50) 36123* PgUp: TUI Keys. (line 47) 36124* physical address from linear address: DJGPP Native. (line 81) 36125* pid: Inferiors In Python. (line 23) 36126* pipe, target remote to: Connecting. (line 60) 36127* pipes: Starting. (line 62) 36128* pmon, MIPS remote: MIPS Embedded. (line 132) 36129* po (print-object): The Print Command with Objective-C. 36130 (line 6) 36131* pointer on Type: Types In Python. (line 114) 36132* pointer values, in file-i/o protocol: Pointer Values. (line 6) 36133* pointer, finding referent: Print Settings. (line 79) 36134* port rights, GNU Hurd: Hurd Native. (line 85) 36135* port sets, GNU Hurd: Hurd Native. (line 85) 36136* possible-completions (M-?): Commands For Completion. 36137 (line 11) 36138* post-commands annotation: Prompting. (line 27) 36139* post-overload-choice annotation: Prompting. (line 32) 36140* post-prompt annotation: Prompting. (line 24) 36141* post-prompt-for-continue annotation: Prompting. (line 40) 36142* post-query annotation: Prompting. (line 36) 36143* post_event: Basic Python. (line 69) 36144* PowerPC architecture: PowerPC. (line 6) 36145* pre-commands annotation: Prompting. (line 27) 36146* pre-overload-choice annotation: Prompting. (line 32) 36147* pre-prompt annotation: Prompting. (line 24) 36148* pre-prompt-for-continue annotation: Prompting. (line 40) 36149* pre-query annotation: Prompting. (line 36) 36150* prefix for data files: Data Files. (line 6) 36151* prefix for shared library file names: Files. (line 374) 36152* prefix-meta (<ESC>): Miscellaneous Commands. 36153 (line 18) 36154* premature return from system calls: Interrupted System Calls. 36155 (line 6) 36156* preprocessor macro expansion, showing the results of: Macros. 36157 (line 29) 36158* pretty print arrays: Print Settings. (line 98) 36159* pretty print C++ virtual function tables: Print Settings. (line 364) 36160* pretty_printers <1>: Objfiles In Python. (line 32) 36161* pretty_printers: Progspaces In Python. 36162 (line 28) 36163* previous-history (C-p): Commands For History. 36164 (line 12) 36165* print: Data. (line 6) 36166* print all frame argument values: Print Settings. (line 135) 36167* print an Objective-C object description: The Print Command with Objective-C. 36168 (line 11) 36169* print array indexes: Print Settings. (line 108) 36170* print frame argument values for scalars only: Print Settings. 36171 (line 135) 36172* print messages on inferior start and exit: Inferiors and Programs. 36173 (line 116) 36174* print messages on thread start and exit: Threads. (line 165) 36175* print settings: Print Settings. (line 6) 36176* print structures in indented form: Print Settings. (line 198) 36177* print-object: The Print Command with Objective-C. 36178 (line 6) 36179* print/don't print memory addresses: Print Settings. (line 13) 36180* print_name: Symbols In Python. (line 41) 36181* printf: Output. (line 46) 36182* printing byte arrays: Output Formats. (line 60) 36183* printing data: Data. (line 6) 36184* printing frame argument values: Print Settings. (line 135) 36185* printing strings: Output Formats. (line 60) 36186* probe static tracepoint marker: Create and Delete Tracepoints. 36187 (line 51) 36188* probing markers, static tracepoints: Set Tracepoints. (line 28) 36189* proc-trace-entry: SVR4 Process Information. 36190 (line 70) 36191* proc-trace-exit: SVR4 Process Information. 36192 (line 70) 36193* proc-untrace-entry: SVR4 Process Information. 36194 (line 70) 36195* proc-untrace-exit: SVR4 Process Information. 36196 (line 70) 36197* process detailed status information: SVR4 Process Information. 36198 (line 40) 36199* process ID: SVR4 Process Information. 36200 (line 16) 36201* process info via /proc: SVR4 Process Information. 36202 (line 6) 36203* process list, QNX Neutrino: SVR4 Process Information. 36204 (line 74) 36205* process record and replay: Process Record and Replay. 36206 (line 6) 36207* process status register: Registers. (line 26) 36208* processes, multiple: Forks. (line 6) 36209* procfs API calls: SVR4 Process Information. 36210 (line 53) 36211* profiling GDB: Maintenance Commands. 36212 (line 291) 36213* program counter register: Registers. (line 26) 36214* program entry point: Backtrace. (line 93) 36215* programming in python: Python API. (line 6) 36216* Progspace: Progspaces In Python. 36217 (line 6) 36218* progspaces: Progspaces In Python. 36219 (line 19) 36220* progspaces in python: Progspaces In Python. 36221 (line 6) 36222* prompt: Prompt. (line 6) 36223* prompt annotation: Prompting. (line 24) 36224* prompt-for-continue annotation: Prompting. (line 40) 36225* protocol basics, file-i/o: Protocol Basics. (line 6) 36226* protocol, GDB remote serial: Overview. (line 14) 36227* protocol-specific representation of datatypes, in file-i/o protocol: Protocol-specific Representation of Datatypes. 36228 (line 6) 36229* ptid: Threads In Python. (line 23) 36230* ptrace system call: OS Information. (line 9) 36231* ptype: Symbols. (line 85) 36232* putDebugChar: Bootstrapping. (line 20) 36233* pwd: Working Directory. (line 19) 36234* python: Python Commands. (line 9) 36235* python api: Python API. (line 6) 36236* python commands <1>: Commands In Python. (line 6) 36237* python commands: Python Commands. (line 6) 36238* python convenience functions: Functions In Python. (line 6) 36239* python directory: Python. (line 10) 36240* python exceptions: Exception Handling. (line 6) 36241* python functions: Basic Python. (line 6) 36242* python module: Basic Python. (line 6) 36243* python pagination: Python API. (line 6) 36244* python parameters: Parameters In Python. 36245 (line 6) 36246* python scripting: Python. (line 6) 36247* python stdout: Python API. (line 6) 36248* Python, working with types: Types In Python. (line 6) 36249* python, working with values from inferior: Values From Inferior. 36250 (line 6) 36251* PYTHONDIR: Basic Python. (line 12) 36252* q (quit): Quitting GDB. (line 6) 36253* q (SingleKey TUI key): TUI Single Key Mode. (line 22) 36254* Q packet: Packets. (line 242) 36255* q packet: Packets. (line 242) 36256* QAllow packet: General Query Packets. 36257 (line 51) 36258* qAttached packet: General Query Packets. 36259 (line 810) 36260* qAuth packet: General Query Packets. 36261 (line 41) 36262* qC packet: General Query Packets. 36263 (line 62) 36264* qCRC packet: General Query Packets. 36265 (line 73) 36266* qfThreadInfo packet: General Query Packets. 36267 (line 91) 36268* qGetTIBAddr packet: General Query Packets. 36269 (line 143) 36270* qGetTLSAddr packet: General Query Packets. 36271 (line 119) 36272* QNonStop packet: General Query Packets. 36273 (line 220) 36274* QNX Neutrino: Neutrino. (line 6) 36275* qOffsets packet: General Query Packets. 36276 (line 182) 36277* qP packet: General Query Packets. 36278 (line 209) 36279* QPassSignals packet: General Query Packets. 36280 (line 240) 36281* qRcmd packet: General Query Packets. 36282 (line 261) 36283* qSearch:memory packet: General Query Packets. 36284 (line 280) 36285* QStartNoAckMode packet: General Query Packets. 36286 (line 300) 36287* qsThreadInfo packet: General Query Packets. 36288 (line 91) 36289* qSupported packet: General Query Packets. 36290 (line 315) 36291* qSymbol packet: General Query Packets. 36292 (line 551) 36293* QTDPsrc packet: Tracepoint Packets. (line 90) 36294* QTDV packet: Tracepoint Packets. (line 121) 36295* qThreadExtraInfo packet: General Query Packets. 36296 (line 596) 36297* qTV packet: Tracepoint Packets. (line 270) 36298* query annotation: Prompting. (line 36) 36299* query attached, remote request: General Query Packets. 36300 (line 810) 36301* quit [EXPRESSION]: Quitting GDB. (line 6) 36302* quit annotation: Errors. (line 6) 36303* quoted-insert (C-q or C-v): Commands For Text. (line 20) 36304* quotes in commands: Completion. (line 57) 36305* quoting Ada internal identifiers: Additions to Ada. (line 76) 36306* quoting names: Symbols. (line 14) 36307* qXfer packet: General Query Packets. 36308 (line 632) 36309* r (run): Starting. (line 6) 36310* r (SingleKey TUI key): TUI Single Key Mode. (line 25) 36311* R packet: Packets. (line 251) 36312* r packet: Packets. (line 246) 36313* raise exceptions: Set Catchpoints. (line 197) 36314* range checking: Type Checking. (line 65) 36315* range on Type: Types In Python. (line 104) 36316* ranges of breakpoints: Breakpoints. (line 48) 36317* raw printing: Output Formats. (line 70) 36318* rbreak: Set Breaks. (line 92) 36319* rc (reverse-continue): Reverse Execution. (line 30) 36320* RDI heartbeat: ARM. (line 112) 36321* rdilogenable: ARM. (line 95) 36322* rdilogfile: ARM. (line 89) 36323* re-read-init-file (C-x C-r): Miscellaneous Commands. 36324 (line 6) 36325* read special object, remote request: General Query Packets. 36326 (line 632) 36327* read, file-i/o system call: read. (line 6) 36328* read-only sections: Files. (line 258) 36329* read_memory on Inferior: Inferiors In Python. (line 38) 36330* read_var on Frame: Frames In Python. (line 75) 36331* reading symbols from relocatable object files: Files. (line 132) 36332* reading symbols immediately: Files. (line 90) 36333* readline: Editing. (line 6) 36334* readnow: Files. (line 90) 36335* rec: Process Record and Replay. 36336 (line 38) 36337* rec del: Process Record and Replay. 36338 (line 155) 36339* rec s: Process Record and Replay. 36340 (line 57) 36341* receive rights, GNU Hurd: Hurd Native. (line 85) 36342* recent tracepoint number: Create and Delete Tracepoints. 36343 (line 98) 36344* record: Process Record and Replay. 36345 (line 38) 36346* record aggregates (Ada): Omissions from Ada. (line 44) 36347* record delete: Process Record and Replay. 36348 (line 155) 36349* record mode: Process Record and Replay. 36350 (line 19) 36351* record restore: Process Record and Replay. 36352 (line 85) 36353* record save: Process Record and Replay. 36354 (line 80) 36355* record serial communications on file: Remote Configuration. 36356 (line 57) 36357* record stop: Process Record and Replay. 36358 (line 57) 36359* recording a session script: Bug Reporting. (line 89) 36360* recording inferior's execution and replaying it: Process Record and Replay. 36361 (line 6) 36362* redirection: Input/Output. (line 6) 36363* redraw-current-line (): Commands For Moving. (line 30) 36364* reference card: Formatting Documentation. 36365 (line 6) 36366* reference declarations: C Plus Plus Expressions. 36367 (line 51) 36368* reference on Type: Types In Python. (line 110) 36369* refresh: TUI Commands. (line 58) 36370* register stack, AMD29K: A29K. (line 6) 36371* registers: Registers. (line 6) 36372* regs, Super-H: Super-H. (line 9) 36373* regular expression: Set Breaks. (line 92) 36374* reinterpret_cast on Value: Values From Inferior. 36375 (line 97) 36376* reloading symbols: Symbols. (line 217) 36377* reloading the overlay table: Overlay Commands. (line 52) 36378* relocatable object files, reading symbols from: Files. (line 132) 36379* remote connection without stubs: Server. (line 6) 36380* remote debugging: Remote Debugging. (line 6) 36381* remote delete: File Transfer. (line 23) 36382* remote get: File Transfer. (line 19) 36383* remote memory comparison: Memory. (line 123) 36384* remote monitor prompt: MIPS Embedded. (line 107) 36385* remote packets, enabling and disabling: Remote Configuration. 36386 (line 143) 36387* remote programs, interrupting: Connecting. (line 78) 36388* remote protocol debugging: Debugging Output. (line 123) 36389* remote protocol, binary data: Overview. (line 61) 36390* remote protocol, field separator: Overview. (line 53) 36391* remote put: File Transfer. (line 15) 36392* remote query requests: General Query Packets. 36393 (line 6) 36394* remote serial debugging summary: Debug Session. (line 6) 36395* remote serial debugging, overview: Remote Stub. (line 14) 36396* remote serial protocol: Overview. (line 14) 36397* remote serial stub: Stub Contents. (line 6) 36398* remote serial stub list: Remote Stub. (line 54) 36399* remote serial stub, initialization: Stub Contents. (line 10) 36400* remote serial stub, main routine: Stub Contents. (line 15) 36401* remote stub, example: Remote Stub. (line 6) 36402* remote stub, support routines: Bootstrapping. (line 6) 36403* remote target: Target Commands. (line 58) 36404* remote target, file transfer: File Transfer. (line 6) 36405* remote target, limit break- and watchpoints: Remote Configuration. 36406 (line 72) 36407* remote timeout: Remote Configuration. 36408 (line 65) 36409* remotetimeout: Sparclet. (line 12) 36410* remove actions from a tracepoint: Tracepoint Actions. (line 21) 36411* remove-inferior: Inferiors and Programs. 36412 (line 86) 36413* rename, file-i/o system call: rename. (line 6) 36414* Renesas: Remote Stub. (line 63) 36415* repeated array elements: Print Settings. (line 176) 36416* repeating command sequences: Command Syntax. (line 42) 36417* repeating commands: Command Syntax. (line 21) 36418* replay log events, remote reply: Stop Reply Packets. (line 61) 36419* replay mode: Process Record and Replay. 36420 (line 10) 36421* reporting bugs in GDB: GDB Bugs. (line 6) 36422* reprint the last value: Data. (line 23) 36423* reset SDI connection, M32R: M32R/D. (line 44) 36424* response time, MIPS debugging: MIPS. (line 10) 36425* restart: Checkpoint/Restart. (line 6) 36426* restart CHECKPOINT-ID: Checkpoint/Restart. (line 44) 36427* restore: Dump/Restore Files. (line 41) 36428* restore data from a file: Dump/Restore Files. (line 6) 36429* result records in GDB/MI: GDB/MI Result Records. 36430 (line 6) 36431* resume threads of multiple processes simultaneously: All-Stop Mode. 36432 (line 53) 36433* resuming execution: Continuing and Stepping. 36434 (line 6) 36435* RET (repeat last command): Command Syntax. (line 21) 36436* retransmit-timeout, MIPS protocol: MIPS Embedded. (line 83) 36437* return: Returning. (line 6) 36438* returning from a function: Returning. (line 6) 36439* reverse execution: Reverse Execution. (line 6) 36440* reverse-continue: Reverse Execution. (line 30) 36441* reverse-finish: Reverse Execution. (line 77) 36442* reverse-next: Reverse Execution. (line 60) 36443* reverse-nexti: Reverse Execution. (line 69) 36444* reverse-search: Search. (line 16) 36445* reverse-search-history (C-r): Commands For History. 36446 (line 26) 36447* reverse-step: Reverse Execution. (line 37) 36448* reverse-stepi: Reverse Execution. (line 52) 36449* revert-line (M-r): Miscellaneous Commands. 36450 (line 25) 36451* rewind program state: Checkpoint/Restart. (line 6) 36452* Right: TUI Keys. (line 62) 36453* rn (reverse-next): Reverse Execution. (line 60) 36454* rni (reverse-nexti): Reverse Execution. (line 69) 36455* ROM at zero address, RDI: ARM. (line 102) 36456* rs (step): Reverse Execution. (line 37) 36457* rsi (reverse-stepi): Reverse Execution. (line 52) 36458* run: Starting. (line 6) 36459* run to main procedure: Starting. (line 79) 36460* run until specified location: Continuing and Stepping. 36461 (line 118) 36462* run&: Background Execution. 36463 (line 34) 36464* running: Starting. (line 6) 36465* running and debugging Sparclet programs: Sparclet Execution. 36466 (line 6) 36467* running programs backward: Reverse Execution. (line 6) 36468* running VxWorks tasks: VxWorks Attach. (line 6) 36469* running, on Sparclet: Sparclet. (line 28) 36470* rwatch: Set Watchpoints. (line 64) 36471* s (SingleKey TUI key): TUI Single Key Mode. (line 28) 36472* s (step): Continuing and Stepping. 36473 (line 46) 36474* S packet: Packets. (line 264) 36475* s packet: Packets. (line 258) 36476* save breakpoints: Save Breakpoints. (line 9) 36477* save breakpoints to a file for future sessions: Save Breakpoints. 36478 (line 9) 36479* save command history: Command History. (line 36) 36480* save GDB output to a file: Logging Output. (line 6) 36481* save gdb-index: Index Files. (line 19) 36482* save tracepoints: save tracepoints. (line 6) 36483* save tracepoints for future sessions: save tracepoints. (line 6) 36484* save-tracepoints: save tracepoints. (line 6) 36485* scheduler locking mode: All-Stop Mode. (line 37) 36486* scope: M2 Scope. (line 6) 36487* scripting commands: Command Files. (line 6) 36488* scripting with python: Python. (line 6) 36489* sdireset: M32R/D. (line 44) 36490* sdistatus: M32R/D. (line 47) 36491* SDS protocol: PowerPC Embedded. (line 44) 36492* sds, a command: PowerPC Embedded. (line 55) 36493* search: Search. (line 9) 36494* search path for libthread_db: Threads. (line 186) 36495* search_memory on Inferior: Inferiors In Python. (line 51) 36496* searching memory: Searching Memory. (line 6) 36497* searching memory, in remote debugging: General Query Packets. 36498 (line 280) 36499* searching source files: Search. (line 6) 36500* section: Files. (line 182) 36501* section offsets, remote request: General Query Packets. 36502 (line 182) 36503* segment descriptor tables: DJGPP Native. (line 24) 36504* select Ctrl-C, BREAK or BREAK-g: Remote Configuration. 36505 (line 96) 36506* select on Frame: Frames In Python. (line 83) 36507* select trace snapshot: tfind. (line 6) 36508* select-frame: Frames. (line 51) 36509* selected frame: Stack. (line 19) 36510* selected_frame: Frames In Python. (line 22) 36511* selected_thread: Threads In Python. (line 14) 36512* selecting frame silently: Frames. (line 51) 36513* self-insert (a, b, A, 1, !, ...): Commands For Text. (line 27) 36514* send command to remote monitor: Connecting. (line 105) 36515* send command to simulator: Embedded Processors. (line 9) 36516* send interrupt-sequence on start: Remote Configuration. 36517 (line 109) 36518* send PMON command: MIPS Embedded. (line 132) 36519* send rights, GNU Hurd: Hurd Native. (line 85) 36520* sending files to remote systems: File Transfer. (line 6) 36521* separate debugging information files: Separate Debug Files. 36522 (line 6) 36523* sequence-id, for GDB remote: Overview. (line 29) 36524* serial connections, debugging: Debugging Output. (line 123) 36525* serial line, target remote: Connecting. (line 18) 36526* serial protocol, GDB remote: Overview. (line 14) 36527* server prefix: Server Prefix. (line 6) 36528* server, command prefix: Command History. (line 20) 36529* set: Help. (line 107) 36530* set ABI for MIPS: MIPS. (line 32) 36531* set ada trust-PAD-over-XVS: Ada Glitches. (line 48) 36532* set annotate: Annotations Overview. 36533 (line 29) 36534* set architecture: Targets. (line 21) 36535* set args: Arguments. (line 21) 36536* set arm: ARM. (line 18) 36537* set auto-solib-add: Files. (line 303) 36538* set backtrace: Backtrace. (line 104) 36539* set board-address: M32R/D. (line 21) 36540* set breakpoint always-inserted: Set Breaks. (line 313) 36541* set breakpoint auto-hw: Set Breaks. (line 293) 36542* set breakpoint pending: Set Breaks. (line 262) 36543* set breakpoints in many functions: Set Breaks. (line 92) 36544* set breakpoints on all functions: Set Breaks. (line 112) 36545* set can-use-hw-watchpoints: Set Watchpoints. (line 101) 36546* set case-sensitive: Symbols. (line 27) 36547* set charset: Character Sets. (line 46) 36548* set check range: Range Checking. (line 34) 36549* set check type: Type Checking. (line 42) 36550* set circular-trace-buffer: Starting and Stopping Trace Experiments. 36551 (line 87) 36552* set coerce-float-to-double: ABI. (line 41) 36553* set com1base: DJGPP Native. (line 125) 36554* set com1irq: DJGPP Native. (line 125) 36555* set com2base: DJGPP Native. (line 125) 36556* set com2irq: DJGPP Native. (line 125) 36557* set com3base: DJGPP Native. (line 125) 36558* set com3irq: DJGPP Native. (line 125) 36559* set com4base: DJGPP Native. (line 125) 36560* set com4irq: DJGPP Native. (line 125) 36561* set complaints: Messages/Warnings. (line 29) 36562* set confirm: Messages/Warnings. (line 50) 36563* set cp-abi: ABI. (line 53) 36564* set cygwin-exceptions: Cygwin Native. (line 42) 36565* set data-directory: Data Files. (line 12) 36566* set debug: Debugging Output. (line 18) 36567* set debug darwin: Darwin. (line 9) 36568* set debug hppa: HPPA. (line 10) 36569* set debug libthread-db: Threads. (line 213) 36570* set debug mach-o: Darwin. (line 16) 36571* set debug mips: MIPS. (line 106) 36572* set debug monitor: Target Commands. (line 108) 36573* set debug nto-debug: Neutrino. (line 9) 36574* set debug-file-directory: Separate Debug Files. 36575 (line 68) 36576* set debugevents: Cygwin Native. (line 71) 36577* set debugexceptions: Cygwin Native. (line 82) 36578* set debugexec: Cygwin Native. (line 78) 36579* set debugmemory: Cygwin Native. (line 86) 36580* set default-collect: Tracepoint Actions. (line 114) 36581* set demangle-style: Print Settings. (line 296) 36582* set detach-on-fork: Forks. (line 55) 36583* set disable-randomization: Starting. (line 136) 36584* set disassemble-next-line: Machine Code. (line 139) 36585* set disassembly-flavor: Machine Code. (line 127) 36586* set disconnected-tracing: Starting and Stopping Trace Experiments. 36587 (line 48) 36588* set displaced-stepping: Maintenance Commands. 36589 (line 56) 36590* set download-path: M32R/D. (line 15) 36591* set editing: Editing. (line 15) 36592* set endian: Byte Order. (line 13) 36593* set environment: Environment. (line 39) 36594* set exceptions, Hurd command: Hurd Native. (line 40) 36595* set exec-direction: Reverse Execution. (line 83) 36596* set exec-done-display: Debugging Output. (line 11) 36597* set exec-wrapper: Starting. (line 111) 36598* set extension-language: Show. (line 30) 36599* set fast tracepoint: Create and Delete Tracepoints. 36600 (line 40) 36601* set follow-exec-mode: Forks. (line 101) 36602* set follow-fork-mode: Forks. (line 35) 36603* set gnutarget: Target Commands. (line 28) 36604* set hash, for remote monitors: Target Commands. (line 99) 36605* set height: Screen Size. (line 21) 36606* set history expansion: Command History. (line 65) 36607* set history filename: Command History. (line 26) 36608* set history save: Command History. (line 36) 36609* set history size: Command History. (line 45) 36610* set host-charset: Character Sets. (line 33) 36611* set inferior controlling terminal: Input/Output. (line 44) 36612* set inferior-tty: Input/Output. (line 49) 36613* set input-radix: Numbers. (line 14) 36614* set interactive-mode: Other Misc Settings. (line 6) 36615* set language: Manually. (line 9) 36616* set libthread-db-search-path: Threads. (line 186) 36617* set listsize: List. (line 33) 36618* set logging: Logging Output. (line 9) 36619* set mach-exceptions: Darwin. (line 27) 36620* set max-user-call-depth: Define. (line 76) 36621* set mem inaccessible-by-default: Memory Region Attributes. 36622 (line 130) 36623* set mips abi: MIPS. (line 32) 36624* set mips compression: MIPS. (line 55) 36625* set mips mask-address: MIPS. (line 86) 36626* set mipsfpu: MIPS Embedded. (line 60) 36627* set monitor-prompt, MIPS remote: MIPS Embedded. (line 107) 36628* set monitor-warnings, MIPS remote: MIPS Embedded. (line 123) 36629* set multiple-symbols: Ambiguous Expressions. 36630 (line 50) 36631* set new-console: Cygwin Native. (line 54) 36632* set new-group: Cygwin Native. (line 63) 36633* set non-stop: Non-Stop Mode. (line 38) 36634* set opaque-type-resolution: Symbols. (line 241) 36635* set osabi: ABI. (line 11) 36636* set output-radix: Numbers. (line 31) 36637* set overload-resolution: Debugging C Plus Plus. 36638 (line 48) 36639* set pagination: Screen Size. (line 38) 36640* set powerpc: PowerPC Embedded. (line 18) 36641* set print: Print Settings. (line 11) 36642* set print frame-arguments: Print Settings. (line 135) 36643* set print inferior-events: Inferiors and Programs. 36644 (line 116) 36645* set print thread-events: Threads. (line 165) 36646* set processor: Targets. (line 31) 36647* set procfs-file: SVR4 Process Information. 36648 (line 59) 36649* set procfs-trace: SVR4 Process Information. 36650 (line 53) 36651* set prompt: Prompt. (line 16) 36652* set radix: Numbers. (line 44) 36653* set rdiheartbeat: ARM. (line 112) 36654* set rdiromatzero: ARM. (line 102) 36655* set record insn-number-max: Process Record and Replay. 36656 (line 89) 36657* set record memory-query: Process Record and Replay. 36658 (line 123) 36659* set record stop-at-limit: Process Record and Replay. 36660 (line 109) 36661* set remote: Remote Configuration. 36662 (line 6) 36663* set remote system-call-allowed: system. (line 38) 36664* set remote-mips64-transfers-32bit-regs: MIPS. (line 96) 36665* set remotecache: Caching Remote Data. (line 18) 36666* set remoteflow: Remote Configuration. 36667 (line 41) 36668* set retransmit-timeout: MIPS Embedded. (line 83) 36669* set rstack_high_address: A29K. (line 6) 36670* set schedule-multiple: All-Stop Mode. (line 66) 36671* set script-extension: Extending GDB. (line 19) 36672* set sdstimeout: PowerPC Embedded. (line 48) 36673* set server-address: M32R/D. (line 27) 36674* set sh calling-convention: Super-H. (line 12) 36675* set shell: Cygwin Native. (line 90) 36676* set signal-thread: Hurd Native. (line 21) 36677* set signals, Hurd command: Hurd Native. (line 11) 36678* set sigs, Hurd command: Hurd Native. (line 11) 36679* set sigthread: Hurd Native. (line 21) 36680* set solib-absolute-prefix: Files. (line 374) 36681* set solib-search-path: Files. (line 443) 36682* set spu: SPU. (line 39) 36683* set stack-cache: Caching Remote Data. (line 26) 36684* set static tracepoint: Create and Delete Tracepoints. 36685 (line 51) 36686* set step-mode: Continuing and Stepping. 36687 (line 92) 36688* set stop-on-solib-events: Files. (line 351) 36689* set stopped, Hurd command: Hurd Native. (line 32) 36690* set struct-convention: i386. (line 7) 36691* set substitute-path: Source Path. (line 123) 36692* set symbol-reloading: Symbols. (line 224) 36693* set syn-garbage-limit, MIPS remote: MIPS Embedded. (line 98) 36694* set sysroot: Files. (line 374) 36695* set target-async: Background Execution. 36696 (line 17) 36697* set target-charset: Character Sets. (line 28) 36698* set target-file-system-kind (unix|dos-based|auto): Files. (line 457) 36699* set target-wide-charset: Character Sets. (line 61) 36700* set task, Hurd commands: Hurd Native. (line 49) 36701* set tcp: Remote Configuration. 36702 (line 118) 36703* set tdesc filename: Retrieving Descriptions. 36704 (line 18) 36705* set thread, Hurd command: Hurd Native. (line 91) 36706* set timeout: MIPS Embedded. (line 83) 36707* set trace-commands: Messages/Warnings. (line 67) 36708* set tracepoint: Create and Delete Tracepoints. 36709 (line 6) 36710* set trust-readonly-sections: Files. (line 258) 36711* set tui active-border-mode: TUI Configuration. (line 24) 36712* set tui border-kind: TUI Configuration. (line 9) 36713* set tui border-mode: TUI Configuration. (line 23) 36714* set unwind-on-terminating-exception: Calling. (line 46) 36715* set unwindonsignal: Calling. (line 35) 36716* set variable: Assignment. (line 16) 36717* set verbose: Messages/Warnings. (line 15) 36718* set watchdog: Maintenance Commands. 36719 (line 357) 36720* set width: Screen Size. (line 21) 36721* set write: Patching. (line 15) 36722* set-mark (C-@): Miscellaneous Commands. 36723 (line 32) 36724* set_debug_traps: Stub Contents. (line 10) 36725* set_doc: Parameters In Python. 36726 (line 54) 36727* setting variables: Assignment. (line 6) 36728* setting watchpoints: Set Watchpoints. (line 6) 36729* SH: Remote Stub. (line 63) 36730* sh-stub.c: Remote Stub. (line 63) 36731* share: Files. (line 332) 36732* shared libraries: Files. (line 281) 36733* shared library events, remote reply: Stop Reply Packets. (line 56) 36734* sharedlibrary: Files. (line 332) 36735* shell: Shell Commands. (line 10) 36736* shell escape: Shell Commands. (line 10) 36737* show: Help. (line 112) 36738* show ada trust-PAD-over-XVS: Ada Glitches. (line 48) 36739* show all convenience functions: Convenience Vars. (line 112) 36740* show all user variables: Convenience Vars. (line 37) 36741* show annotate: Annotations Overview. 36742 (line 34) 36743* show architecture: Targets. (line 21) 36744* show args: Arguments. (line 28) 36745* show arm: ARM. (line 22) 36746* show auto-solib-add: Files. (line 320) 36747* show backtrace: Backtrace. (line 111) 36748* show board-address: M32R/D. (line 24) 36749* show breakpoint always-inserted: Set Breaks. (line 313) 36750* show breakpoint auto-hw: Set Breaks. (line 293) 36751* show breakpoint pending: Set Breaks. (line 262) 36752* show can-use-hw-watchpoints: Set Watchpoints. (line 104) 36753* show case-sensitive: Symbols. (line 40) 36754* show charset: Character Sets. (line 52) 36755* show check range: Range Checking. (line 34) 36756* show check type: Type Checking. (line 42) 36757* show circular-trace-buffer: Starting and Stopping Trace Experiments. 36758 (line 94) 36759* show coerce-float-to-double: ABI. (line 50) 36760* show com1base: DJGPP Native. (line 137) 36761* show com1irq: DJGPP Native. (line 137) 36762* show com2base: DJGPP Native. (line 137) 36763* show com2irq: DJGPP Native. (line 137) 36764* show com3base: DJGPP Native. (line 137) 36765* show com3irq: DJGPP Native. (line 137) 36766* show com4base: DJGPP Native. (line 137) 36767* show com4irq: DJGPP Native. (line 137) 36768* show commands: Command History. (line 78) 36769* show complaints: Messages/Warnings. (line 35) 36770* show confirm: Messages/Warnings. (line 58) 36771* show convenience: Convenience Vars. (line 37) 36772* show copying: Help. (line 136) 36773* show cp-abi: ABI. (line 53) 36774* show cygwin-exceptions: Cygwin Native. (line 50) 36775* show data-directory: Data Files. (line 16) 36776* show debug: Debugging Output. (line 22) 36777* show debug darwin: Darwin. (line 13) 36778* show debug libthread-db: Threads. (line 213) 36779* show debug mach-o: Darwin. (line 23) 36780* show debug mips: MIPS. (line 110) 36781* show debug monitor: Target Commands. (line 112) 36782* show debug nto-debug: Neutrino. (line 13) 36783* show debug-file-directory: Separate Debug Files. 36784 (line 73) 36785* show default-collect: Tracepoint Actions. (line 123) 36786* show detach-on-fork: Forks. (line 71) 36787* show directories: Source Path. (line 120) 36788* show disassemble-next-line: Machine Code. (line 139) 36789* show disassembly-flavor: Machine Code. (line 136) 36790* show disconnected-tracing: Starting and Stopping Trace Experiments. 36791 (line 55) 36792* show displaced-stepping: Maintenance Commands. 36793 (line 56) 36794* show download-path: M32R/D. (line 18) 36795* show editing: Editing. (line 22) 36796* show environment: Environment. (line 33) 36797* show exceptions, Hurd command: Hurd Native. (line 46) 36798* show exec-done-display: Debugging Output. (line 14) 36799* show follow-fork-mode: Forks. (line 49) 36800* show gnutarget: Target Commands. (line 40) 36801* show hash, for remote monitors: Target Commands. (line 105) 36802* show height: Screen Size. (line 21) 36803* show history: Command History. (line 70) 36804* show host-charset: Character Sets. (line 55) 36805* show inferior-tty: Input/Output. (line 52) 36806* show input-radix: Numbers. (line 36) 36807* show interactive-mode: Other Misc Settings. (line 17) 36808* show language: Show. (line 10) 36809* show last commands: Command History. (line 78) 36810* show libthread-db-search-path: Threads. (line 210) 36811* show listsize: List. (line 37) 36812* show logging: Logging Output. (line 26) 36813* show mach-exceptions: Darwin. (line 34) 36814* show max-user-call-depth: Define. (line 76) 36815* show mem inaccessible-by-default: Memory Region Attributes. 36816 (line 136) 36817* show mips abi: MIPS. (line 52) 36818* show mips compression: MIPS. (line 78) 36819* show mips mask-address: MIPS. (line 92) 36820* show mipsfpu: MIPS Embedded. (line 60) 36821* show monitor-prompt, MIPS remote: MIPS Embedded. (line 119) 36822* show monitor-warnings, MIPS remote: MIPS Embedded. (line 129) 36823* show multiple-symbols: Ambiguous Expressions. 36824 (line 70) 36825* show new-console: Cygwin Native. (line 59) 36826* show new-group: Cygwin Native. (line 68) 36827* show non-stop: Non-Stop Mode. (line 42) 36828* show opaque-type-resolution: Symbols. (line 256) 36829* show osabi: ABI. (line 11) 36830* show output-radix: Numbers. (line 39) 36831* show overload-resolution: Debugging C Plus Plus. 36832 (line 65) 36833* show pagination: Screen Size. (line 44) 36834* show paths: Environment. (line 29) 36835* show print: Print Settings. (line 39) 36836* show print inferior-events: Inferiors and Programs. 36837 (line 124) 36838* show print thread-events: Threads. (line 175) 36839* show processor: Targets. (line 31) 36840* show procfs-file: SVR4 Process Information. 36841 (line 64) 36842* show procfs-trace: SVR4 Process Information. 36843 (line 56) 36844* show prompt: Prompt. (line 19) 36845* show radix: Numbers. (line 44) 36846* show rdiheartbeat: ARM. (line 117) 36847* show rdiromatzero: ARM. (line 109) 36848* show record insn-number-max: Process Record and Replay. 36849 (line 106) 36850* show record memory-query: Process Record and Replay. 36851 (line 134) 36852* show record stop-at-limit: Process Record and Replay. 36853 (line 120) 36854* show remote: Remote Configuration. 36855 (line 6) 36856* show remote system-call-allowed: system. (line 42) 36857* show remote-mips64-transfers-32bit-regs: MIPS. (line 102) 36858* show remotecache: Caching Remote Data. (line 23) 36859* show remoteflow: Remote Configuration. 36860 (line 45) 36861* show retransmit-timeout: MIPS Embedded. (line 83) 36862* show rstack_high_address: A29K. (line 17) 36863* show script-extension: Extending GDB. (line 19) 36864* show sdstimeout: PowerPC Embedded. (line 52) 36865* show server-address: M32R/D. (line 31) 36866* show sh calling-convention: Super-H. (line 25) 36867* show shell: Cygwin Native. (line 94) 36868* show signal-thread: Hurd Native. (line 28) 36869* show signals, Hurd command: Hurd Native. (line 17) 36870* show sigs, Hurd command: Hurd Native. (line 17) 36871* show sigthread: Hurd Native. (line 28) 36872* show solib-search-path: Files. (line 454) 36873* show spu: SPU. (line 44) 36874* show stack-cache: Caching Remote Data. (line 31) 36875* show stop-on-solib-events: Files. (line 357) 36876* show stopped, Hurd command: Hurd Native. (line 37) 36877* show struct-convention: i386. (line 15) 36878* show substitute-path: Source Path. (line 160) 36879* show symbol-reloading: Symbols. (line 238) 36880* show syn-garbage-limit, MIPS remote: MIPS Embedded. (line 103) 36881* show sysroot: Files. (line 440) 36882* show target-async: Background Execution. 36883 (line 21) 36884* show target-charset: Character Sets. (line 58) 36885* show target-file-system-kind: Files. (line 457) 36886* show target-wide-charset: Character Sets. (line 67) 36887* show task, Hurd commands: Hurd Native. (line 57) 36888* show tcp: Remote Configuration. 36889 (line 118) 36890* show tdesc filename: Retrieving Descriptions. 36891 (line 25) 36892* show thread, Hurd command: Hurd Native. (line 101) 36893* show timeout: MIPS Embedded. (line 83) 36894* show unwind-on-terminating-exception: Calling. (line 54) 36895* show unwindonsignal: Calling. (line 42) 36896* show user: Define. (line 70) 36897* show values: Value History. (line 47) 36898* show verbose: Messages/Warnings. (line 21) 36899* show version: Help. (line 126) 36900* show warranty: Help. (line 140) 36901* show width: Screen Size. (line 21) 36902* show write: Patching. (line 26) 36903* show-all-if-ambiguous: Readline Init File Syntax. 36904 (line 164) 36905* show-all-if-unmodified: Readline Init File Syntax. 36906 (line 170) 36907* show_doc: Parameters In Python. 36908 (line 60) 36909* si (stepi): Continuing and Stepping. 36910 (line 190) 36911* signal: Signaling. (line 6) 36912* signal annotation: Annotations for Running. 36913 (line 42) 36914* signal-name annotation: Annotations for Running. 36915 (line 22) 36916* signal-name-end annotation: Annotations for Running. 36917 (line 22) 36918* signal-string annotation: Annotations for Running. 36919 (line 22) 36920* signal-string-end annotation: Annotations for Running. 36921 (line 22) 36922* signalled annotation: Annotations for Running. 36923 (line 22) 36924* signals: Signals. (line 6) 36925* SIGQUIT signal, dump core of GDB: Maintenance Commands. 36926 (line 99) 36927* silent <1>: Breakpoints In Python. 36928 (line 45) 36929* silent: Break Commands. (line 43) 36930* sim: Z8000. (line 15) 36931* sim, a command: Embedded Processors. (line 13) 36932* simulator, Z8000: Z8000. (line 6) 36933* size of remote memory accesses: Packets. (line 203) 36934* size of screen: Screen Size. (line 6) 36935* sizeof: Types In Python. (line 28) 36936* snapshot of a process: Checkpoint/Restart. (line 6) 36937* software watchpoints: Set Watchpoints. (line 31) 36938* solib_name: Basic Python. (line 123) 36939* source: Command Files. (line 17) 36940* source annotation: Source Annotations. (line 6) 36941* source file and line of a symbol: Print Settings. (line 51) 36942* source line and its code address: Machine Code. (line 6) 36943* source path: Source Path. (line 6) 36944* Sparc: Remote Stub. (line 66) 36945* sparc-stub.c: Remote Stub. (line 66) 36946* sparcl-stub.c: Remote Stub. (line 69) 36947* Sparclet: Sparclet. (line 6) 36948* SparcLite: Remote Stub. (line 69) 36949* Special Fortran commands: Special Fortran Commands. 36950 (line 6) 36951* specifying location: Specify Location. (line 6) 36952* spr: OpenRISC 1000. (line 33) 36953* SPU: SPU. (line 6) 36954* SSE registers (x86): Registers. (line 71) 36955* stack frame: Frames. (line 6) 36956* stack on Alpha: MIPS. (line 6) 36957* stack on MIPS: MIPS. (line 6) 36958* stack pointer register: Registers. (line 26) 36959* stacking targets: Active Targets. (line 6) 36960* standard registers: Registers. (line 26) 36961* start <1>: Blocks In Python. (line 24) 36962* start: Starting. (line 78) 36963* start a new trace experiment: Starting and Stopping Trace Experiments. 36964 (line 6) 36965* start-kbd-macro (C-x (): Keyboard Macros. (line 6) 36966* starting: Starting. (line 6) 36967* starting annotation: Annotations for Running. 36968 (line 6) 36969* startup code, and backtrace: Backtrace. (line 93) 36970* stat, file-i/o system call: stat/fstat. (line 6) 36971* static members of C++ objects: Print Settings. (line 342) 36972* static members of Pascal objects: Print Settings. (line 353) 36973* static tracepoints: Set Tracepoints. (line 28) 36974* static tracepoints, in remote protocol: General Query Packets. 36975 (line 547) 36976* static tracepoints, setting: Create and Delete Tracepoints. 36977 (line 51) 36978* status of trace data collection: Starting and Stopping Trace Experiments. 36979 (line 20) 36980* status output in GDB/MI: GDB/MI Output Syntax. 36981 (line 94) 36982* step: Continuing and Stepping. 36983 (line 46) 36984* step&: Background Execution. 36985 (line 41) 36986* stepi: Continuing and Stepping. 36987 (line 190) 36988* stepi&: Background Execution. 36989 (line 44) 36990* stepping: Continuing and Stepping. 36991 (line 6) 36992* stepping into functions with no line info: Continuing and Stepping. 36993 (line 93) 36994* stop a running trace experiment: Starting and Stopping Trace Experiments. 36995 (line 12) 36996* stop on C++ exceptions: Set Catchpoints. (line 13) 36997* stop reply packets: Stop Reply Packets. (line 6) 36998* stop, a pseudo-command: Hooks. (line 21) 36999* stopped threads: Thread Stops. (line 6) 37000* stopping annotation: Annotations for Running. 37001 (line 6) 37002* strace: Create and Delete Tracepoints. 37003 (line 51) 37004* stream records in GDB/MI: GDB/MI Stream Records. 37005 (line 6) 37006* string on Value: Values From Inferior. 37007 (line 101) 37008* strip_typedefs on Type: Types In Python. (line 118) 37009* struct return convention: i386. (line 7) 37010* struct stat, in file-i/o protocol: struct stat. (line 6) 37011* struct timeval, in file-i/o protocol: struct timeval. (line 6) 37012* struct user contents: OS Information. (line 9) 37013* struct/union returned in registers: i386. (line 7) 37014* structure field name completion: Completion. (line 96) 37015* stub example, remote debugging: Remote Stub. (line 6) 37016* stupid questions: Messages/Warnings. (line 50) 37017* Super-H: Super-H. (line 6) 37018* superblock: Blocks In Python. (line 36) 37019* supported packets, remote query: General Query Packets. 37020 (line 315) 37021* switch on InferiorThread: Threads In Python. (line 33) 37022* switching threads: Threads. (line 6) 37023* switching threads automatically: All-Stop Mode. (line 28) 37024* symbol decoding style, C++: Print Settings. (line 296) 37025* symbol dump: Symbols. (line 259) 37026* symbol from address: Symbols. (line 54) 37027* symbol lookup, remote request: General Query Packets. 37028 (line 551) 37029* symbol names: Symbols. (line 14) 37030* symbol table: Files. (line 6) 37031* symbol tables in python: Symbol Tables In Python. 37032 (line 6) 37033* symbol tables, listing GDB's internal: Symbols. (line 278) 37034* symbol, source file and line: Print Settings. (line 51) 37035* symbol-file: Files. (line 45) 37036* SYMBOL_FUNCTIONS_DOMAIN: Symbols In Python. (line 83) 37037* SYMBOL_LABEL_DOMAIN: Symbols In Python. (line 76) 37038* SYMBOL_LOC_ARG: Symbols In Python. (line 105) 37039* SYMBOL_LOC_BLOCK: Symbols In Python. (line 126) 37040* SYMBOL_LOC_COMPUTED: Symbols In Python. (line 140) 37041* SYMBOL_LOC_CONST: Symbols In Python. (line 96) 37042* SYMBOL_LOC_CONST_BYTES: Symbols In Python. (line 129) 37043* SYMBOL_LOC_LOCAL: Symbols In Python. (line 119) 37044* SYMBOL_LOC_OPTIMIZED_OUT: Symbols In Python. (line 137) 37045* SYMBOL_LOC_REF_ARG: Symbols In Python. (line 109) 37046* SYMBOL_LOC_REGISTER: Symbols In Python. (line 102) 37047* SYMBOL_LOC_REGPARM_ADDR: Symbols In Python. (line 114) 37048* SYMBOL_LOC_STATIC: Symbols In Python. (line 99) 37049* SYMBOL_LOC_TYPEDEF: Symbols In Python. (line 122) 37050* SYMBOL_LOC_UNDEF: Symbols In Python. (line 94) 37051* SYMBOL_LOC_UNRESOLVED: Symbols In Python. (line 132) 37052* SYMBOL_STRUCT_DOMAIN: Symbols In Python. (line 73) 37053* SYMBOL_TYPES_DOMAIN: Symbols In Python. (line 86) 37054* SYMBOL_UNDEF_DOMAIN: Symbols In Python. (line 66) 37055* SYMBOL_VAR_DOMAIN: Symbols In Python. (line 69) 37056* SYMBOL_VARIABLES_DOMAIN: Symbols In Python. (line 79) 37057* symbols in python: Symbols In Python. (line 6) 37058* symbols, reading from relocatable object files: Files. (line 132) 37059* symbols, reading immediately: Files. (line 90) 37060* symtab <1>: Symbol Tables In Python. 37061 (line 17) 37062* symtab: Symbols In Python. (line 28) 37063* synchronize with remote MIPS target: MIPS Embedded. (line 98) 37064* syscall DSO: Files. (line 162) 37065* sysinfo: DJGPP Native. (line 19) 37066* system calls and thread breakpoints: Interrupted System Calls. 37067 (line 6) 37068* system root, alternate: Files. (line 374) 37069* system, file-i/o system call: system. (line 6) 37070* system-wide init file: System-wide configuration. 37071 (line 6) 37072* T packet: Packets. (line 276) 37073* t packet: Packets. (line 271) 37074* T packet reply: Stop Reply Packets. (line 22) 37075* tabset: TUI Commands. (line 84) 37076* tag: Types In Python. (line 33) 37077* target: Target Commands. (line 49) 37078* target architecture: Targets. (line 17) 37079* target array: MIPS Embedded. (line 49) 37080* target byte order: Byte Order. (line 6) 37081* target character set: Character Sets. (line 6) 37082* target dbug: M68K. (line 9) 37083* target ddb PORT: MIPS Embedded. (line 41) 37084* target debugging info: Debugging Output. (line 148) 37085* target descriptions: Target Descriptions. (line 6) 37086* target descriptions, ARM features: ARM Features. (line 6) 37087* target descriptions, i386 features: i386 Features. (line 6) 37088* target descriptions, inclusion: Target Description Format. 37089 (line 54) 37090* target descriptions, M68K features: M68K Features. (line 6) 37091* target descriptions, MIPS features: MIPS Features. (line 6) 37092* target descriptions, PowerPC features: PowerPC Features. (line 6) 37093* target descriptions, predefined types: Predefined Target Types. 37094 (line 6) 37095* target descriptions, standard features: Standard Target Features. 37096 (line 6) 37097* target descriptions, XML format: Target Description Format. 37098 (line 6) 37099* target dink32: PowerPC Embedded. (line 33) 37100* target jtag: OpenRISC 1000. (line 9) 37101* target lsi PORT: MIPS Embedded. (line 44) 37102* target m32r: M32R/D. (line 6) 37103* target m32rsdi: M32R/D. (line 9) 37104* target mips PORT: MIPS Embedded. (line 14) 37105* target on Type: Types In Python. (line 122) 37106* target op50n: PA. (line 6) 37107* target output in GDB/MI: GDB/MI Output Syntax. 37108 (line 110) 37109* target pmon PORT: MIPS Embedded. (line 38) 37110* target ppcbug: PowerPC Embedded. (line 36) 37111* target ppcbug1: PowerPC Embedded. (line 37) 37112* target r3900: MIPS Embedded. (line 46) 37113* target rdi: ARM. (line 6) 37114* target rdp: ARM. (line 11) 37115* target record: Process Record and Replay. 37116 (line 38) 37117* target remote: Connecting. (line 11) 37118* target sds: PowerPC Embedded. (line 41) 37119* target sim, with Z8000: Z8000. (line 15) 37120* target sparclite: Sparclite. (line 6) 37121* target stack description: Maintenance Commands. 37122 (line 236) 37123* target tfile: Trace Files. (line 22) 37124* target vxworks: VxWorks. (line 6) 37125* target w89k: PA. (line 9) 37126* target_charset: Basic Python. (line 112) 37127* target_wide_charset: Basic Python. (line 117) 37128* task: Breakpoints In Python. 37129 (line 58) 37130* task (Ada): Ada Tasks. (line 105) 37131* task attributes (GNU Hurd): Hurd Native. (line 49) 37132* task breakpoints, in Ada: Ada Tasks. (line 135) 37133* task exception port, GNU Hurd: Hurd Native. (line 68) 37134* task suspend count: Hurd Native. (line 60) 37135* tbreak: Set Breaks. (line 55) 37136* TCP port, target remote: Connecting. (line 29) 37137* tdump: tdump. (line 6) 37138* template_argument on Type: Types In Python. (line 137) 37139* terminal: Input/Output. (line 6) 37140* teval (tracepoints): Tracepoint Actions. (line 89) 37141* Text User Interface: TUI. (line 6) 37142* tfile: Trace Files. (line 22) 37143* tfind: tfind. (line 6) 37144* thbreak: Set Breaks. (line 82) 37145* this, inside C++ member functions: C Plus Plus Expressions. 37146 (line 22) 37147* thread: Breakpoints In Python. 37148 (line 53) 37149* thread apply: Threads. (line 156) 37150* thread attributes info, remote request: General Query Packets. 37151 (line 596) 37152* thread breakpoints: Thread-Specific Breakpoints. 37153 (line 10) 37154* thread breakpoints and system calls: Interrupted System Calls. 37155 (line 6) 37156* thread default settings, GNU Hurd: Hurd Native. (line 131) 37157* thread identifier (GDB): Threads. (line 63) 37158* thread identifier (GDB), on HP-UX: Threads. (line 89) 37159* thread identifier (system): Threads. (line 51) 37160* thread identifier (system), on HP-UX: Threads. (line 93) 37161* thread info (Solaris): Threads. (line 133) 37162* thread information, remote request: General Query Packets. 37163 (line 209) 37164* thread list format: Thread List Format. (line 6) 37165* thread number: Threads. (line 63) 37166* thread properties, GNU Hurd: Hurd Native. (line 91) 37167* thread suspend count, GNU Hurd: Hurd Native. (line 110) 37168* thread THREADNO: Threads. (line 135) 37169* THREAD-ID, in remote protocol: Packets. (line 20) 37170* threads and watchpoints: Set Watchpoints. (line 165) 37171* threads in python: Threads In Python. (line 6) 37172* threads of execution: Threads. (line 6) 37173* threads on Inferior: Inferiors In Python. (line 33) 37174* threads, automatic switching: All-Stop Mode. (line 28) 37175* threads, continuing: Thread Stops. (line 6) 37176* threads, stopped: Thread Stops. (line 6) 37177* time of command execution: Maintenance Commands. 37178 (line 328) 37179* timeout for commands: Maintenance Commands. 37180 (line 357) 37181* timeout for serial communications: Remote Configuration. 37182 (line 65) 37183* timeout, for remote target connection: Remote Configuration. 37184 (line 134) 37185* timeout, MIPS protocol: MIPS Embedded. (line 83) 37186* timestampping debugging info: Debugging Output. (line 159) 37187* tload, M32R: M32R/D. (line 39) 37188* to_string on pretty printer: Pretty Printing API. (line 54) 37189* trace: Create and Delete Tracepoints. 37190 (line 6) 37191* trace experiment, status of: Starting and Stopping Trace Experiments. 37192 (line 20) 37193* trace file format: Trace File Format. (line 6) 37194* trace files: Trace Files. (line 6) 37195* trace state variable value, remote request: Tracepoint Packets. 37196 (line 270) 37197* trace state variables: Trace State Variables. 37198 (line 6) 37199* traceback: Backtrace. (line 6) 37200* tracepoint actions: Tracepoint Actions. (line 6) 37201* tracepoint conditions: Tracepoint Conditions. 37202 (line 6) 37203* tracepoint data, display: tdump. (line 6) 37204* tracepoint deletion: Create and Delete Tracepoints. 37205 (line 101) 37206* tracepoint number: Create and Delete Tracepoints. 37207 (line 98) 37208* tracepoint packets: Tracepoint Packets. (line 6) 37209* tracepoint pass count: Tracepoint Passcounts. 37210 (line 6) 37211* tracepoint restrictions: Tracepoint Restrictions. 37212 (line 6) 37213* tracepoint variables: Tracepoint Variables. 37214 (line 6) 37215* tracepoints: Tracepoints. (line 6) 37216* tracepoints support in gdbserver: Server. (line 204) 37217* trailing underscore, in Fortran symbols: Fortran. (line 9) 37218* translating between character sets: Character Sets. (line 6) 37219* transpose-chars (C-t): Commands For Text. (line 30) 37220* transpose-words (M-t): Commands For Text. (line 36) 37221* tsave: Trace Files. (line 12) 37222* tstart: Starting and Stopping Trace Experiments. 37223 (line 6) 37224* tstatus: Starting and Stopping Trace Experiments. 37225 (line 20) 37226* tstop: Starting and Stopping Trace Experiments. 37227 (line 12) 37228* tty: Input/Output. (line 23) 37229* TUI: TUI. (line 6) 37230* TUI commands: TUI Commands. (line 6) 37231* TUI configuration variables: TUI Configuration. (line 6) 37232* TUI key bindings: TUI Keys. (line 6) 37233* tui reg: TUI Commands. (line 61) 37234* TUI single key mode: TUI Single Key Mode. (line 6) 37235* tvariable: Trace State Variables. 37236 (line 26) 37237* type <1>: Lazy Strings In Python. 37238 (line 44) 37239* type <2>: Breakpoints In Python. 37240 (line 73) 37241* type: Values From Inferior. 37242 (line 55) 37243* type casting memory: Expressions. (line 43) 37244* type chain of a data type: Maintenance Commands. 37245 (line 248) 37246* type checking: Checks. (line 31) 37247* type conversions in C++: C Plus Plus Expressions. 37248 (line 27) 37249* type on Frame: Frames In Python. (line 44) 37250* TYPE_CODE_ARRAY: Types In Python. (line 155) 37251* TYPE_CODE_BITSTRING: Types In Python. (line 193) 37252* TYPE_CODE_BOOL: Types In Python. (line 214) 37253* TYPE_CODE_CHAR: Types In Python. (line 211) 37254* TYPE_CODE_COMPLEX: Types In Python. (line 217) 37255* TYPE_CODE_DECFLOAT: Types In Python. (line 226) 37256* TYPE_CODE_ENUM: Types In Python. (line 164) 37257* TYPE_CODE_ERROR: Types In Python. (line 196) 37258* TYPE_CODE_FLAGS: Types In Python. (line 167) 37259* TYPE_CODE_FLT: Types In Python. (line 176) 37260* TYPE_CODE_FUNC: Types In Python. (line 170) 37261* TYPE_CODE_INT: Types In Python. (line 173) 37262* TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 229) 37263* TYPE_CODE_MEMBERPTR: Types In Python. (line 205) 37264* TYPE_CODE_METHOD: Types In Python. (line 199) 37265* TYPE_CODE_METHODPTR: Types In Python. (line 202) 37266* TYPE_CODE_NAMESPACE: Types In Python. (line 223) 37267* TYPE_CODE_PTR: Types In Python. (line 152) 37268* TYPE_CODE_RANGE: Types In Python. (line 185) 37269* TYPE_CODE_REF: Types In Python. (line 208) 37270* TYPE_CODE_SET: Types In Python. (line 182) 37271* TYPE_CODE_STRING: Types In Python. (line 188) 37272* TYPE_CODE_STRUCT: Types In Python. (line 158) 37273* TYPE_CODE_TYPEDEF: Types In Python. (line 220) 37274* TYPE_CODE_UNION: Types In Python. (line 161) 37275* TYPE_CODE_VOID: Types In Python. (line 179) 37276* types in Python: Types In Python. (line 6) 37277* u (SingleKey TUI key): TUI Single Key Mode. (line 31) 37278* u (until): Continuing and Stepping. 37279 (line 118) 37280* UDP port, target remote: Connecting. (line 49) 37281* undisplay: Auto Display. (line 45) 37282* undo (C-_ or C-x C-u): Miscellaneous Commands. 37283 (line 22) 37284* union field name completion: Completion. (line 96) 37285* unions in structures, printing: Print Settings. (line 236) 37286* universal-argument (): Numeric Arguments. (line 10) 37287* unix-filename-rubout (): Commands For Killing. 37288 (line 32) 37289* unix-line-discard (C-u): Commands For Killing. 37290 (line 12) 37291* unix-word-rubout (C-w): Commands For Killing. 37292 (line 28) 37293* unknown address, locating: Output Formats. (line 35) 37294* unlink, file-i/o system call: unlink. (line 6) 37295* unlinked object files: Files. (line 26) 37296* unload symbols from shared libraries: Files. (line 341) 37297* unmap an overlay: Overlay Commands. (line 39) 37298* unmapped overlays: How Overlays Work. (line 6) 37299* unqualified on Type: Types In Python. (line 99) 37300* unset environment: Environment. (line 55) 37301* unset substitute-path: Source Path. (line 152) 37302* unset tdesc filename: Retrieving Descriptions. 37303 (line 21) 37304* unsupported languages: Unsupported Languages. 37305 (line 6) 37306* unsupported packets, empty response for: Standard Replies. (line 10) 37307* until: Continuing and Stepping. 37308 (line 118) 37309* until&: Background Execution. 37310 (line 59) 37311* unwind stack in called functions: Calling. (line 35) 37312* unwind stack in called functions with unhandled exceptions: Calling. 37313 (line 46) 37314* unwind_stop_reason on Frame: Frames In Python. (line 49) 37315* Up: TUI Keys. (line 53) 37316* up: Selection. (line 29) 37317* up-silently: Selection. (line 58) 37318* upcase-word (M-u): Commands For Text. (line 41) 37319* update: TUI Commands. (line 76) 37320* upload, M32R: M32R/D. (line 34) 37321* use only software watchpoints: Set Watchpoints. (line 93) 37322* use_dbt_break: M32R/D. (line 64) 37323* use_debug_dma: M32R/D. (line 53) 37324* use_ib_break: M32R/D. (line 61) 37325* use_mon_code: M32R/D. (line 57) 37326* user-defined command: Define. (line 6) 37327* user-defined macros: Macros. (line 52) 37328* user-defined variables: Convenience Vars. (line 6) 37329* v (SingleKey TUI key): TUI Single Key Mode. (line 34) 37330* value: Parameters In Python. 37331 (line 66) 37332* value history: Value History. (line 6) 37333* value on LazyString: Lazy Strings In Python. 37334 (line 21) 37335* value optimized out, in backtrace: Backtrace. (line 71) 37336* values from inferior, with Python: Values From Inferior. 37337 (line 6) 37338* variable name conflict: Variables. (line 36) 37339* variable object debugging info: Debugging Output. (line 168) 37340* variable objects in GDB/MI: GDB/MI Variable Objects. 37341 (line 9) 37342* variable values, wrong: Variables. (line 58) 37343* variables, readline: Readline Init File Syntax. 37344 (line 34) 37345* variables, setting: Assignment. (line 16) 37346* vAttach packet: Packets. (line 291) 37347* vCont packet: Packets. (line 311) 37348* vCont? packet: Packets. (line 353) 37349* vector unit: Vector Unit. (line 6) 37350* vector, auxiliary: OS Information. (line 21) 37351* verbose operation: Messages/Warnings. (line 6) 37352* verify remote memory image: Memory. (line 123) 37353* vFile packet: Packets. (line 364) 37354* vFlashDone packet: Packets. (line 409) 37355* vFlashErase packet: Packets. (line 368) 37356* vFlashWrite packet: Packets. (line 390) 37357* virtual functions (C++) display: Print Settings. (line 364) 37358* visible-stats: Readline Init File Syntax. 37359 (line 179) 37360* vKill packet: Packets. (line 417) 37361* volatile on Type: Types In Python. (line 95) 37362* vRun packet: Packets. (line 430) 37363* vStopped packet: Packets. (line 447) 37364* VTBL display: Print Settings. (line 364) 37365* VxWorks: VxWorks. (line 6) 37366* vxworks-timeout: VxWorks. (line 23) 37367* w (SingleKey TUI key): TUI Single Key Mode. (line 37) 37368* was_attached: Inferiors In Python. (line 27) 37369* watch: Set Watchpoints. (line 42) 37370* watchdog timer: Maintenance Commands. 37371 (line 357) 37372* watchpoint annotation: Annotations for Running. 37373 (line 50) 37374* watchpoints: Breakpoints. (line 20) 37375* watchpoints and threads: Set Watchpoints. (line 165) 37376* weak alias functions: Calling. (line 58) 37377* whatis: Symbols. (line 74) 37378* where: Backtrace. (line 34) 37379* where to look for shared libraries: Files. (line 369) 37380* while: Command Files. (line 86) 37381* while-stepping (tracepoints): Tracepoint Actions. (line 97) 37382* wild pointer, interpreting: Print Settings. (line 79) 37383* winheight: TUI Commands. (line 80) 37384* word completion: Completion. (line 6) 37385* working directory: Source Path. (line 108) 37386* working directory (of your program): Working Directory. (line 6) 37387* working language: Languages. (line 13) 37388* WP_ACCESS: Breakpoints In Python. 37389 (line 29) 37390* WP_READ: Breakpoints In Python. 37391 (line 23) 37392* WP_WRITE: Breakpoints In Python. 37393 (line 26) 37394* write: Basic Python. (line 103) 37395* write data into object, remote request: General Query Packets. 37396 (line 756) 37397* write, file-i/o system call: write. (line 6) 37398* write_memory on Inferior: Inferiors In Python. (line 44) 37399* writing convenience functions: Functions In Python. (line 6) 37400* writing into corefiles: Patching. (line 6) 37401* writing into executables: Patching. (line 6) 37402* wrong values: Variables. (line 58) 37403* x (examine memory): Memory. (line 9) 37404* x command, default address: Machine Code. (line 30) 37405* X packet: Packets. (line 459) 37406* x(examine), and info line: Machine Code. (line 30) 37407* Xilinx MicroBlaze: MicroBlaze. (line 6) 37408* XInclude: Target Description Format. 37409 (line 54) 37410* XMD, Xilinx Microprocessor Debugger: MicroBlaze. (line 6) 37411* XML parser debugging: Debugging Output. (line 176) 37412* yank (C-y): Commands For Killing. 37413 (line 59) 37414* yank-last-arg (M-. or M-_): Commands For History. 37415 (line 64) 37416* yank-nth-arg (M-C-y): Commands For History. 37417 (line 55) 37418* yank-pop (M-y): Commands For Killing. 37419 (line 62) 37420* yanking text: Readline Killing Commands. 37421 (line 6) 37422* z packet: Packets. (line 469) 37423* Z packets: Packets. (line 469) 37424* Z0 packet: Packets. (line 484) 37425* z0 packet: Packets. (line 484) 37426* Z1 packet: Packets. (line 506) 37427* z1 packet: Packets. (line 506) 37428* Z2 packet: Packets. (line 522) 37429* z2 packet: Packets. (line 522) 37430* Z3 packet: Packets. (line 531) 37431* z3 packet: Packets. (line 531) 37432* Z4 packet: Packets. (line 540) 37433* z4 packet: Packets. (line 540) 37434* Z8000: Z8000. (line 6) 37435* Zilog Z8000 simulator: Z8000. (line 6) 37436* {TYPE}: Expressions. (line 43) 37437 37438 37439 37440Tag Table: 37441Node: Top2036 37442Node: Summary5210 37443Node: Free Software6915 37444Node: Contributors12483 37445Node: Sample Session20572 37446Node: Invocation27424 37447Node: Invoking GDB27968 37448Node: File Options30281 37449Node: Mode Options33018 37450Node: Startup39617 37451Ref: Startup-Footnote-141839 37452Node: Quitting GDB41948 37453Node: Shell Commands42845 37454Node: Logging Output43687 37455Node: Commands44533 37456Node: Command Syntax45171 37457Node: Completion47337 37458Ref: Completion-Footnote-152543 37459Node: Help52703 37460Node: Running57948 37461Node: Compilation59177 37462Node: Starting61154 37463Node: Arguments70044 37464Node: Environment71314 37465Node: Working Directory74582 37466Node: Input/Output75690 37467Node: Attach77661 37468Node: Kill Process80128 37469Node: Inferiors and Programs81109 37470Node: Threads88279 37471Node: Forks96813 37472Node: Checkpoint/Restart103121 37473Ref: Checkpoint/Restart-Footnote-1107650 37474Node: Stopping107685 37475Node: Breakpoints108844 37476Node: Set Breaks112280 37477Ref: Set Breaks-Footnote-1128572 37478Node: Set Watchpoints128820 37479Node: Set Catchpoints137342 37480Node: Delete Breaks146538 37481Node: Disabling148474 37482Node: Conditions151327 37483Node: Break Commands156276 37484Node: Save Breakpoints159500 37485Node: Error in Breakpoints160676 37486Node: Breakpoint-related Warnings161407 37487Node: Continuing and Stepping163734 37488Node: Signals173094 37489Ref: extra signal information177366 37490Node: Thread Stops178869 37491Node: All-Stop Mode179968 37492Node: Non-Stop Mode183866 37493Node: Background Execution187343 37494Node: Thread-Specific Breakpoints189912 37495Node: Interrupted System Calls191234 37496Node: Observer Mode192748 37497Node: Reverse Execution196187 37498Ref: Reverse Execution-Footnote-1200814 37499Ref: Reverse Execution-Footnote-2201441 37500Node: Process Record and Replay201491 37501Node: Stack208738 37502Node: Frames210231 37503Node: Backtrace212983 37504Ref: Backtrace-Footnote-1218214 37505Node: Selection218402 37506Node: Frame Info221033 37507Node: Source223364 37508Node: List224430 37509Node: Specify Location227043 37510Node: Edit230614 37511Ref: Edit-Footnote-1232089 37512Node: Search232324 37513Node: Source Path233132 37514Ref: set substitute-path239390 37515Node: Machine Code241611 37516Node: Data248285 37517Node: Expressions250955 37518Node: Ambiguous Expressions253047 37519Node: Variables256281 37520Node: Arrays260784 37521Node: Output Formats263315 37522Ref: Output Formats-Footnote-1266503 37523Node: Memory266660 37524Node: Auto Display272814 37525Node: Print Settings276529 37526Node: Pretty Printing290133 37527Node: Value History291170 37528Node: Convenience Vars293591 37529Node: Registers298326 37530Ref: Registers-Footnote-1303003 37531Node: Floating Point Hardware303398 37532Node: Vector Unit303930 37533Node: OS Information304317 37534Node: Memory Region Attributes306962 37535Node: Dump/Restore Files311632 37536Node: Core File Generation313937 37537Node: Character Sets315171 37538Node: Caching Remote Data321538 37539Ref: Caching Remote Data-Footnote-1323339 37540Node: Searching Memory323577 37541Node: Optimized Code326454 37542Node: Inline Functions328064 37543Node: Macros331034 37544Node: Tracepoints338137 37545Node: Set Tracepoints340198 37546Node: Create and Delete Tracepoints343137 37547Node: Enable and Disable Tracepoints348025 37548Node: Tracepoint Passcounts348809 37549Node: Tracepoint Conditions350236 37550Node: Trace State Variables351929 37551Node: Tracepoint Actions354119 37552Node: Listing Tracepoints359459 37553Node: Listing Static Tracepoint Markers360577 37554Node: Starting and Stopping Trace Experiments362423 37555Node: Tracepoint Restrictions366837 37556Node: Analyze Collected Data370590 37557Node: tfind371895 37558Node: tdump376317 37559Node: save tracepoints378832 37560Node: Tracepoint Variables379328 37561Node: Trace Files380456 37562Node: Overlays381914 37563Node: How Overlays Work382634 37564Ref: A code overlay385194 37565Node: Overlay Commands388632 37566Node: Automatic Overlay Debugging392822 37567Node: Overlay Sample Program394963 37568Node: Languages396723 37569Node: Setting397886 37570Node: Filenames399588 37571Node: Manually400399 37572Node: Automatically401608 37573Node: Show402669 37574Node: Checks403991 37575Node: Type Checking405381 37576Node: Range Checking408114 37577Node: Supported Languages410515 37578Node: C411725 37579Node: C Operators413016 37580Node: C Constants417335 37581Node: C Plus Plus Expressions419739 37582Node: C Defaults423282 37583Node: C Checks423965 37584Node: Debugging C424688 37585Node: Debugging C Plus Plus425172 37586Node: Decimal Floating Point428359 37587Node: D429618 37588Node: Objective-C429884 37589Node: Method Names in Commands430345 37590Node: The Print Command with Objective-C432040 37591Node: Fortran432691 37592Node: Fortran Operators433416 37593Node: Fortran Defaults434272 37594Node: Special Fortran Commands434657 37595Node: Pascal435163 37596Node: Modula-2435678 37597Node: M2 Operators436653 37598Node: Built-In Func/Proc439652 37599Node: M2 Constants442513 37600Node: M2 Types444114 37601Node: M2 Defaults447333 37602Node: Deviations447933 37603Node: M2 Checks449034 37604Node: M2 Scope449852 37605Node: GDB/M2450876 37606Node: Ada451788 37607Node: Ada Mode Intro452735 37608Node: Omissions from Ada454645 37609Node: Additions to Ada458999 37610Node: Stopping Before Main Program462929 37611Node: Ada Tasks463458 37612Node: Ada Tasks and Core Files469871 37613Node: Ada Glitches470784 37614Node: Unsupported Languages473851 37615Node: Symbols474541 37616Node: Altering488370 37617Node: Assignment489339 37618Node: Jumping492444 37619Node: Signaling494579 37620Node: Returning495710 37621Node: Calling499062 37622Node: Patching502089 37623Node: GDB Files503166 37624Node: Files503811 37625Ref: Shared Libraries516646 37626Ref: Files-Footnote-1526880 37627Node: Separate Debug Files527055 37628Node: Index Files538625 37629Node: Symbol Errors539968 37630Node: Data Files543581 37631Node: Targets544420 37632Node: Active Targets545900 37633Node: Target Commands546974 37634Ref: load551247 37635Node: Byte Order552228 37636Node: Remote Debugging553205 37637Node: Connecting554467 37638Node: File Transfer559407 37639Node: Server560347 37640Ref: Monitor Commands for gdbserver567997 37641Ref: Server-Footnote-1572546 37642Node: Remote Configuration572666 37643Ref: set remotebreak573690 37644Ref: set remote hardware-watchpoint-limit575154 37645Ref: set remote hardware-breakpoint-limit575154 37646Ref: set remote exec-file575436 37647Node: Remote Stub582008 37648Node: Stub Contents584905 37649Node: Bootstrapping587016 37650Node: Debug Session590825 37651Node: Configurations592385 37652Node: Native593154 37653Node: HP-UX593789 37654Node: BSD libkvm Interface594078 37655Node: SVR4 Process Information595149 37656Node: DJGPP Native598579 37657Node: Cygwin Native605159 37658Node: Non-debug DLL Symbols609108 37659Node: Hurd Native613656 37660Node: Neutrino618919 37661Node: Darwin619309 37662Node: Embedded OS620567 37663Node: VxWorks621043 37664Node: VxWorks Connection623260 37665Node: VxWorks Download624194 37666Node: VxWorks Attach625929 37667Node: Embedded Processors626327 37668Node: ARM627506 37669Node: M32R/D631627 37670Node: M68K633329 37671Node: MicroBlaze633622 37672Node: MIPS Embedded635072 37673Node: OpenRISC 1000640022 37674Node: PowerPC Embedded642877 37675Node: PA644769 37676Node: Sparclet645058 37677Node: Sparclet File646542 37678Node: Sparclet Connection647422 37679Node: Sparclet Download647900 37680Node: Sparclet Execution648949 37681Node: Sparclite649540 37682Node: Z8000649915 37683Node: AVR651299 37684Node: CRIS651662 37685Node: Super-H652640 37686Node: Architectures653755 37687Node: i386654177 37688Node: A29K654859 37689Node: Alpha655698 37690Node: MIPS655831 37691Node: HPPA659692 37692Node: SPU660211 37693Node: PowerPC662399 37694Node: Controlling GDB663117 37695Node: Prompt663943 37696Node: Editing664722 37697Node: Command History665665 37698Node: Screen Size669069 37699Node: Numbers670903 37700Node: ABI672880 37701Node: Messages/Warnings675809 37702Ref: confirmation requests677235 37703Node: Debugging Output678442 37704Node: Other Misc Settings684361 37705Node: Extending GDB685128 37706Node: Sequences686619 37707Node: Define687214 37708Node: Hooks690827 37709Node: Command Files693194 37710Node: Output698264 37711Node: Python703197 37712Node: Python Commands704052 37713Node: Python API705727 37714Node: Basic Python707386 37715Node: Exception Handling713431 37716Node: Values From Inferior715500 37717Node: Types In Python722554 37718Node: Pretty Printing API730522 37719Node: Selecting Pretty-Printers734421 37720Node: Disabling Pretty-Printers738533 37721Node: Inferiors In Python739407 37722Node: Threads In Python741967 37723Node: Commands In Python743693 37724Node: Parameters In Python752509 37725Node: Functions In Python757265 37726Node: Progspaces In Python759378 37727Node: Objfiles In Python760740 37728Node: Frames In Python762275 37729Node: Blocks In Python765669 37730Node: Symbols In Python767271 37731Node: Symbol Tables In Python772392 37732Node: Breakpoints In Python774051 37733Node: Lazy Strings In Python779022 37734Node: Auto-loading781296 37735Node: objfile-gdb.py file782371 37736Node: .debug_gdb_scripts section783626 37737Node: Which flavor to choose?785003 37738Node: Interpreters786820 37739Node: TUI788919 37740Node: TUI Overview789886 37741Node: TUI Keys792319 37742Node: TUI Single Key Mode794623 37743Node: TUI Commands795498 37744Node: TUI Configuration797882 37745Node: Emacs799178 37746Node: GDB/MI804655 37747Node: GDB/MI General Design806503 37748Node: Context management809026 37749Node: Asynchronous and non-stop modes812161 37750Node: Thread groups814153 37751Node: GDB/MI Command Syntax816431 37752Node: GDB/MI Input Syntax816674 37753Node: GDB/MI Output Syntax818228 37754Node: GDB/MI Compatibility with CLI821800 37755Node: GDB/MI Development and Front Ends822537 37756Node: GDB/MI Output Records824194 37757Node: GDB/MI Result Records824529 37758Node: GDB/MI Stream Records825535 37759Node: GDB/MI Async Records826800 37760Node: GDB/MI Frame Information832925 37761Node: GDB/MI Thread Information834003 37762Node: GDB/MI Simple Examples834941 37763Node: GDB/MI Command Description Format837118 37764Node: GDB/MI Breakpoint Commands837998 37765Node: GDB/MI Program Context855994 37766Node: GDB/MI Thread Commands860262 37767Node: GDB/MI Program Execution863140 37768Node: GDB/MI Stack Manipulation874921 37769Node: GDB/MI Variable Objects885615 37770Ref: -var-set-format895902 37771Ref: -var-list-children897020 37772Ref: -var-update905197 37773Ref: -var-set-frozen907894 37774Ref: -var-set-update-range908690 37775Ref: -var-set-visualizer909220 37776Node: GDB/MI Data Manipulation910717 37777Node: GDB/MI Tracepoint Commands928195 37778Node: GDB/MI Symbol Query935524 37779Node: GDB/MI File Commands936213 37780Node: GDB/MI Target Manipulation939550 37781Node: GDB/MI File Transfer Commands945772 37782Node: GDB/MI Miscellaneous Commands947094 37783Ref: -interpreter-exec956626 37784Node: Annotations958935 37785Node: Annotations Overview959854 37786Node: Server Prefix962317 37787Node: Prompting963051 37788Node: Errors964568 37789Node: Invalidation965464 37790Node: Annotations for Running965941 37791Node: Source Annotations967461 37792Node: JIT Interface968386 37793Node: Declarations970104 37794Node: Registering Code971491 37795Node: Unregistering Code972463 37796Node: GDB Bugs973064 37797Node: Bug Criteria973793 37798Node: Bug Reporting974670 37799Node: Command Line Editing981449 37800Node: Introduction and Notation982101 37801Node: Readline Interaction983721 37802Node: Readline Bare Essentials984910 37803Node: Readline Movement Commands986697 37804Node: Readline Killing Commands987660 37805Node: Readline Arguments989578 37806Node: Searching990620 37807Node: Readline Init File992769 37808Node: Readline Init File Syntax993832 37809Node: Conditional Init Constructs1005764 37810Node: Sample Init File1008295 37811Node: Bindable Readline Commands1011410 37812Node: Commands For Moving1012465 37813Node: Commands For History1013324 37814Node: Commands For Text1016446 37815Node: Commands For Killing1019170 37816Node: Numeric Arguments1021310 37817Node: Commands For Completion1022447 37818Node: Keyboard Macros1023989 37819Node: Miscellaneous Commands1024558 37820Node: Readline vi Mode1027917 37821Node: Using History Interactively1028834 37822Node: History Interaction1029349 37823Node: Event Designators1030771 37824Node: Word Designators1031704 37825Node: Modifiers1033341 37826Node: Formatting Documentation1034566 37827Ref: Formatting Documentation-Footnote-11037959 37828Node: Installing GDB1038055 37829Node: Requirements1038627 37830Ref: Expat1039196 37831Node: Running Configure1041331 37832Node: Separate Objdir1045110 37833Node: Config Names1048090 37834Node: Configure Options1049567 37835Node: System-wide configuration1051937 37836Node: Maintenance Commands1053232 37837Ref: maint info breakpoints1054416 37838Node: Remote Protocol1068451 37839Node: Overview1069034 37840Ref: Binary Data1071605 37841Node: Standard Replies1074182 37842Node: Packets1076048 37843Ref: thread-id syntax1076956 37844Ref: extended mode1078516 37845Ref: bc1080196 37846Ref: bs1080406 37847Ref: read registers packet1081797 37848Ref: cycle step packet1082855 37849Ref: write register packet1084608 37850Ref: step with signal packet1085480 37851Ref: vStopped packet1091762 37852Ref: X packet1092105 37853Ref: insert breakpoint or watchpoint packet1092356 37854Node: Stop Reply Packets1095076 37855Node: General Query Packets1099816 37856Ref: QNonStop1109105 37857Ref: QPassSignals1109729 37858Ref: qSearch memory1111512 37859Ref: QStartNoAckMode1112010 37860Ref: qSupported1112540 37861Ref: multiprocess extensions1121177 37862Ref: qXfer read1125207 37863Ref: qXfer auxiliary vector read1125701 37864Ref: qXfer target description read1126050 37865Ref: qXfer library list read1126494 37866Ref: qXfer memory map read1127140 37867Ref: qXfer sdata read1127526 37868Ref: qXfer siginfo read1127990 37869Ref: qXfer spu read1128386 37870Ref: qXfer threads read1128909 37871Ref: qXfer osdata read1129302 37872Ref: qXfer write1130504 37873Ref: qXfer siginfo write1131061 37874Ref: qXfer spu write1131457 37875Ref: General Query Packets-Footnote-11133544 37876Node: Architecture-Specific Protocol Details1133871 37877Node: Tracepoint Packets1135672 37878Node: Host I/O Packets1152021 37879Node: Interrupts1156163 37880Node: Notification Packets1158066 37881Node: Remote Non-Stop1160339 37882Node: Packet Acknowledgment1164598 37883Node: Examples1166713 37884Node: File-I/O Remote Protocol Extension1167339 37885Node: File-I/O Overview1167801 37886Node: Protocol Basics1169998 37887Node: The F Request Packet1172230 37888Node: The F Reply Packet1173131 37889Node: The Ctrl-C Message1174049 37890Node: Console I/O1175678 37891Node: List of Supported Calls1176895 37892Node: open1177257 37893Node: close1179751 37894Node: read1180133 37895Node: write1180740 37896Node: lseek1181507 37897Node: rename1182385 37898Node: unlink1183781 37899Node: stat/fstat1184720 37900Node: gettimeofday1185607 37901Node: isatty1186042 37902Node: system1186638 37903Node: Protocol-specific Representation of Datatypes1188180 37904Node: Integral Datatypes1188557 37905Node: Pointer Values1189364 37906Node: Memory Transfer1190072 37907Node: struct stat1190692 37908Node: struct timeval1192894 37909Node: Constants1193411 37910Node: Open Flags1193860 37911Node: mode_t Values1194201 37912Node: Errno Values1194693 37913Node: Lseek Flags1195504 37914Node: Limits1195689 37915Node: File-I/O Examples1196049 37916Node: Library List Format1197165 37917Node: Memory Map Format1199929 37918Node: Thread List Format1202489 37919Node: Agent Expressions1203276 37920Node: General Bytecode Design1206097 37921Node: Bytecode Descriptions1210897 37922Node: Using Agent Expressions1222608 37923Node: Varying Target Capabilities1224586 37924Node: Rationale1225748 37925Node: Trace File Format1233134 37926Node: Target Descriptions1235115 37927Node: Retrieving Descriptions1237175 37928Node: Target Description Format1238260 37929Node: Predefined Target Types1247310 37930Node: Standard Target Features1248695 37931Node: ARM Features1250466 37932Node: i386 Features1251958 37933Node: MIPS Features1253062 37934Node: M68K Features1254007 37935Node: PowerPC Features1254670 37936Node: Operating System Information1255954 37937Node: Process list1256792 37938Node: Copying1257854 37939Node: GNU Free Documentation License1295441 37940Node: GDB Index1320603 37941 37942End Tag Table 37943